feat(suspend): detach the tmux client as the final step of every suspend

A suspend now ends by detaching the tmux client viewing the aiv-<project> session, so the parked session drops out of the alt-space rotation instead of cluttering it. Detach is not teardown: the session and agent process stay alive in the background and only the view disconnects, so it runs inline as the last action (the handoff text is preserved in the pane and shown on re-attach) rather than deferring to a Stop hook the way the session-killing teardown must. Degrades gracefully when not in tmux.

Originated in archsetup as a local stopgap and reconciled to canonical here.

3 files changed, 76 insertions, 13 deletions

diff --git a/.ai/workflows/suspend.org b/.ai/workflows/suspend.org
index 3691f60..166f9c9 100644
--- a/.ai/workflows/suspend.org
+++ b/.ai/workflows/suspend.org
@@ -23,8 +23,10 @@ straight:
   Refreshes the anchor in place, prompts Craig to type =/clear=, and a hook
   resumes the *same* logical session in a fresh context. Craig is still here.
 - *suspend* (this workflow) — *leave.* Captures richly into the anchor, leaves
-  the file in place, and Craig walks away. The next session is a cold startup
-  that detects the present anchor and resumes from it.
+  the file in place, detaches the tmux client so the session parks in the
+  re-attachable set, and Craig walks away. The next session is a cold startup
+  that detects the present anchor and resumes from it — or Craig re-attaches the
+  still-live session directly.
 - =wrap-it-up= ([[file:wrap-it-up.org][wrap-it-up.org]]) — *end.* Writes the
   Summary, archives the anchor into =.ai/sessions/=, commits + pushes, and runs
   the phrase-dependent teardown.
@@ -91,7 +93,32 @@ when the Summary body is from an earlier thread.
    that set — but the default shared behavior is to leave the tree alone.)
 4. *Leave =.ai/session-context.org= in place.* Do not archive it.
 5. *Brief handoff* — one or two lines: what was captured, where the resume
-   pointer is, the most-active thread. End and let Craig go.
+   pointer is, the most-active thread. This is the last thing Craig sees before
+   the view detaches (Step 6), so deliver it complete.
+6. *Detach the tmux client.* As the final action, detach the client viewing the
+   =aiv-<project>= session so it drops out of Craig's active view while staying
+   alive in the background. This is a DETACH, not a teardown: the session and the
+   agent process keep running, nothing is killed, no context is lost.
+
+   #+begin_src bash
+   sess=$(tmux display-message -p '#S' 2>/dev/null)
+   [ -n "$sess" ] && tmux detach-client -s "$sess"
+   #+end_src
+
+   Run it as the very last tool call, after the handoff text has rendered — tmux
+   preserves the pane, so Craig sees the full handoff when he re-attaches. Unlike
+   wrap-up's teardown (which must defer to a =Stop= hook because it kills the
+   session the agent runs in, which would cut off the valediction), detach runs
+   inline: it disconnects the view but leaves the agent's session alive, so
+   nothing is cut off. Degrade gracefully — if not inside tmux (=$TMUX= unset, no
+   session), skip silently and the session simply stays attached.
+
+   Why detach on every suspend: Craig cycles his live agent sessions in Emacs
+   with alt-space, and rotates through everything — including re-attaching
+   detached ai-term sessions — with shift+alt+space. A suspended session left
+   attached clutters the active rotation; detaching parks it in the
+   re-attachable set, which is what makes suspend-and-walk-away work. Re-attach
+   is one keystroke (shift+alt+space) or =tmux attach -t aiv-<project>=.
 
 * What suspend does NOT do
 
@@ -103,8 +130,12 @@ does beyond capture:
 - No KB / memory promotion sweep.
 - No Linear / board reconciliation.
 - No session-record archive (the file stays live).
-- No teardown (the ai-term buffer + tmux session stay up). It drops no
-  =Stop=-hook teardown sentinel, so the wrap-teardown hook stays dormant.
+- No teardown. Suspend DETACHES the tmux client (Step 6) but never kills the
+  session: the =aiv-<project>= session and the agent process stay alive in the
+  background, only the view disconnects. It drops no =Stop=-hook teardown
+  sentinel, so the wrap-teardown hook stays dormant. Teardown — killing the
+  session — is wrap-it-up's job, not suspend's; detach is the lighter move that
+  parks a still-live session.
 - No blind commit of working files (step 3).
 - No valediction. A suspend is a pause, not a goodbye.
 
diff --git a/claude-templates/.ai/workflows/suspend.org b/claude-templates/.ai/workflows/suspend.org
index 3691f60..166f9c9 100644
--- a/claude-templates/.ai/workflows/suspend.org
+++ b/claude-templates/.ai/workflows/suspend.org
@@ -23,8 +23,10 @@ straight:
   Refreshes the anchor in place, prompts Craig to type =/clear=, and a hook
   resumes the *same* logical session in a fresh context. Craig is still here.
 - *suspend* (this workflow) — *leave.* Captures richly into the anchor, leaves
