Merge chore/notify-terminal-preflight into develop

The toast body showed Claude's own message when present and the raw
notification_type otherwise, so permission_prompt and idle_prompt reached
the user as snake_case. Map every event the matcher covers to a readable
label, and keep Claude's message as a suffix when it adds detail.

.claude/memory/journal.md

@@ -456,4 +456,6 @@ rules:
 ## 2026-09-03
 - Attention signal completed + verified end-to-end. Two client faults isolated ([[BLK-020]] resolved): ext instruments only terminals born AFTER activation (re-attach via `dtach -a`, no session loss); Code app volume 0 in Windows mixer killed bell while Windows-emitted toast sound masked it.
 - Coverage gap found + closed: `Notification` matcher covers input-needed only, turn-end had no event. `Stop` wired on same script, branches on `.hook_event_name` ([[BDR-087]], [[LRN-146]]). Verified live: turn-end + AskUserQuestion ring; `permission_prompt` unexercisable under `defaultMode: auto`.
-- BDR-087 + LRN-146 + BLK-020 capitalized. Branch feature/notify-stop-event, UNMERGED (human gate).
+- BDR-087 + LRN-146 + BLK-020 capitalized. Branch feature/notify-stop-event, merged to develop (f90ee74).
+- Post-merge regression: toast dead again after re-attach from a RESTORED terminal, bell fine. Root cause [[LRN-147]]: ext hooks only terminals born after its activation; `enablePersistentSessions` restores terminals before it. Fix = disable persistent sessions, or fresh terminal + `dtach -a`. Verified: 3/3 toasts on fresh pty.
+- Same-day counter-example broke that cause: second session's terminal deaf though created LATER, same window, ext global, shells identical. Trigger unknown; [[LRN-148]] adds the 5s pre-flight test + demotes LRN-147's mechanism claim.

.claude/memory/learnings.md

@@ -1400,3 +1400,17 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s
 - **Pattern**: wire SAME hook script on TWO events — `Notification` (matcher = input-needed set) + `Stop` (fires once per turn end, supports terminalSequence, no matcher). Script branches on `.hook_event_name` when `.message`/`.notification_type` absent: Stop → "Claude has finished responding", else default. Read stdin ONCE into var, jq the var (stdin not re-readable).
 - **Verified**: turn-end bip+toast OK, AskUserQuestion selector bip+toast OK. `permission_prompt` NOT exercisable under `defaultMode: auto` — ask-rules (`python3 -c *`, `curl`…) auto-approved, no prompt raised. Hooks hot-reloaded by file watcher, no restart.
 - **Future**: enumerate the events a signal must cover BEFORE wiring, one per user-visible moment. Notification ≠ lifecycle-complete. SubagentStop exists too for agent completion.
+
+## LRN-147 — VS Code restores terminals BEFORE ext activation → toast dies every restart
+- **Context**: 2026-09-03, second hit same day. Bell OK, toast gone, after user re-attached session from a restored terminal. Probe on that pty: OSC 777 unique + OSC 777 repeated + OSC 9 → all three silent, while BEL rang. Same pty, bell works ⇒ bytes arrive, ext just not hooked to that terminal.
+- **Pattern**: `wenbopan.vscode-terminal-osc-notifier` instruments a terminal only if it exists AFTER ext activation. `terminal.integrated.enablePersistentSessions` (default true) restores terminals at window startup, i.e. BEFORE lazy ext activation → every restored terminal is permanently deaf to OSC. Recurs at each VS Code restart, silently, bell still ringing so it reads as "half broken".
+- **Fix**: client setting `"terminal.integrated.enablePersistentSessions": false` → no terminal pre-exists activation. Fallback without it: after VS Code start, open a FRESH terminal then `dtach -a ~/.dtach/<session>` (dtach broadcasts, old client can stay or be closed, session never lost).
+- **Diagnostic shortcut**: bell rings + toast dead on the SAME pty = terminal-instrumentation fault, not audio, not hook, not server. Bell dead + toast alive = audio fault ([[BLK-020]] fault B). The two channels split the search space; check which one survives before anything else.
+- **Future**: any client-side terminal-parsing ext over Remote-SSH inherits this. Verify instrumentation on the ACTUAL attached pty after every restart, never assume yesterday's terminal.
+
+## LRN-148 — terminal instrumentation is per-terminal + unpredictable; pre-flight test before attaching
+- **Refines**: [[LRN-147]] blamed restored-terminals-born-before-activation. Too narrow — counter-example same day: two terminals SAME VS Code window, pts/3 (born 01:58:33) instrumented, pts/7 (born 01:59:29, LATER) deaf. Ext is GLOBAL (marketplace: Enable/Disable pause parsing extension-wide, no per-terminal setting), shells identical on every server-side measurable: `VSCODE_INJECTION=1`, TERM, TERM_PROGRAM, same `--init-file` shell-integration path, ~2-3s between shell start and dtach. Trigger NOT identified.
+- **Pattern**: treat instrumentation as a per-terminal property that can silently fail for unknown reasons. Cheap pre-flight before committing a long-lived session to a terminal: `printf '\a\a\033]777;notify;NEUF;test\033\\'` typed IN that terminal. Toast → instrumented, attach. Bell only → deaf terminal, open another. Costs 5s, replaces an hour of pty archaeology.
+- **Recovery**: deaf terminal never repairs. Open fresh terminal, pre-flight it, `dtach -a ~/.dtach/<session>`. dtach broadcasts, so old client may stay attached; session never at risk.
+- **Diagnostic split (holds)**: bell alive + toast dead = terminal instrumentation. Toast alive + bell dead = client audio ([[BLK-020]]). Neither = bytes never arrive.
+- **Future**: do NOT assert the born-before-activation cause as established — it fits the first incident, not the second. Unknown trigger is the honest state.

hooks/notify-attention.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # Notification + Stop hook — signal the user through the terminal when
-# Claude needs input (permission prompt, question, idle wait) or has
+# Claude needs input (permission, question, idle wait) or has finished
-# finished responding.
+# responding. Each case gets its own readable label so the toast says
+# which one fired.
 #
 # Runs on the remote (Linux); the only channel that crosses SSH into the
 # VS Code client is the terminal stream. Hooks have no controlling TTY,
@@ -12,27 +13,34 @@
 #     volume for Code in the Windows volume mixer (BLK-020).
 #   - OSC 777 notify -> Windows toast via the client-side extension
 #     "Terminal Notification" (wenbopan.vscode-terminal-osc-notifier).
-#     The extension only instruments terminals created AFTER it is
+#     A terminal can be deaf to OSC while the bell still rings; test it
-#     active: install it first, then start or re-attach the session.
+#     before attaching a session to it (LRN-148).
 # Both are invisible no-ops in terminals that ignore them.
 set -u
 
 payload=$(cat 2>/dev/null)
 read_field() {
   printf '%s' "$payload" | jq -r "$1 // empty" 2>/dev/null \
-    | tr -d '\000-\037' | cut -c1-200
+    | tr -d '\000-\037' | cut -c1-160
 }
 
-msg=$(read_field '.message // .notification_type')
+event=$(read_field '.notification_type')
-if [ -z "$msg" ]; then
+[ -n "$event" ] || event=$(read_field '.hook_event_name')
-  case "$(read_field '.hook_event_name')" in
+
-    Stop) msg="Claude has finished responding" ;;
+case "$event" in
-    *) msg="Claude Code needs your input" ;;
+  Stop) label="Finished responding" ;;
+  permission_prompt) label="Needs your permission" ;;
+  agent_needs_input) label="Asks you a question" ;;
+  idle_prompt) label="Waiting for you" ;;
+  elicitation_dialog|elicitation_url_dialog) label="Needs your input" ;;
+  *) label="Needs your attention" ;;
 esac
-fi
+
+detail=$(read_field '.message')
+[ -z "$detail" ] || label="${label}: ${detail}"
 
 bell=$(printf '\a')
 esc=$(printf '\033')
-seq="${bell}${bell}${esc}]777;notify;Claude Code;${msg}${esc}\\"
+seq="${bell}${bell}${esc}]777;notify;Claude Code;${label}${esc}\\"
 jq -cn --arg seq "$seq" '{suppressOutput: true, terminalSequence: $seq}'
 exit 0