Document per-session cached audio clear procedure

README.md

@@ -432,6 +432,7 @@ Audio persistence and diagnostics:
 
 - Latest inbound voice bytes are stored per-session in `~/.local/share/flynn/sessions.db` under `session_config.key = "lastAudioAttachment"` (used to safely hydrate `audio.transcribe` calls).
 - `/reset` clears session history and session config for that chat, including `lastAudioAttachment`.
+- To clear one session manually: `DELETE FROM session_config WHERE session_id='<channel:sender>' AND key='lastAudioAttachment'`.
 - When Flynn rewrites bad model-provided audio tool args, it emits audit event `tool.args_rewritten`.
 - Runbook: `docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md`.
 

TOOLS.md

@@ -36,6 +36,31 @@ Contract enforcement:
 - Scratch space: `/tmp`
 - Use runtime tool definitions as source of truth for currently available tools.
 
+## Audio Cache Management (Session Config)
+
+When asked to clear cached voice audio for one chat/session:
+
+1. Identify session id (example: `telegram:8367012007`).
+2. Delete only that session's `lastAudioAttachment` key.
+3. Verify row removal.
+4. Report exact command evidence and whether rows remain.
+
+Commands:
+
+```bash
+# Clear one session's cached voice attachment
+sqlite3 ~/.local/share/flynn/sessions.db \
+  "DELETE FROM session_config WHERE session_id='<channel:sender>' AND key='lastAudioAttachment';"
+
+# Verify remaining cached audio entries
+sqlite3 ~/.local/share/flynn/sessions.db \
+  "SELECT session_id,key,length(value) FROM session_config WHERE key='lastAudioAttachment';"
+```
+
+Notes:
+- `/reset` for that chat also clears session config (including `lastAudioAttachment`).
+- Do not delete other session_config keys unless explicitly requested.
+
 ## Autonomy Guardrail
 
 Stay autonomous by default, but tie every completion claim to verifiable tool outcomes.

docs/plans/state.json

@@ -6040,6 +6040,18 @@
         "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md"
       ],
       "test_status": "pnpm test:run src/backends/native/agent.test.ts src/daemon/routing.test.ts src/tools/builtin/audio-transcribe.test.ts src/tools/executor.test.ts; pnpm typecheck; pnpm build"
+    },
+    "audit-followup-audio-cache-clear-procedure": {
+      "status": "completed",
+      "date": "2026-02-23",
+      "updated": "2026-02-23",
+      "summary": "Documented deterministic per-session cached audio cleanup procedure so Flynn can clear one session cached lastAudioAttachment safely on request.",
+      "files_modified": [
+        "TOOLS.md",
+        "README.md",
+        "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md"
+      ],
+      "test_status": "docs-only update; no runtime code changes"
     }
   },
   "overall_progress": {

docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md

@@ -83,6 +83,24 @@ sqlite3 ~/.local/share/flynn/sessions.db \
   "SELECT session_id,key,length(value) FROM session_config WHERE key='lastAudioAttachment';"
 ```
 
+### Clear Cached Audio for One Session
+
+Delete only one chat/session cache entry (example session id: `telegram:8367012007`):
+
+```bash
+sqlite3 ~/.local/share/flynn/sessions.db \
+  "DELETE FROM session_config WHERE session_id='telegram:8367012007' AND key='lastAudioAttachment';"
+```
+
+Verify:
+
+```bash
+sqlite3 ~/.local/share/flynn/sessions.db \
+  "SELECT session_id,key,length(value) FROM session_config WHERE key='lastAudioAttachment';"
+```
+
+If `/reset` is run in that chat, it also clears the session's `lastAudioAttachment` row.
+
 ## Data Lifecycle
 
 - `session.clear()` (e.g. `/reset`) removes messages, tool executions, and session config for that session.