@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/decisions/ADR-0064-account-model-fallback-on-resume.md

@@ -0,0 +1,79 @@
+---
+id: ADR-0064
+title: A conversation this account cannot use starts on the account's newest selection
+status: Accepted
+created: 2026-10-30
+---
+
+# ADR-0064: A conversation this account cannot use starts on the account's newest selection
+
+## Context
+
+Each mode keeps a model and effort per account in that account's `choices.json`, and a fresh
+conversation starts on the normal mode's selection. A *resumed* conversation instead keeps the model
+in its own history, which is right while the account can use it. After an account switch, a
+signed-out provider or a retired model it cannot: the conversation's branch names a provider this
+account has no credentials for.
+
+Nothing in the Harness decided that case. Pi noticed the failed restore, set a
+`modelFallbackMessage`, and picked a model itself — the settings default, then the first available
+model of the account, restored effort from the branch. The person's own choice for that account was
+never consulted, and the run recorded a model the person had not selected for that conversation.
+The case that prompted this record: a conversation written on one account (a Codex model) was
+resumed on another, and a run started on a different provider's model at a *maximum* reasoning
+level that no step in the conversation had chosen. Because the change is applied at session
+creation, the transcript held no `model_change` entry, so the model could not even be traced from
+the conversation.
+
+## Decision
+
+The terminal runtime owns the start model of every conversation, and the rule is:
+
+- A conversation keeps the model in its history while this account offers it and holds credentials
+  for its provider. An explicit `--model` from a host still wins, and a fresh conversation still
+  starts on the normal mode's saved selection.
+- When the conversation's model is not usable, the conversation starts on **this account's newest
+  saved selection**, resolved field by field: the current mode's choice, then normal's, then the
+  newest selection in any mode (by `updatedAt`). Its effort comes from the same resolution. Each
+  candidate model is checked for being offered and authenticated, and skipped when it is not.
+- That start is a change the terminal makes itself. It is written into the conversation as a
+  `model_change` entry — so the next resume is settled and a run's recorded model is traceable —
+  and it is *never* written to the account's `choices.json`: a fallback is not a selection the
+  person made.
+- The person is told once, in a terminal notice: which model was replaced and which one is used. With
+  no usable saved selection the notice falls back to Pi's own `modelFallbackMessage`, and the
+  session still starts.
+
+## Alternatives considered
+
+- **Adopt the account's newest selection on every account switch.** Rejected: an account switch
+  between two accounts that share a provider would silently drop a conversation's model and effort,
+  which is still valid work.
+- **Resolve the model at the `accounts.relaunch` / `prepare` seam and pass `--model`.** Rejected:
+  that seam cannot tell whether the conversation's model is usable on the target account, so it has
+  the same override problem; it also misses `/session` resume, forks and a provider that was signed
+  out while the account stayed the same.
+- **Do nothing and rely on Pi's fallback.** Rejected: Pi cannot know the person's account choice, and
+  it leaves the run's model unexplained in the transcript.
+- **Block the resume until a model is chosen.** Rejected: a switch or a resume must not dead-end on a
+  model question; a notice plus a working default keeps the conversation usable, and `/model`
+  remains one command away.
+
+## Consequences
+
+- A conversation carried to a new account is deterministic: the same account selection decides it
+  every time, and the transcript records the resulting model change.
+- The conversation gains one `model_change` entry per account it cannot be continued on, which is
+  the audit trail for the run's model and effort.
+- The account's saved choices are unchanged by a fallback, so the person's last deliberate selection
+  for the account and the mode still applies to the next conversation.
+- A host that reads a run's model sees the model the run actually used, not the one recorded in the
+  older part of the conversation.
+
+## References
+
+- `src/accounts/choices.ts` (`latestChoice`, `startChoice`, `startModels`, `resolveChoice`)
+- `src/terminal/tui/modeChoices.ts` (`ModeChoices.start`, `ModeChoices.useFallback`)
+- `src/terminal/tui/runtime.ts` (`recoverModel`, `recordedModel`, `usableModel`, `bind`)
+- [11 Terminal](../architecture/11-terminal.md), [09 Accounts](../architecture/09-accounts-and-connectors.md),
+  [terminal and TUI](../terminal-tui.md)

package/docs/decisions/ADR-0065-variant-switch-at-turn-boundaries.md