-  the file in place, and Craig walks away. The next session is a cold startup
-  that detects the present anchor and resumes from it.
+  the file in place, detaches the tmux client so the session parks in the
+  re-attachable set, and Craig walks away. The next session is a cold startup
+  that detects the present anchor and resumes from it — or Craig re-attaches the
+  still-live session directly.
 - =wrap-it-up= ([[file:wrap-it-up.org][wrap-it-up.org]]) — *end.* Writes the
   Summary, archives the anchor into =.ai/sessions/=, commits + pushes, and runs
   the phrase-dependent teardown.
@@ -91,7 +93,32 @@ when the Summary body is from an earlier thread.
    that set — but the default shared behavior is to leave the tree alone.)
 4. *Leave =.ai/session-context.org= in place.* Do not archive it.
 5. *Brief handoff* — one or two lines: what was captured, where the resume
-   pointer is, the most-active thread. End and let Craig go.
+   pointer is, the most-active thread. This is the last thing Craig sees before
+   the view detaches (Step 6), so deliver it complete.
+6. *Detach the tmux client.* As the final action, detach the client viewing the
+   =aiv-<project>= session so it drops out of Craig's active view while staying
+   alive in the background. This is a DETACH, not a teardown: the session and the
+   agent process keep running, nothing is killed, no context is lost.
+
+   #+begin_src bash
+   sess=$(tmux display-message -p '#S' 2>/dev/null)
+   [ -n "$sess" ] && tmux detach-client -s "$sess"
+   #+end_src
+
+   Run it as the very last tool call, after the handoff text has rendered — tmux
+   preserves the pane, so Craig sees the full handoff when he re-attaches. Unlike
+   wrap-up's teardown (which must defer to a =Stop= hook because it kills the
+   session the agent runs in, which would cut off the valediction), detach runs
+   inline: it disconnects the view but leaves the agent's session alive, so
+   nothing is cut off. Degrade gracefully — if not inside tmux (=$TMUX= unset, no
+   session), skip silently and the session simply stays attached.
+
+   Why detach on every suspend: Craig cycles his live agent sessions in Emacs
+   with alt-space, and rotates through everything — including re-attaching
+   detached ai-term sessions — with shift+alt+space. A suspended session left
+   attached clutters the active rotation; detaching parks it in the
+   re-attachable set, which is what makes suspend-and-walk-away work. Re-attach
+   is one keystroke (shift+alt+space) or =tmux attach -t aiv-<project>=.
 
 * What suspend does NOT do
 
@@ -103,8 +130,12 @@ does beyond capture:
 - No KB / memory promotion sweep.
 - No Linear / board reconciliation.
 - No session-record archive (the file stays live).
-- No teardown (the ai-term buffer + tmux session stay up). It drops no
-  =Stop=-hook teardown sentinel, so the wrap-teardown hook stays dormant.
+- No teardown. Suspend DETACHES the tmux client (Step 6) but never kills the
+  session: the =aiv-<project>= session and the agent process stay alive in the
+  background, only the view disconnects. It drops no =Stop=-hook teardown
+  sentinel, so the wrap-teardown hook stays dormant. Teardown — killing the
+  session — is wrap-it-up's job, not suspend's; detach is the lighter move that
+  parks a still-live session.
 - No blind commit of working files (step 3).
 - No valediction. A suspend is a pause, not a goodbye.
 
diff --git a/todo.org b/todo.org
index ea69ba4..de5dcc9 100644
--- a/todo.org
+++ b/todo.org
@@ -200,10 +200,11 @@ Three considerations captured by .emacs.d's own hand-run sentry trial (routed vi
 
 Take up with the sentry Living Document refinements once the trial has quiet nights behind it. Related: the sentry /schedule variant above, and Fire 1's triage-probe finding in the approval queue.
 
-** TODO [#C] Apply suspend.org detach-on-suspend change to canonical :feature:
-Craig's change relayed from archsetup (2026-07-20, applied there as a stopgap): add Step 6 to suspend.org — detach the tmux client (=tmux detach-client -s "$sess"=) as the final action of every suspend, so a suspended session parks in the re-attachable set instead of cluttering the alt-space rotation. Also reword the neighbors bullet and the "does NOT do" teardown bullet to draw the detach-vs-teardown line.
+** DONE [#C] Apply suspend.org detach-on-suspend change to canonical :feature:
+CLOSED: [2026-07-20 Mon]
+Craig's change relayed from archsetup (2026-07-20): add Step 6 to suspend.org — detach the tmux client (=tmux detach-client -s "$sess"=) as the final action of every suspend, so a suspended session parks in the re-attachable set instead of cluttering the alt-space rotation. Also reworded the neighbors bullet and the "does NOT do" teardown bullet to draw the detach-vs-teardown line.
 
-Reviewed and recommended-apply: clean, low-risk, detach is not teardown (session + agent stay alive, only the view disconnects), graceful when not in tmux, no hook/settings/test surface. The exact diff is archsetup's proposed file (parked at inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend.org). To apply: patch =claude-templates/.ai/workflows/suspend.org=, run sync-check --fix, commit. One-word go from Craig.
+Applied to canonical 2026-07-20 (verified the diff was exactly the intended change, canonical + mirror synced, lint clean bar one pre-existing flush/SKILL.md link). Replied to archsetup that its local stopgap is now canonical.
 
 ** TODO [#B] Extend ui-prototyping rule with build-to-prototype :feature:
 :PROPERTIES: