diff options
| -rw-r--r-- | inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend-workflow-change-detach-the-tmux.org | 16 | ||||
| -rw-r--r-- | inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend.org | 143 | ||||
| -rw-r--r-- | todo.org | 5 |
3 files changed, 164 insertions, 0 deletions
diff --git a/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend-workflow-change-detach-the-tmux.org b/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend-workflow-change-detach-the-tmux.org new file mode 100644 index 0000000..9348a50 --- /dev/null +++ b/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend-workflow-change-detach-the-tmux.org @@ -0,0 +1,16 @@ +#+TITLE: Suspend workflow change — detach the tmux client on every su +#+SOURCE: from archsetup +#+DATE: 2026-07-20 08:47:17 -0500 + +Suspend workflow change — detach the tmux client on every suspend. Applied locally in archsetup as a stopgap (startup sync overwrites it); please apply to the canonical claude-templates/.ai/workflows/suspend.org. The edited file is attached alongside this note. + +What changed: added Step 6 to suspend.org. After the brief handoff, detach the tmux client viewing the aiv-<project> session as the very last tool call: + sess=$(tmux display-message -p '#S' 2>/dev/null) + [ -n "$sess" ] && tmux detach-client -s "$sess" +Also updated the 'Where suspend sits among its neighbors' bullet and the 'What suspend does NOT do' section to draw the detach-vs-teardown line. + +Key distinction: detach is NOT teardown. wrap-it-up's teardown KILLS the aiv-<project> session (and must defer to the Stop hook because it kills the session the agent runs in, which would cut the valediction). Suspend's detach leaves the session and the agent process ALIVE in the background and only disconnects the view, so it can run inline as the final action — the handoff text is preserved in the tmux pane and shown on re-attach. Degrade gracefully when not in tmux ($TMUX unset -> skip, session stays attached). + +Why: Craig now cycles 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. So every suspension should end in a detach. + +Companion files: suspend.org is the only change. No hook / settings.json change needed (detach needs no deferred hook, unlike teardown). wrap-it-up.org is unaffected — its teardown section is the contrast the new suspend text references, no edit required. diff --git a/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend.org b/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend.org new file mode 100644 index 0000000..166f9c9 --- /dev/null +++ b/inbox/PROCESSED-2026-07-20-0847-from-archsetup-suspend.org @@ -0,0 +1,143 @@ +#+TITLE: Session Suspend Workflow +#+AUTHOR: Craig Jennings +#+DATE: 2026-06-28 + +* Overview + +This workflow captures the live state of a session when Craig must leave +abruptly, so a future session resumes with nothing lost. It is the fast, +capture-only workflow for departure: it writes down where every thread stands, +notes any uncommitted work, then STOPS — no cleanup, no archive, no teardown. + +Triggered by Craig saying "suspend the session," "suspend," "I need to go," +"stick a pin in everything," or similar. "I need to go" is broad — if it reads +as a conversational aside rather than a request to suspend, confirm before +running. + +* Where suspend sits among its neighbors + +Three workflows touch the session anchor (=.ai/session-context.org=); keep them +straight: + +- =flush= ([[file:../../flush/SKILL.md]] / =/flush=) — *stay and sharpen.* + 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, 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. + +Suspend and flush share one core — capture into the anchor, leave it in place. +They differ in the exit (leave vs clear-and-continue) and the resume path +(startup vs the =/clear= hook). Suspend reuses flush's capture discipline (its +Phase 1 anchor-refresh) rather than restating it, and adds a richer, +resume-weighted Session Log entry because it's written for a cold resume after a +gap, not a same-session reset. + +* Suspend vs wrap-up — the one structural difference + +=wrap-it-up= ARCHIVES =.ai/session-context.org= (renames it into +=.ai/sessions/=); its absence at the next startup is the signal that the last +session ended cleanly. + +Suspend does the opposite: it LEAVES =.ai/session-context.org= in place. Its +presence at startup is exactly the signal that the previous session was +interrupted, so the startup workflow reads it and resumes. Suspend provides only +the *capture* half — startup's existing interrupted-session path (Phase A checks +for the anchor, Phase B reads it, Phase C offers to resume) is the *resume* half, +already built. + +So: never archive, never rename the context file in a suspend. Capture into it +and leave it. + +* What gets captured + +The point is zero lost information, weighted toward RESUME. Into the +=* Session Log= of =.ai/session-context.org=, append one dated +=** YYYY-MM-DD ... — SUSPENDED= entry holding: + +1. *Open threads — resume here.* For each active or pending thread: the topic, + its status (ACTIVE / PINNED / SET ASIDE / DEFERRED), the immediate next + step, and the pointers needed to act on it cold (files + line numbers, + commit SHAs, the specific finding or decision). This is the core; spend the + most words here. Order newest / most-active first. +2. *Pending decisions / open questions* awaiting Craig — anything blocked on + his input, with enough context that the answer is actionable. +3. *Shipped this session* — a terse list of what landed, each with its commit + SHA, so the resume knows what is already done and need not re-derive it. +4. *Uncommitted work* — anything modified on disk but not committed, named + file by file, so the resume knows what state the tree is in. +5. *Key findings not yet recorded elsewhere* — anything learned this session + that isn't already in a commit, a file, or memory, so it survives. +6. *Background work* — any running task, agent, or job, and how to check it. +7. *Resume hint* — the single most likely "start here" next action. + +Also update the top of =* Summary= (Active Goal) with a one-line SUSPENDED +pointer to the entry, so startup reading the top sees the current state even +when the Summary body is from an earlier thread. + +* Steps + +1. *Write the SUSPENDED entry* into the Session Log, per "What gets captured" + above. Timestamp with =date "+%Y-%m-%d %a @ %H:%M:%S %z"=. +2. *Update the Active Goal pointer* at the top of =* Summary=. +3. *Record uncommitted work, don't force-commit it.* A suspend records state, it + does not tidy it. Name every uncommitted change in the SUSPENDED entry and + leave the tree as it is — on an abrupt departure, a dirty tree (like any + crash) is safer than a blind commit of arbitrary mid-work state. (If a + project defines a standing always-commit set in its own workflow, commit only + 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. 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 + +Speed over completeness. A suspend deliberately skips everything wrap-it-up +does beyond capture: + +- No =* Summary= rewrite beyond the one-line Active Goal pointer. +- No todo.org cleanup / archive-done. +- No KB / memory promotion sweep. +- No Linear / board reconciliation. +- No session-record archive (the file stays live). +- 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. + +If Craig later wants the clean end, he runs wrap-it-up, which picks up the +captured state and finishes the job. @@ -201,6 +201,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. + +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. + ** TODO [#B] Extend ui-prototyping rule with build-to-prototype :feature: :PROPERTIES: :CREATED: [2026-07-11 Sat] |