@@ -0,0 +1,31 @@
+---
+id: ADR-0065
+title: A conversation switches variant version only by the person's action, at a turn boundary
+status: Accepted
+created: 2026-10-30
+---
+
+# ADR-0065: A conversation switches variant version only by the person's action, at a turn boundary
+
+## Context
+
+`INV-VAR-4` pinned a conversation's variant once: every later turn used the same files even when
+the head moved. That kept runs reproducible and the provider cache warm, but an improvement a
+person adopted reached only their next conversation (PROP-0052).
+
+## Decision
+
+- A conversation has a **selected version**. It starts as the head (or the version the host names)
+  and changes only when the person, in this session, adopts a refinement, restores or reverts a
+  version, or picks one. A head moved elsewhere is shown, never followed.
+- The change takes effect at the next turn boundary. A running reply finishes on its version;
+  every run pins exactly one version (`INV-RUN-1`).
+- The terminal applies it by restarting its frontend on the chosen version and resuming the same
+  native conversation, through the existing relaunch path (`TerminalRelaunch.variantVersion`). The
+  prompt pack is compiled again, so the provider cache misses once.
+- When the version records `tunedFor` and the chat runs another model, the person is told.
+
+## Consequences
+
+Run records keep naming the version each run used, so a conversation's history shows where it
+switched. A terminal's harness session id changes across the restart; the native session does not.

package/docs/decisions/ADR-0066-guided-refinement-from-turn-snapshots.md

@@ -0,0 +1,37 @@
+---
+id: ADR-0066
+title: Refinement replays a typed turn from its snapshot, and a person's guidance reaches improvers only
+status: Accepted
+created: 2026-10-30
+---
+
+# ADR-0066: Refinement replays a typed turn from its snapshot, and a person's guidance reaches improvers only
+
+## Context
+
+Refinement needs a task it can run several times from the same start. For a request a person made
+in their repository, the folder as it is now already holds the agent's answer, and the repository's
+HEAD lacks the person's uncommitted work. People also know where their agent goes wrong and want to
+point improvers there (PROP-0052).
+
+## Decision
+
+- **Snapshot each typed turn.** In a git repository, before the agent acts, the harness writes a
+  commit of the working tree through a throwaway index (tracked edits, deletions, and untracked
+  files within 5 MB each, 100 MB and 10,000 files) and records it on the run. It never touches the
+  working tree, the real index, HEAD or refs, and it gives up after two seconds. The temporary index
+  keeps the real index's time, so git still sees an edit made in the same second that kept a file's
+  size.
+- **Replay in a shared clone.** Each execution works in a temporary `--shared` clone checked out at
+  the snapshot, with HEAD and the index at the turn's starting commit. Ignored files named by
+  `.worktreeinclude` are copied from the repository.
+- **Guidance directs improvers, not choices.** `task.guidance` is checked like work prompts (no
+  measurement words) and capped at 2,000 characters. It is added to the INV, DOM, aggregate and
+  compose missions as where to look first; an edit must still trace to a trajectory and `KEEP_BASE`
+  stays valid. The selector and the reflector never see it (`INV-REF-1`, `INV-REF-2`).
+
+## Consequences
+
+A replay cannot reach what the snapshot left out (ignored files not listed for worktrees, large
+untracked files, attachments); `refine.fromRun` says so before the person confirms. Repositories gain
+unreferenced objects that git collects in time.

