From d8de295cb06cd3f43f3700df9861e8ec201607ef Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 22 Feb 2026 19:02:56 -0800
Subject: [PATCH] Document per-session cached audio clear procedure

---
 README.md                                  |  1 +
 TOOLS.md                                   | 25 ++++++++++++++++++++++
 docs/plans/state.json                      | 12 +++++++++++
 docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md | 18 ++++++++++++++++
 4 files changed, 56 insertions(+)

diff --git a/README.md b/README.md
index bbb0a04..9190d09 100644
--- a/README.md
+++ b/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`.
 
diff --git a/TOOLS.md b/TOOLS.md
index 7ff2eaf..db06ed5 100644
--- a/TOOLS.md
+++ b/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.
diff --git a/docs/plans/state.json b/docs/plans/state.json
index 37f42c8..a461489 100644
--- a/docs/plans/state.json
+++ b/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": {
diff --git a/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md b/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md
index 84917a3..4bb20da 100644
--- a/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md
+++ b/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.