chore(todo): checkpoint helper-instance — detection+contract done, wiring next

1 files changed, 18 insertions, 0 deletions

diff --git a/todo.org b/todo.org
index 43f6d2a..4525e0c 100644
--- a/todo.org
+++ b/todo.org
@@ -64,6 +64,24 @@ Implement Phase 1.5 of the generic-agent-runtime spec ([[file:docs/design/2026-0
 
 Independent of the spec's phases 2-6 (runtime-neutral refactor), which stay gated on their own go/no-go.
 
+*** 2026-06-15 progress — detection + contract landed (inert); wiring is what's left
+RESUME NOTE. Before picking this back up as the big item, re-read what it is, does, and why first — don't dive straight into the next slice. The orientation, in one breath: this lets Craig open a second Claude in the *same project* while a primary session is running (a second terminal, to look something up or make a small task edit) without the two sessions clobbering each other's files. The whole risk it manages is two Edit-tool writers on one shared file (todo.org, notes.org) losing each other's writes, last-write-wins, silently. The design's answer: a singleton primary keeps the unisolated session-context.org; helpers get their own session-context.d/<id>.org, make only scoped single-heading edits to shared files, and never touch git. Full why-and-how in the spec ([[file:docs/design/2026-05-28-generic-agent-runtime-spec.org]], "Concurrent same-project agents" amendment) and the contract ([[file:.ai/workflows/helper-mode.org]]). A helper is NOT a subagent — subagents are for bounded dispatched lookups; this is for interactive parallel work Craig drives himself.
+
+Done so far (shipped, pushed, inert until wiring routes to them):
+- agent-roster (commit f8bdf30): the detection primitive. pgrep -x claude → /proc cwd → keep in-project → drop own ancestry. Exit 0 alone / 1 others / 2 unavailable. Injectable boundary (ROSTER_PGREP/PROC/SELF_PID), 11 bats, live-verified against 4 real sessions. [[file:.ai/scripts/agent-roster]].
+- helper-mode.org (commit 0b681dc): the canonical contract — read/write tiers, four data-integrity rules, light startup, helper wrap-up. Triggerless INDEX entry, protocols.org pointer.
+- Already shipped earlier: the AI_AGENT_ID + session-context.d/ split, and (2026-06-14) the epoch-on-the-tail id convention.
+
+What's next — the WIRING, all behind the spec's three-ring gate (bats → sandbox drills → live pilot), none of it sync'd to live template paths until the two-session drill passes:
+- Startup roster-detection branch: roster runs first; not-alone routes to helper-mode.org, alone keeps crashed-vs-fresh anchor logic. (Edits startup.org — synced, gated.)
+- wrap-it-up.org helper branch (archive own file, skip hygiene+commit; orphaned-helper lifts the git ban).
+- ai --helper launcher: roster → assign+export id → launch with helper opener. Plus the Emacs surface (ai-term.el) via an .emacs.d cross-project handoff.
+- Hygiene-pass live-helper gate: todo-cleanup.el / lint-org.el / wrap-org-table.el check session-context.d/ and pause+ask on live helper files.
+- todo-cleanup.el backup-to-/tmp backstop (lint-org and wrap-org-table already conform).
+- Manual validation drills with Craig (the live two-session test + the corruption drill).
+
+Stand up a drill rig before the gated work; build against it, don't touch synced paths until the live drill passes.
+
 ** DOING [#C] Check that memories are sync'd across machines via git :spec:
 :PROPERTIES:
 :LAST_REVIEWED: 2026-06-12