package/docs/decisions/ADR-0067-cache-stable-compaction-checkpoint.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0067
+title: The compaction checkpoint arms only for a compaction during its run and stays in place
+status: Accepted
+created: 2026-10-30
+---
+
+# ADR-0067: The compaction checkpoint arms only for a compaction during its run and stays in place
+
+Supersedes the delivery part of [ADR-0032](ADR-0032-compaction-run-checkpoints.md); what the
+checkpoint holds and its bounds are unchanged.
+
+## Context
+
+Under ADR-0032 the checkpoint was appended to the end of every model request, rebuilt each time, in
+every run whose context held a compaction summary. A summary stays in context for the rest of the
+session, so every later turn received it, though that turn's request, todo list and plan were in live
+history.
+
+Because the checkpoint was always last, a request was never the previous request plus its reply.
+Pi's Codex WebSocket continuation (`previous_response_id` with only the new items) needs that shape,
+so every request became a full resend. Provider prefix caches also stopped extending.
+
+In a measured terminal session (6.1 Terra and 6 Luna), caching ran at 94–99% before the first
+compaction and 18–24% after it. Replaying that session's saved history through Pi's request builder
+showed the history itself was append-only:
+- With the old checkpoint, 138 of 151 post-compaction requests were full resends.
+- With this decision, 1 was: the request right after a second compaction.
+
+A live probe on `openai-codex/gpt-6-luna` (2026-10-30, three pairs of disposable sessions with the
+owner's permission) forced one compaction mid-run, then ran a follow-up turn that wrote a todo list:
+- With the old checkpoint, every request after the compaction in that run read 0 cached tokens. In
+  the follow-up turn the cached amount stayed fixed while uncached input grew.
+- With this decision, those requests were cached at 47–66%, against a ceiling of about 76% for
+  contexts that small. The follow-up turn was cached at 61–79%.
+
+## Decision
+
+- **Only a compaction during the run arms it.** The extension records the summary already in context
+  at the run's first request. Only a different summary, a compaction that happened while the run was
+  working, produces a checkpoint. A run that starts from compacted history gets none.
+- **Built once, placed after the summary.** The checkpoint is rendered once per compaction from the
+  run's request, todo list and plan instructions at that moment. It is inserted directly after the
+  `compactionSummary` message, with the same text and timestamp on every later request. Todo updates
+  after the compaction are already in history as `todo_write` calls; the checkpoint says that later
+  updates supersede it. A further compaction in the same run rebuilds it.
+- It stays ephemeral: not persisted, no event, cleared when the run settles or the branch changes.
+
+## Consequences
+
+Each request after a compaction is again the previous request plus new items, so continuation and
+prefix caching work until the next compaction. The checkpoint's todo can be older than the latest
+`todo_write`, which follows it in context. A run whose compaction found no todo list or plan gets no
+checkpoint, even if it writes a todo list later; that list is in its live history.

package/docs/decisions/ADR-0068-scope-and-completion-report.md

@@ -0,0 +1,60 @@
+---
+id: ADR-0068
+title: Scope of the work and two required completion headings
+status: superseded
+created: 2026-10-30
+updated: 2026-11-01
+superseded_by: ADR-0073
+supersedes: partial — ADR-0008
+---
+# ADR-0068 — Scope of the work and two required completion headings
+
+> **Superseded by [ADR-0073](ADR-0073-large-reporting-prompt.md):** the two required headings and the fixed-label rule are replaced by content blocks and flexible headings. The scope rule in the `role` paragraph stands.
+
+> **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** `## What would make this complete` applies only when the work stopped short (blocked, needing the person, or handed back by the guard), and the deferred runner feature is now the stop gate.
+
+## Context and decision
+
+ADR-0008 removed the fixed heading list from the `reporting` section and kept every heading
+optional. Two problems followed from a prompt that only described output:
+
+1. Every run of the last seven days that ended with work left (207 of 822, 25 %) did so at a median
+   of 17 tool calls; the model treated the literal request as the whole assignment
+   (`outputs/diagnoses/2026-10-30-sweep.md`). Nothing in the prompt said the work extends to what the
+   request implies.
+2. A person reading the final reply could not tell what had been done beyond their request, nor what
+   would finish the run. `README`-style prose hid both.
+
+The `role` paragraph of a standard session now states the scope of the work — the job the request
+implies, not only its literal words, inside the working folder and away from what a person must
+decide (a deploy, a secret, remote data, money), without asking first inside those bounds — and the
+`reporting` section requires two headings when they apply:
+
+- `## Beyond what you asked` — anything done beyond the request, each piece with why the work needed it.
+- `## What would make this complete` — the concrete remaining steps in order, naming the ones only
+  the person can decide.
+
+`REPORTING_BUDGET` rises from 2,000 to 2,400 characters to hold them without cutting
+(`prompt/compile.ts`).
+
+## Consequences
+
+- A run may do and report adjacent work that the person did not name; the second heading is what
+  makes that auditable and rejectable rather than silent.
+- The stable prefix changes once per session for the three texts (`role`, `reporting`,
+  `TODO_GUIDANCE`). Measured with real requests only, under INV-PRM-8.
+- Applications bundling the harness need a rebuild before any new session sees the wording; an
+  existing session keeps the prefix it compiled (observed: `context.json` `compiledAt` 16:33:36Z
+  reused by a run at 17:21Z).
+- No stored data or protocol changes. Bounded autonomy is still enforced by the tool gate and the
+  workspace boundary; the prompt does not grant new reach.
+
+## Alternatives considered
+
+- Keep every heading optional (ADR-0008 as it stood): rejected — the two facts above were invisible
+  in the reply, so the person could not see either the extra work or the gap.
+- One combined heading ("Summary"): rejected — extra work and remaining work are different decisions
+  for the person, and merging them hides which is which.
+- Make autonomy a runner feature (continue when a todo is open): deferred, not rejected. The prompt
+  is the cheapest lever and was not yet in effect; `docs/research/2026-10-30-turn-end-controls.md`
+  records what other harnesses do and when a stop-hook style continuation is worth adding.

package/docs/decisions/ADR-0069-stop-gate-and-finish.md

@@ -0,0 +1,136 @@
+---
+id: ADR-0069
+title: A stop gate and a finish tool; the model's checkpoint tool is removed
+status: superseded
+created: 2026-10-31
+updated: 2026-11-01
+superseded_by: ADR-0075
+supersedes: partial — PROP-0041 (the model-written checkpoint), ADR-0068 (when the completion heading applies), ADR-0063 (scope of the unfinished-work guidance)
+related:
+  - STUDY-0004
+  - ADR-0068
+---
+# ADR-0069 — A stop gate and a finish tool; the model's checkpoint tool is removed
+
+> **Superseded by [ADR-0075](ADR-0075-no-todo-gate.md):** the stop gate and the `unfinished` status
+> that open todo items produced are removed. A reply the model ends settles `completed`; the goal
+> loop and the work-slice guard keep their statuses. The `finish` tool was already removed by
+> ADR-0071.
+
+> **Amended by [ADR-0071](ADR-0071-completion-check.md):** `finish` is removed; a completion check (the run's own model, fresh context) now decides `continue` / `needs_person` / `done` when a reply that did work ends with its list closed.
+
+## Context
+
+A reply the model ended on its own settled `completed` (`sessions/runner.ts`), and only a
+guard-ended slice auto-continued (`continueSlice`: `terminalReason === 'slice_complete'`). Nothing
+read the todo list when a reply ended.
+
+- **Scale.** 207 of 822 runs in the week to 2026-10-30 ended with work left, at a median of 17 tool
+  calls; 81 left open todos (`outputs/diagnoses/2026-10-30-sweep.md`).
+- **Worst case.** One terminal session, "Complete platform and API handoff", stopped three times in
+  a row with an open todo, at 23, 65 and 94 of 320 tool calls, after being told "dont stop". Its own
+  answer in between: "I stopped prematurely… the unfinished work was not all blocked by approval
+  gates."
+- **Prompt fixes did not reach it.** ADR-0068's wording was in `src/` but not in `dist/`, and a live
+  terminal session keeps the pack and the extension code it started with.
+
+**Hypothesis: the harness's own exit ramps make stopping easier.** Several texts made a polished,
+incomplete stop a first-class outcome, with nothing pushing back:
+
+- `checkpoint_write`, whose description said to call it "before you stop on purpose";
+- `TODO_GUIDANCE`'s "before your final reply… leave unfinished or blocked steps accurate";
+- ADR-0063's unfinished-handoff guidance;
+- ADR-0068's `## What would make this complete`, "when the run could be more complete".
+
+**What the run records show:**
+
+- `checkpoint_write` was rarely called: 3 calls in 41 eligible top-level code runs.
+- In run `62c7fc6c` the model wrote a checkpoint on its own ("the handoff remains incomplete…
+  continue remaining implementation", nothing `blocked`), made zero further tool calls, and ended.
+  It used the checkpoint as a sign-off.
+- Runs that ended with open todos rose from 8% (146 runs before the tool existed) to 42% (19 after).
+  The second sample is small and mostly huge handoffs, so this is a signal, not proof. Stopping
+  early predates the tool.
+
+Other harnesses enforce the end of a turn rather than describe it (STUDY-0004):
+
+| Harness | Mechanism |
+|---|---|
+| Claude Code, Codex | `Stop` hook with `decision: block` and a reason |
+| Cursor | `followup_message` with a loop limit |
+| Amp | `agent.end → continue` |
+| Ralph loop | A stop hook with a completion promise and an iteration cap |
+| Gemini CLI | `complete_task` is "the ONLY way to finish" |
+| Cline | `attempt_completion` with a double check |
+
+## Decision
+
+1. **Stop gate.** An extension at Pi's `agent_before_settle` boundary (`sessions/stopGate.ts`) runs
+   in every attended top-level run, structured and terminal. It is off in plan, command, automatic,
+   subagent and other related runs.
+   - When the reply's own `todo_write` list holds an open item and nothing was declared with
+     `finish`, it appends a displayed `xingular-stop-gate` message naming the open items and
+     continues the same run.
+   - It nudges at most three times per reply, and never again after a nudge that produced no tool
+     call other than `todo_write` or `finish`.
+   - It is silent for a reply with no todo list or a complete one, an aborted or failed reply, a
+     slice the guard ended, or a continuation another handler already requested.
+   - Each nudge is an `extension.notice` from `stop-gate`.
+   - It is deterministic: it reads the todo list and the declaration, never a model judgment.
+2. **`finish`.** This is the one explicit way to stop with work open (`tools/finish.ts`):
+   - `blocked` or `needs_decision` with a reason, plus an optional `needs`;
+   - `done` is refused while any item is open;
+   - read-only and plan-safe.
+3. **Honest stop codes.** A reply that settles with open items is `interrupted`, never `completed`:
+   - `needs_person` after a `finish` declaration;
+   - otherwise `unfinished`.
+   The runner (or the terminal extension) writes its checkpoint from evidence: done and next from the
+   todo list, blocked from the declaration, files and checks from the reply. Neither auto-continues;
+   the person continues the run. (A terminal reply that ended at its work-slice budget, not one of
+   these, continues in place since ADR-0070.)
+4. **No model-written checkpoint.** `checkpoint_write` is removed. At a work-slice budget the guard
+   asks the model to stop and report, and the harness writes the checkpoint. A capability set pinned
+   before the removal gets `finish` in its place.
+5. **One budget per reply.** The work-slice guard and the gate reset only on a person's message
+   (`before_agent_start` with `messageType: 'user'`). Pi emits `agent_start` for every continuation,
+   so resetting there gave every nudge, delivered subagent result or plan repair a fresh 320-call
+   budget.
+6. **Exit ramps rewritten.**
+   - `role` names the only reasons to stop, and the gate.
+   - `TODO_GUIDANCE` asks for a list that is true at all times.
+   - `## What would make this complete` applies only when the work stopped short (blocked, needing
+     the person, or handed back by the guard), "never stop early in order to write this section".
+   - The `Progress` group explains the gate and `finish`.
+   - The terminal's launch tools now include `finish`, so its prompt says so.
+7. **Subagent tool mismatch is visible.** `spawn_subagent` returns the child's effective `tools`, and
+   the read-only profiles say in their first line when a brief needs a tool they lack.
+
+## Consequences
+
+- A reply with open todos costs up to three more model requests before it is handed back. A reply
+  without a todo list costs nothing extra.
+- A model can still stop with work open, but only by naming a blocker (`needs_person`) or by
+  exhausting the gate (`unfinished`). Both are visible in the record and offer Continue.
+- Hosts must accept the two new stop codes (`10-server-protocol.md`). The external App needs a
+  release that shows Continue for them.
+- The stable prefix changes once (`role`, `TODO_GUIDANCE`, `reporting`, `Progress`). Measured with
+  real requests only, under INV-PRM-8.
+- A live terminal session keeps the code and pack it started with. The gate reaches it only after a
+  rebuild and a restart.
+- **Measure:**
+  - the share of runs that end with open todos (baseline 81 of 207 `model_behaviour` runs);
+  - nudges per run (expected mostly 0–1; more than 3 in a row means the gate's test is wrong);
+  - the `unfinished` and `needs_person` rates.
+
+## Alternatives considered
+
+- **Widen `continueSlice` to `completed` runs with open todos** (STUDY-0004 option 2). Rejected for
+  the first layer: it starts a new run per continuation, needs `continuationOf` to reopen a
+  completed run, and does not cover the terminal, where the failing session ran. The gate keeps one
+  run and works on both surfaces.
+- **Keep `checkpoint_write` and reword it.** Rejected: any always-available "record where you
+  stopped" tool is a sign-off. The harness already derives a better record from evidence.
+- **A model-judged goal evaluator** (Claude Code `/goal`). Rejected, as in STUDY-0004: it adds a
+  model call per reply and judges only what the transcript shows.
+- **Prompt only** (ADR-0068 as it stood). Rejected: the record shows the wording does not hold under
+  long tasks, and it cannot reach a live session.

package/docs/decisions/ADR-0070-terminal-slice-continuation.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0070
+title: A terminal reply continues across work slices in place
+status: accepted
+created: 2026-10-31
+updated: 2026-10-31
+supersedes: partial — ADR-0069 (item 3, "neither auto-continues" for a budget-ended terminal reply), PROP-0041 (terminal replies hand every boundary to the person)
+related:
+  - PROP-0041
+  - ADR-0069
+---
+# ADR-0070 — A terminal reply continues across work slices in place
+
+> **Amended by [ADR-0075](ADR-0075-no-todo-gate.md):** the stop gate is removed; the slice guard
+> still resumes a reply at its slice boundary.
+
+## Context
+
+A headless run that stops at its work-slice budget already continues on its own (`continueSlice`,
+up to `maxSlices`). A terminal reply did not: at 320 tool calls or 60 minutes it settled
+`slice_complete` and waited for the person. In a recorded two-hour design-system handoff the reply
+was cut mid-command at step 221, sat idle nine minutes until the person typed "continue", and the
+next request re-sent about 200k tokens uncached. The guard's own text already told the model "the
+next slice continues from it", which was false in the terminal.
+
+## Decision
+
+1. **Continue in place.** When a terminal reply ends at its budget, `sliceContinuation`
+   (`sessions/workSlice.ts`) returns a continuation from Pi's `agent_before_settle`: a
+   `xingular-slice-continue` message naming the next open todo item, in the same run, so the cached
+   prompt stays warm. The counters and clock restart; compactions carry over, so a reply that keeps
+   compacting still ends.
+2. **The same stops as `continueSlice`.** No continuation after a fruitless slice (no successful
+   `bash`, `edit` or `write`), a `finish` declaring `blocked` or `needs_decision`, a provider
+   failure, an abort, a plan reply, a todo list with every item done, or `maxSlices` (8 by default).
+   Then the reply settles `slice_complete` as before and the person decides.
+3. **One checkpoint per slice.** Each boundary sends a harness-written `checkpoint` with its real
+   slice number and a notice; the heartbeat reports the live slice. A person's message starts again
+   at slice 1.
+4. **Launch control.** `XINGULAR_WORK_SLICE=off` still removes the boundary; key=value pairs
+   (`maxToolCalls=15,maxSlices=3`, the run-policy fields and bounds) set a launch policy, mainly for
+   testing. A malformed value falls back to the defaults.
+
+## Consequences
+
+- A long terminal task runs up to eight slices without a person, and Esc still stops it at once.
+- A continued terminal reply is one run record with several checkpoints, where a headless one is a
+  chain of runs; `sliceOf` keeps counting the headless chain.
+- A reply at its slice boundary continues in the next slice; there is no todo gate (ADR-0075).

package/docs/decisions/ADR-0071-completion-check.md

@@ -0,0 +1,104 @@
+---
+id: ADR-0071
+title: A completion check decides whether a reply may end; finish is removed
+status: accepted (partly superseded by ADR-0072)
+created: 2026-10-31
+updated: 2026-11-01
+supersedes: partial — ADR-0069 (the `finish` tool and the `needs_person` it declared)
+superseded-by: partial — ADR-0072 (the check no longer runs on every reply; it checks a /goal claim only; there is now a /goal command)
+related:
+  - ADR-0069
+  - ADR-0070
+  - STUDY-0004
+---
+# ADR-0071 — A completion check decides whether a reply may end; finish is removed
+
+## Context
+
+ADR-0069 added a deterministic todo gate and a `finish` tool. A live A/B with the Panisara account
+on `openai-codex/gpt-6-luna` used the prompt "work for the handoff docs/handoffs/B-platform-and-api.md":
+
+| Build | What happened |
+|---|---|
+| Before ADR-0069 | The reply branched, edited `package.json`, hit an `npm install` failure, and stopped. It marked every todo item `completed` while its own reply said "B0 remains incomplete", so it settled `completed`. |
+| With ADR-0069 | The reply stopped after 23 seconds through `finish(needs_decision)`, asking to "confirm I should start with B0 and create the worktree". The handoff already answers both. |
+
+The `role` section was missing from both runs, because the runner did not pass `launch.standard`,
+so the prompt layer was not tested.
+
+The A/B showed three ways a reply stops while it could continue:
+
+1. it ends with todo items open (the gate catches this);
+2. it marks items done falsely (the gate cannot see this);
+3. it stops to ask permission for something inside its authority, which `finish` turned into a
+   sanctioned exit.
+
+Every harness studied keeps the agent doing the work from certifying its own early stop:
+
+| Harness | Who decides the work may stop |
+|---|---|
+| Claude Code | A Stop hook, or the `/goal` evaluator: a separate model returning met / not met / impossible |
+| Codex, Cursor, Amp | Stop hooks |
+| OpenHands headless | Scripted auto-continue: "Please continue working on the task… Do NOT ask for more help" |
+| Aider | Test exit codes |
+| Anthropic long-running harness | Tests decide before a feature is marked passing |
+
+`finish(blocked | needs_decision)` was the opposite: a self-declared exit.
+
+## Decision
+
+1. **Remove `finish`.** The model has no tool that ends or hands off its own work (INV-TOOL-9).
+2. **Add the completion check** (`sessions/completionCheck.ts`, wired into `sessions/stopGate.ts`).
+   - **When it runs:** at Pi's `agent_before_settle`, when the todo list is closed or absent and the
+     reply made a work tool call (pure chat and one-line answers are never checked).
+   - **What it asks:** the run's own model (`ctx.modelRegistry.streamSimple`, reasoning `low`, a
+     fresh context and its own system prompt) judges the person's request against a clipped
+     transcript of this reply and its todo list. For a continuation, the request is the one behind
+     the chain.
+   - **`continue`:** the reply is sent back with a displayed `xingular-completion-check` message
+     carrying the reason and the next step.
+   - **`needs_person`:** the reply settles `interrupted` / `needs_person`, with the check's reason as
+     the checkpoint's `blocked`.
+   - **`done`:** the reply ends `completed`.
+   - **Limits:** it shares the todo gate's cap of three nudges per reply and the no-progress rule.
+   - **Recording:** its request is recorded in the run's usage.
+   - **Failure:** it fails open on any error.
+   - **The request is the goal.** There is no `/goal` command and no condition to write.
+3. **Same model, low effort.** Chosen by the person over a cheaper model. The trade-off is that the
+   same model shares some blind spots with the doer. A separate system prompt, a fresh context
+   holding only the request, list and transcript, and no tools limit that.
+4. **Prompt.** `role` names the decisions that are the agent's own and the only reasons to stop. It
+   says that a document the request points to is the request, and that a question the request or
+   files already answer is not a question for the person. In a person's own session, the `Progress`
+   group says replies are checked. The role budget is now 2,200 characters, so the role fits uncut
+   with the subagent paragraph.
+5. **Kill switches.** `XINGULAR_STOP_GATE=off` and `XINGULAR_COMPLETION_CHECK=off` at launch, for
+   layer-by-layer experiments.
+
+## Consequences
+
+- A reply that did work costs one more model request when it ends, plus at most three nudges. A
+  reply with no tool calls costs nothing extra.
+- False "done" lists and permission questions are answered by the check rather than reaching the
+  person. A real blocker still stops the reply, but a separate judgement decides it, and the record
+  says why.
+- The faux model in tests must answer the check too, so the test setup switches it off by default
+  and the tests about it switch it on.
+- **Measure, layer by layer**, with a live A/B on clean copies, 3 runs per arm:
+  - (A) the old harness;
+  - (B) the prompt only;
+  - (C) the prompt plus the todo gate;
+  - (D) everything.
+
+  Compare tool calls before the reply ends, false "completed" lists, permission-question stops,
+  nudges by layer, check verdicts and cost.
+
+## Alternatives considered
+
+- **Keep `finish` with a double check** (refuse the first `needs_decision`). Rejected: it still tells
+  the model there is a sanctioned way out, and asks it to insist.
+- **A `/goal` command.** Rejected by the person: ordinary requests must keep going without one.
+- **A cheaper judge model.** Not chosen. It would be cheaper and more independent; the person
+  preferred the run's own model.
+- **Prompt only.** Rejected as the only layer: agent B ignored "dont stop" in the person's own
+  message, and a live session keeps the prompt it started with.