chore(ai): archive session record, note helper-instance resume plan

1 files changed, 61 insertions, 0 deletions

diff --git a/.ai/sessions/2026-06-15-08-43-czsusp-epoch-helper-instance-slices.org b/.ai/sessions/2026-06-15-08-43-czsusp-epoch-helper-instance-slices.org
new file mode 100644
index 0000000..7d150d5
--- /dev/null
+++ b/.ai/sessions/2026-06-15-08-43-czsusp-epoch-helper-instance-slices.org
@@ -0,0 +1,61 @@
+#+TITLE: Session Context
+#+DATE: 2026-06-14
+
+* Summary
+
+** Active Goal
+
+Fix an accidental C-z that suspended Claude, clear two interrupted 2026-06-13 session anchors, document the helper-agent epoch-id convention, then start the helper-instance support feature (#B) — shipping its first two slices.
+
+** Decisions
+
+- C-z suspend: scope the disable to ai-launched panes only (stty susp undef in the launcher), not globally. Keybindings.json can't touch it — C-z is raw tty SIGTSTP, not a Claude Code keybinding.
+- Helper-agent id uniqueness: epoch lives in AI_AGENT_ID, baked in by the spawner, convention-only. It can't be minted inside session-context-path (the resolver must return the same path across many calls per session).
+- For the rest of the session: commit and push together, don't hold pushes (Craig).
+- Helper-instance build order: agent-roster first (the detection primitive), then helper-mode.org (the contract); both inert. The behavior-changing wiring stays behind the spec's bats→drills→pilot gate.
+- agent-roster exit codes 0=alone / 1=others / 2=unavailable; pgrep-absent hardened to exit 2 (never silent-alone) after a review Minor.
+
+** Data Collected / Findings
+
+- Real terminal is foot → tmux → Claude (not "ghostel"; ghostel is the separate Emacs-native terminal, per the spec).
+- agent-roster live-verified against 4 concurrent real sessions: alone in rulesets (own session excluded via ancestry, 3 out-of-project claudes excluded by cwd), not-alone in ~/.emacs.d (2 agents listed).
+- helper-mode.org orphan-drift wrinkle solved by a triggerless INDEX catalog entry (startup.org's existing pattern) — no integrity-checker or startup.org change.
+
+** Files Modified
+
+- claude-templates/bin/ai — LAUNCH_PREFIX="stty susp undef; " at the three launch sites (C-z fix). Commit dedbca3.
+- .ai/sessions/2026-06-13-* (x2) + notes.org marker — archived yesterday's interrupted anchors. Commit 16e64fb.
+- protocols.org + wrap-it-up.org + session-context-path header — epoch-on-tail convention. Commit e0f914d.
+- .ai/scripts/agent-roster + tests (canonical+mirror) — detection primitive, 11 bats. Commit f8bdf30.
+- .ai/workflows/helper-mode.org (new) + INDEX.org + protocols.org pointer — helper contract. Commit 0b681dc.
+- todo.org — helper-instance DOING + resume note + Craig's open question. Commits 25bde1f-era flip, bef1d66, and wrap.
+
+** Next Steps
+
+Helper-instance is the big item next session. Re-orient on what it is/does/why before building (resume note in the helper-instance task body). Answer Craig's open question first: does helper-instance depend on the generic-agent-runtime work, or is Phase 1.5 genuinely independent of phases 2-6? Then the gated wiring: startup roster branch, wrap-it-up helper branch, ai --helper launcher (+ Emacs surface via .emacs.d handoff), hygiene live-helper gate, todo-cleanup.el /tmp backstop — all behind the drill rig.
+
+KB: promoted 0 / consulted no
+
+* Session Log
+
+** 2026-06-14 Sun @ 17:52 CDT — Startup, then disable C-z suspend in ai-launched Claude panes
+
+New session (2026-06-14). Startup found two un-wrapped 2026-06-13 anchors (the main session-context.org + session-context.d/codex.org) with all work already pushed; offered cleanup but Craig pivoted to a live problem: he accidentally hit C-z during the session, suspending Claude to the shell. Wants C-z's suspend disabled but scoped, not nuked machine-wide.
+
+Diagnosed the layers: foot (terminal) → tmux → Claude Code. tmux has no root C-z binding, so C-z passes through to the pane's tty, which generates SIGTSTP. Confirmed via the keybindings skill that ctrl+z is NOT a Claude Code keybinding action — it's listed under Reserved Shortcuts as Unix SIGTSTP, no action mapped — so keybindings.json can't touch it. Fix has to be at the tty layer (stty susp undef).
+
+Craig picked launcher-scoped over global zshrc. Edited claude-templates/bin/ai: added a commented LAUNCH_PREFIX="stty susp undef; " var after CLAUDE_CMD, prepended it at all three tmux send-keys launch sites (lines ~76, ~321, ~381). Scopes the disable to exactly the ai-launched Claude pane; C-z keeps working everywhere else. Verified: bash -n clean, all three sites carry the prefix, stty susp undef in a real pty leaves susp = <undef>. Live now via the ~/.local/bin/ai symlink, but only for NEW ai-launched sessions — the current running session keeps its old tty setting. /review-code Approve, /voice personal walk, committed dedbca3 (unpushed). Note: with susp undef the 0x1a byte now reaches Claude as input (no binding → expected to be ignored).
+
+Then Craig's task order: (2) commit the C-z fix [done, dedbca3], (3) clean up yesterday's two un-wrapped anchors, (1) return to the epoch-suffix thread. Cleanup: split yesterday's shipped 12:11 session out of this anchor into .ai/sessions/2026-06-13-12-11-inbox-zero-build-and-session-title.org (Summary populated), archived the codex sub-session to .ai/sessions/2026-06-13-15-29-codex-inbox-ack.org and removed session-context.d/codex.org, reset this anchor to today only.
+
+Then the epoch thread (task 1). Lost the original design in the crash, so reconstructed from code and surfaced the determinism constraint (session-context-path is called many times per session and must return the same path, so it can't mint date +%s; the Bash tool also drops env between calls, so the agent can't export once). Craig picked option 1: epoch baked into AI_AGENT_ID by the spawner, convention-only, no resolver change. Documented the convention in three canonical spots (protocols.org Agent-scoped path, wrap-it-up.org recommended-shape note, session-context-path header comment), with the 2026-06-13 codex collision as the worked example. sync-check --fix paired the mirror; session-context-path.bats still 5/5 green (comment-only). /review-code Approve, /voice personal walk, committed e0f914d.
+
+Session commits: dedbca3 (C-z fix), 16e64fb (archive yesterday's two anchors + inbox marker), e0f914d (epoch convention docs). Pushed bbd07b6..e0f914d. Craig then set "commit and push together for the rest of this session."
+
+Then started the helper-instance task (#B, DOING) via start-work, first slice only: the agent-roster detection script. Built claude-templates/.ai/scripts/agent-roster + tests/agent-roster.bats (11 tests), synced to mirror. Algorithm per spec: pgrep -x claude, /proc cwd resolution, cwd-within-root filter, self-ancestry exclusion. Exit 0 alone / 1 others / 2 unavailable. pgrep + /proc + self-pid injectable (ROSTER_PGREP/PROC/SELF_PID) so bats run the real filter against fixtures, no agents spawned. TDD red→green. Live-verified against the real process tree: alone in rulesets (own session excluded via ancestry, 3 out-of-project claudes excluded by cwd, exit 0), not-alone against ~/.emacs.d (2 live agents listed, exit 1). /review-code flagged one Minor (pgrep-absent read as silent-alone, violating the spec's never-silent-alone invariant); hardened it with a command -v guard → exit 2 (TDD red→green, 11th test). make test exit 0 (180 ok). Committed f8bdf30, pushed e0f914d..f8bdf30. todo task stays DOING (epic; slice 1 of ~7 done).
+
+Slice 2: helper-mode.org workflow contract (the spec's "single canonical home" of helper rules). Authored claude-templates/.ai/workflows/helper-mode.org — Overview + subagent boundary, When-to-Use (no trigger, three routing paths), Identity (helper-<rand4>, self-assign, recorded as first line of .d/ file), four read/write tiers, four data-integrity rules + inbox-send slug nit, Light Startup, Helper Wrap-Up (orphaned-helper lifts git ban), Status (wiring gated/not-live). Solved the orphan-drift-check wrinkle via a triggerless INDEX catalog entry (startup.org's pattern) — no integrity-checker or startup.org change. Added protocols.org one-paragraph pointer. Synced mirror. workflow-integrity OK (45 workflows), make test exit 0 (180 ok), /review-code Approve. Committed 0b681dc, pushed f8bdf30..0b681dc.
+
+Remaining slices, all behind the spec's bats→drills→pilot gate (change live session behavior in synced paths): startup roster-detection branch, wrap-it-up helper branch, ai --helper launcher (+ ai-term.el via .emacs.d handoff), hygiene-pass live-helper gate, todo-cleanup.el /tmp backstop.
+
+Stopped here for the session (Craig's call). Durable resume note filed in the helper-instance task body in todo.org — what it is/does/why plus done-vs-next — flagged to re-orient on the feature's purpose before picking it up as the big item next session. The wiring is the gated, drill-rig half. Not a full wrap-up; this anchor stays live.