docs(spec): record the three confirmed helper-design decisions

1 files changed, 33 insertions, 22 deletions

diff --git a/docs/design/2026-05-28-generic-agent-runtime-spec.org b/docs/design/2026-05-28-generic-agent-runtime-spec.org
index e3651f9..40a97b4 100644
--- a/docs/design/2026-05-28-generic-agent-runtime-spec.org
+++ b/docs/design/2026-05-28-generic-agent-runtime-spec.org
@@ -70,16 +70,25 @@ revision). The helper-instance design iterated four times in one evening;
 holding it open until the known gaps close. Readiness checklist — all of
 these before any build starts:
 
-- [ ] Emacs launch surface designed (see the open-issue subsection in the
+- [X] Emacs launch surface designed (see the open-issue subsection in the
   helper section): every place a session can be born routes through, or is
-  caught by, the deterministic path.
+  caught by, the deterministic path. /Closed 2026-06-12: mechanics verified
+  in ai-term.el's code, integration design written, the three open calls
+  confirmed by Craig (roster-only sharing, singleton primary,
+  helper-mode.org as canonical home)./
 - [ ] Pre-live test strategy agreed (see Test strategy): sandbox drills
   pass, and the rollout is gated so nothing reaches live projects via
   template sync until validated — startup.org edits propagate to every
   project on their next session, so "accidentally live everywhere" is the
-  default failure mode, not an edge case.
-- [ ] A re-read of the whole helper section after the dust settles, since
-  four same-day revisions usually leave a seam somewhere.
+  default failure mode, not an edge case. /The three-ring gating is
+  written; "agreed" lands with the independent review below./
+- [X] A re-read of the whole helper section after the dust settles, since
+  four same-day revisions usually leave a seam somewhere. /Done 2026-06-12:
+  the coherence pass unified the churned subsections and verified the
+  ai-term.el claims against code./
+- [ ] Independent spec review (the =spec-review= cycle, as the KB and
+  consolidation specs got) comes back Ready or Ready-with-caveats, and its
+  dispositions are folded in via =spec-response=.
 
 * Problem
 
@@ -460,21 +469,23 @@ live anchor used to mean only "crashed session"; it now splits into crashed
 *** Identity and the role contract
 
 - The primary keeps the unset-id singleton (=.ai/session-context.org=), per
-  Phase 1's compatibility rule. Zero friction for the overwhelmingly common
-  one-agent case, and the asymmetry is harmless: the helper's writes land in
-  =.ai/session-context.d/=, away from the singleton. (This deliberately
-  diverges from the v0 launcher model, where every agent gets an id; revisit
-  only if the asymmetry bites in practice.)
+  Phase 1's compatibility rule — /decided (Craig, 2026-06-12)/. Zero
+  friction for the overwhelmingly common one-agent case, and the asymmetry
+  is harmless: the helper's writes land in =.ai/session-context.d/=, away
+  from the singleton. (This deliberately diverges from the v0 launcher
+  model, where every agent gets an id; revisit only if the asymmetry bites
+  in practice.)
 - Helpers are =helper-<rand4>=, launcher-assigned or self-assigned per the
   spawn paths above, sanitized by =session-context-path=, archived with the
   id in the filename.
 - =helper-mode.org= (a template workflow, Craig's "helper.org") is the role
-  contract and the *single canonical home* of the helper rules: the
-  read/write tiers, the data-integrity rules, the light startup, and the
-  helper wrap-up. protocols.org carries a one-paragraph pointer; startup.org
-  and wrap-it-up.org reference it rather than restating it. It has no
-  operator trigger phrase — the spawn paths route to it, and an explicit
-  "you are a helper" instruction is the manual fallback.
+  contract and the *single canonical home* of the helper rules — /decided
+  (Craig, 2026-06-12)/: the read/write tiers, the data-integrity rules, the
+  light startup, and the helper wrap-up. protocols.org carries a
+  one-paragraph pointer; startup.org and wrap-it-up.org reference it rather
+  than restating it. It has no operator trigger phrase — the spawn paths
+  route to it, and an explicit "you are a helper" instruction is the manual
+  fallback.
 
 *** Read/write contract for shared files
 
@@ -605,12 +616,12 @@ What remains to design — the integration, not a new surface:
 - The picker badges grow a =[helper]= state alongside =[running]= /
   =[detached]=, so picking a project that already has a live agent shows
   what the new session will become before it's created.
-- Division of labor: =agent-roster= (the shared script) is the single
-  detection implementation; =ai-term.el= and =bin/ai= each do their own
-  id/export/opener wiring on top of it. ai-term owns tmux session naming
-  (=aiv-= prefix) and window placement that =bin/ai= knows nothing about,
-  which argues for sharing only the roster rather than shelling out to
-  =bin/ai= wholesale.
+- Division of labor — /decided (Craig, 2026-06-12)/: =agent-roster= (the
+  shared script) is the single detection implementation; =ai-term.el= and
+  =bin/ai= each do their own id/export/opener wiring on top of it. ai-term
+  owns tmux session naming (=aiv-= prefix) and window placement that
+  =bin/ai= knows nothing about, so the surfaces share only the roster, not
+  the whole launcher.
 - The =emacs.md= live-reload discipline applies to the ai-term.el changes,
   and the change lands in the =~/.emacs.d= project (its own repo and
   session scope — a cross-project handoff from rulesets, not a rulesets