@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/decisions/ADR-0072-codex-prompts-and-goal.md

@@ -0,0 +1,108 @@
+---
+id: ADR-0072
+title: Codex's prompts and /goal; the completion check moves behind /goal
+status: accepted
+created: 2026-11-01
+updated: 2026-11-01
+supersedes: partial — ADR-0071 ("every reply is checked", "there is no /goal command"); amends INV-TOOL-9
+related:
+  - ADR-0069
+  - ADR-0070
+  - ADR-0071
+  - STUDY-0004
+---
+# ADR-0072 — Codex's prompts and `/goal`; the completion check moves behind `/goal`
+
+> **Amended by [ADR-0075](ADR-0075-no-todo-gate.md):** the todo gate is removed, so ordinary replies
+> rely on the prompt alone. The goal loop and its completion claim check stay.
+
+## Context
+
+ADR-0071 asked a model to judge, at the end of **every** reply that did work, whether the request was
+done. Run history after it showed what was still wrong and what was not:
+
+- In the "dont stop" handoff runs that ended on their own with work left (`62c7fc6c`, `d73804c8`,
+  `b3ab2349`) every run still had an open todo item, and the final reply said "not complete" without
+  a reason or a next step. The todo gate catches that; the check never ran for them.
+- The check ran once in all history and failed: `sessionCheckModel` sent no session id, and
+  opencode-go answered 400 `MissingSessionID`.
+- The person wants the evaluator only for an opt-in, long-running goal, and ordinary requests to
+  finish what they can and say plainly what is done, why it stopped and what is next. The person also
+  observed that the todo list, written after a short look at the repository, becomes the boundary of
+  the work: it is progress, not scope.
+
+OpenAI Codex is open source (Apache-2.0). Read at commit 67f0994b53 (2026-10-31):
+
+| Part | What Codex does |
+|---|---|
+| An ordinary turn | Ends when the model makes no tool call. No completion check, no plan gate. Completion pressure is prompt text only (gpt-6 "Autonomy and persistence", "When to ask the user for permission", "Compaction does not end the task"). |
+| `update_plan` | Display only and stateless. |
+| `/goal` | No evaluator. The model calls `update_goal(complete \| blocked \| paused)` after a strict audit prompt; the harness starts the next turn whenever the thread is idle and the goal is active. `blocked` needs the same blocker on three consecutive goal turns. Codex's history removed the "no tool call, so stop" rule and elapsed-time text because they made the model shortcut work. |
+| Stop hooks | A hook's continuation is a user-role message, "to match training for turn loops". |
+
+## Decision
+
+1. **Ordinary replies** have no model-judged check. The deterministic todo gate (ADR-0069) stays:
+   three nudges, the no-progress rule, and now the text "the list shows progress; it is not the limit
+   of the work". Completion pressure is the prompt.
+2. **The prompt adopts Codex's wording** for a person's own session, as separate stable sections:
+   `autonomy`, `permission`, `steering` and `writing` (`src/prompt/standard.ts`), and a longer
+   `reporting` section whose first rule is that unfinished work says so on the first line, with the
+   reason and the next step. They apply to every model, so the terminal and a host read the same
+   text (INV-PAR-1). Left out: text about Codex's own channels and tools, and "do not run tests
+   unless asked", which contradicts this harness.
+3. **The todo list is progress, not scope.** `TODO_GUIDANCE` says the request and any document it
+   points to is the scope; list a handoff's steps instead of one "remaining work" item; compare the
+   request, not the list, with what is done before ending the turn.
+4. **`/goal <objective>`** is the person's opt-in long run (terminal command, and `goal` on
+   `sessions.run`). The person sets it and the work starts at once. It adopts Codex's:
+   - tools `get_goal` and `update_goal` (descriptions and errors verbatim; offered to the model
+     only while a goal exists; **there is no `create_goal`**, the person creates goals);
+   - prompts `continuation`, `budget_limit` and `objective_updated` (the objective escaped and
+     wrapped as data);
+   - states `active | paused | blocked | usage_limited | budget_limited | complete`;
+   - brakes: three automatic rounds with no activity, three with only failed commands, a provider
+     error (`blocked`), a usage-limit error (`usage_limited`);
+   - the person's side: `/goal [<objective>|edit|pause|resume|clear]`, a replace confirmation, Esc
+     pauses a running goal, a footer label, a provenance message for each change.
+5. **A completion claim is checked.** `update_goal(complete)` only records a claim. At the next
+   settle the same model, at low effort, with a fresh context and no tools, checks the claim against
+   the objective and the transcript (Codex's audit: completion is unproven, weak evidence is not
+   enough, quote the evidence). `done` completes the goal; `continue` keeps it active with the
+   reason; no model, an error or an unreadable answer accepts the claim. This is the only completion
+   check in the harness.
+6. **Caps.** Rounds and hours, not tokens (the harness accounts for time, not a token budget): 30
+   rounds or 8 hours by default, `--rounds N --hours H` per goal. At the cap the goal becomes
+   `budget_limited` and gets one last round to wrap up (progress, what remains, the next step).
+7. **INV-TOOL-9 is amended:** the model has no tool that ends or hands off its own work, except
+   `update_goal` in a goal the person started, whose `complete` is checked and whose `paused` needs
+   the person's word.
+8. **Server runs.** `sessions.run` takes `goal: { objective, rounds?, hours? }` for a person's own
+   top-level run; the run continues in place, and `goalMode` on `run.json` records the objective,
+   status, rounds and time. A goal that crosses a work-slice boundary is carried by `continueSlice`.
+   In this change a server goal belongs to one run chain; `goal.set | get | clear` as separate
+   methods and pause/resume across unrelated runs are left for the App's screen.
+9. **Also fixed:** `sessionCheckModel` passes the session id, so opencode-go accepts the request.
+   `XINGULAR_COMPLETION_CHECK=off` now accepts every goal claim unchecked.
+
+## Consequences
+
+- An ordinary reply costs no extra model request. A goal costs one request per completion claim.
+- The stable prefix grows by about 8 to 9 thousand characters (the new sections), once. Starting a
+  goal changes the active tools once (the two goal tools), which can cost one cache miss.
+- The goal's continuation prompt is long (about 6.5 thousand characters); it rides as a hidden user
+  message in each round, and the claim check skips it.
+- A restored conversation shows its goal as `paused`; nothing resumes by itself.
+- Measure, as ADR-0071 asked: the same handoff prompt on clean copies, three runs per arm (old
+  build, new ordinary reply, new `/goal`): tool calls before the reply ends, false "completed"
+  lists, permission-question stops, the first line of the final report, claim checks and cost.
+
+## Alternatives considered
+
+- **Codex exactly (no evaluator).** Rejected for the goal's `complete`: run history shows models
+  marking work done falsely, and a separate fresh-context look at one claim is cheap.
+- **Keep the every-reply check, cheaper model.** Rejected by the person: ordinary requests should
+  finish on their own, and no studied harness judges ordinary replies.
+- **A model-created goal (`create_goal`).** Not adopted: it would put a goal tool in every session.
+- **A harness nudge when a reply's own text says work remains.** Rejected by the person for now:
+  prompt and the todo gate only.

package/docs/decisions/ADR-0073-large-reporting-prompt.md

@@ -0,0 +1,89 @@
+---
+id: ADR-0073
+title: A large, content-block reporting prompt
+status: superseded
+created: 2026-11-01
+updated: 2026-11-01
+superseded_by: ADR-0074
+supersedes: partial — ADR-0068 (its required headings and fixed-label rule)
+amends: ADR-0008 (flexible headings stand; required content blocks are added)
+related:
+  - ADR-0008
+  - ADR-0068
+  - ADR-0072
+  - STUDY-0006
+---
+# ADR-0073 — A large, content-block reporting prompt
+
+> **Superseded by [ADR-0074](ADR-0074-report-content-not-report-blocks.md):** the four required
+> blocks, the "Nothing needed" ending, the five examples and the 18,000-character budget are
+> replaced by content questions, an evidence line, an optional by-hand block and free headings.
+
+## Context
+
+The person reading final replies asked for three things the 3,400-character `reporting` section did
+not give: headings that fit the content, a "how to test" block, and a clear next step. A forensic
+pass on run `07974d6e` showed the structured report existed at seq 222, but the section was thin
+enough that a terse follow-up could replace it, and it carried no example of what a good report looks
+like.
+
+The peer study in [STUDY-0006](../study/STUDY-0006-reporting-prompts.md) found:
+
+- Claude Code leads with the outcome, drops preamble and recap, answers a simple question in one to
+  three sentences, and keeps safety-critical detail complete. Its extracted reporting rules name the
+  next action, use absolute paths, quote only load-bearing snippets, and treat the final message as
+  the report.
+- Codex keeps per-model prompt files of 6.6k–24k characters, so a large reporting section is within
+  the norm it sets.
+- Kimi CLI has no final-report shape at all; a large prompt is an authored choice, not a universal
+  convention.
+
+The old section mandated three headings (`## Beyond what you asked`, `## Differences from the plan`,
+`## What would make this complete`) and no test or next-step block. It had no examples.
+
+## Decision
+
+Replace `REPORTING_GUIDANCE` with a ~15.8k-character text in
+[`src/prompt/reporting.ts`](../../src/prompt/reporting.ts), imported by
+[`src/prompt/compile.ts`](../../src/prompt/compile.ts). Raise `REPORTING_BUDGET` to 18,000 so the
+section is never cut, and keep it last in the stable prefix.
+
+The text keeps the outcome-first rule and defines **content blocks, not heading names**:
+
+- Required for a change: outcome, what changed, how to test, what to do next.
+- Optional when they apply: beyond the request, departures from the plan, unverified or needs a
+  person, open questions.
+- Headings are the model's choice. The guidance lists synonyms ("How to test", "Try it", "Verify")
+  and says the requirement is the information, not the label.
+- Five worked examples: a small change, a multi-file change with extra work, a blocked change, a
+  research answer, and a one-line question. An anti-pattern table and a pre-send checklist follow.
+
+"How to test" is required only for a change. It gives numbered steps, exact commands or URLs, the
+expected result, what the agent already ran, and what the person must run. "What to do next" names
+the person's action or says "Nothing needed". Pure research and one-line questions stay short and
+carry no test block.
+
+## Consequences
+
+- The stable prefix grows by about 12.4k characters (roughly 3.5k tokens). Every session pays it
+  once; the provider cache covers later requests, and the first request after an upgrade misses the
+  cache. The cost is measured with real application requests only, under INV-PRM-8.
+- [`src/prompt/compile.test.ts`](../../src/prompt/compile.test.ts) now checks the content blocks,
+  the five examples, the size range, and that the section is not cut; the exact old phrases are gone.
+- The spec ([04-prompt.md](../architecture/04-prompt.md)) and the old ADRs are updated; the three
+  old headings become examples, not requirements.
+- A shorter or different report shape for one variant is a variant prompt change through refinement,
+  not configuration of this section.
+
+## Alternatives
+
+- **8k characters, three examples.** Rejected: the person chose the 16k balance for enough rules and
+  examples to cover the shapes.
+- **24k characters, eight examples.** Rejected for now: the largest prefix; the 16k text covers the
+  five shapes the person named.
+- **Keep the three fixed headings.** Rejected: fixed labels are what made the report rigid, and the
+  person asked for headings that fit the content.
+- **Move the examples to a skill.** Rejected: the guidance must shape every reply without a second
+  load, and the person asked for the prompt itself to carry the rules and examples.
+- **Always require the test and next blocks, even for a question.** Rejected: the person chose
+  changes only, so a one-line question stays one to three sentences.

package/docs/decisions/ADR-0074-report-content-not-report-blocks.md

@@ -0,0 +1,90 @@
+---
+id: ADR-0074
+title: Report content, not report blocks
+status: superseded
+created: 2026-11-01
+updated: 2026-11-01
+superseded_by: ADR-0076
+supersedes: ADR-0073 (its four required blocks, five examples and 18,000-character budget)
+amends: ADR-0008 (human inspection is the only by-hand block)
+related:
+  - ADR-0008
+  - ADR-0073
+  - STUDY-0006
+---
+# ADR-0074 — Report content, not report blocks
+
+> **Superseded by [ADR-0076](ADR-0076-codex-final-answer-verbatim.md):** the four content
+> questions, the human-check and next-step blocks, the evidence table, the anti-pattern table and
+> the three examples are replaced by Codex's final-answer and technical-communication text.
+
+> **Supersedes [ADR-0073](ADR-0073-large-reporting-prompt.md):** the four required blocks, the
+> "Nothing needed" ending and the 18,000-character budget are replaced.
+
+## Context
+
+ADR-0073 made a change carry four required blocks — outcome, what changed, how to test, what to do
+next — and put both the agent's own runs and the person's steps inside "how to test". In real
+replies the two merged: a section headed for the person's testing listed `npm run typecheck —
+passed` and `npm test — 212 test files passed`, checks the person was never going to repeat. The
+same guidance required "or say 'Nothing needed'", and replies ended with "Nothing needed next"
+even when the work was complete and visible.
+
+Headings also collapsed. The four block names and their synonyms ("How to test", "Test it", "Try
+it", "Verify") gave the model one vocabulary, so unrelated work — a document, a diagnosis, a
+publish — arrived under "What changed / How to check / Next step".
+
+The person asked for three things: a by-hand section for checks only a person can make (a screen,
+a sign-in, a diff or PR, a publish), no filler ending, and headings that follow the content. The
+earlier design already had the principle: ADR-0008 made **Need human inspection** optional and said
+not to use it "for checks already performed or generic risks". ADR-0073 folded that block into the
+required set and lost the distinction.
+
+## Decision
+
+Replace `REPORTING_GUIDANCE` in [`src/prompt/reporting.ts`](../../src/prompt/reporting.ts) with a
+~8.9k-character text (about 2.1k o200k tokens) that defines content questions rather than blocks:
+
+- The reply answers what happened, what changed or was decided, what only a person can check, and
+  what they do next — in any words and any order. Most replies answer two or three.
+- The checks the agent ran are evidence: one line each, command and result. They are never steps
+  for the person, and never appear in a section headed for the person's testing.
+- A by-hand check is optional and covers only what the agent could not do: open a screen, sign in,
+  read a document for tone, review or merge a diff, publish, deploy, use a device. It gives the
+  shortest sequence, what to look at, and the result that means it works. When nothing needs a
+  person, the block is absent — no "no manual check" line.
+- A finished reply with nothing left ends on its last real point. "Nothing needed", "Nothing needed
+  next" and "No action required" are banned.
+- There is no required heading and no preferred set; the section gives cross-domain examples and a
+  shape-by-work table, not a vocabulary, and says not to repeat one heading set.
+- Three worked examples: a screen change, a backend change, a publish. The old examples' "Nothing
+  needed next" endings are gone.
+
+`REPORTING_BUDGET` falls from 18,000 to 12,000 characters. The section stays last in the stable
+prefix and is never cut.
+
+## Consequences
+
+- The stable prefix shrinks by about 6.9k characters (15,809 → 8,921) and about 1.6k o200k tokens
+  (3,736 → 2,108). Existing sessions miss the provider cache once after the upgrade; the price of a
+  request is measured only with real application requests under INV-PRM-8.
+- [`src/prompt/compile.test.ts`](../../src/prompt/compile.test.ts) checks the content questions, the
+  evidence rule, the by-hand rule, the ending ban, the heading freedom, three examples, the size
+  range and the 12,000 budget.
+- No data, storage or server-protocol change; the App needs a rebuilt harness only.
+- Risk: without four required blocks, a reply could go thin. The four content questions and the
+  "before you send" list are the guard; whether replies keep the shape is checked on real work, not
+  by a test.
+
+## Alternatives
+
+- **Keep the four blocks and only ban "Nothing needed".** Rejected: the merge of the agent's runs
+  with the person's checks is the defect, and it comes from the block's own text.
+- **Give the agent a separate "what I ran" block.** Rejected: one line of evidence is enough, and a
+  block invites the ceremony the person objected to.
+- **Ban headings entirely.** Rejected: short replies drift into prose, and a report still needs
+  names for its parts.
+- **Keep ~15.8k characters and rewrite the rules in place.** Rejected: the person chose a leaner
+  text, and the five examples restated rules already in prose.
+- **Require the by-hand block on every change.** Rejected: most backend work has nothing a person
+  can check, and an always-present block produces filler.

package/docs/decisions/ADR-0075-no-todo-gate.md

@@ -0,0 +1,84 @@
+---
+id: ADR-0075
+title: No todo gate; a reply ends when the model ends it
+status: accepted
+created: 2026-11-01
+updated: 2026-11-01
+supersedes: ADR-0069 (its stop gate), ADR-0072 (its "the todo gate stays")
+related:
+  - ADR-0069
+  - ADR-0072
+  - STUDY-0004
+---
+# ADR-0075 — No todo gate; a reply ends when the model ends it
+
+> **Supersedes the todo gate of [ADR-0069](ADR-0069-stop-gate-and-finish.md)** and the line in
+> [ADR-0072](ADR-0072-codex-prompts-and-goal.md) that kept it. The goal loop and its claim check
+> stay.
+
+## Context
+
+ADR-0069 added the stop gate: in an attended top-level reply, an item still `pending` or
+`in_progress` at Pi's `agent_before_settle` boundary sent the reply back with a displayed
+`xingular-stop-gate` message, up to three nudges, and then settled the run
+`interrupted{unfinished}` with a harness-written checkpoint.
+
+In use the messages read as noise. "Harness stop gate (1/3): your reply ended with 2 open todo
+items…" appears in the transcript of a person's own session, and a stale item the model forgot to
+close marks the run unfinished even when the work is done. The person asked for the nudges and the
+unfinished status to go, and for the prompt to relax instead.
+
+The peer check on 2026-11-01 does not make this an obvious outlier either way:
+
+| Harness | Todo nudge at the end of a turn | Evidence |
+|---|---|---|
+| omp | **Yes.** `TodoTracker.checkCompletion()` appends "You stopped with N incomplete todo item(s)… Please continue" as a developer message and schedules a continuation, up to `todo.remindersMax` (default 3); it skips a reply awaiting the person and also nudges mid-run after 12 mutating tools | `external/omp/packages/coding-agent/src/session/todo-tracker.ts:221`, `src/tools/settings.ts:360-380` |
+| Claude Code | No bounce. A gentle reminder to use TodoWrite ("This is just a gentle reminder - ignore if not applicable"); a `Stop` hook is user configuration | Extracted prompt `system-reminder-todowrite-reminder.md`, `ccVersion` 2.1.139 |
+| Codex | No bounce. `update_plan` is opt-in since 0.152 and enforces nothing at the end of a turn | STUDY-0004; 0.152 release notes |
+| Kimi CLI | No bounce. A todo tool and instructions only | `external/kimi-cli/src/kimi_cli/tools/todo/set_todo_list.md` |
+| OpenHands, SWE-agent, smolagents | No todo gate | No todo tool or no end-of-turn enforcement |
+
+So this harness had copied a real design, but it is the minority design among the studied peers,
+and its messages are the thing the person objected to.
+
+## Decision
+
+Remove the gate:
+
+- Delete the nudge extension, its state, `nudgeText`, `stopGateNotice`, `MAX_STOP_GATE_NUDGES`, and
+  the `XINGULAR_STOP_GATE` switch.
+- A reply the model ends settles `completed`. The harness does not send it back and does not
+  overwrite its status from the todo list.
+- A person's interrupt, the work-slice guard (INV-RUN-13) and a goal's stop (INV-RUN-16) keep their
+  statuses and checkpoints. A blocked goal settles `needs_person`; a goal on a limit, a pause or a
+  stall settles `unfinished`.
+- The goal/checkpoint helpers move to `sessions/goalStop.ts`; the goal check's model helper moves to
+  `completionCheck.ts`.
+- The prompt keeps the work-slice sentence as `WORK_SLICE_GUIDANCE`, and `TODO_GUIDANCE` is relaxed:
+  the list is a progress aid, the request is the scope, and a step left open is explained in the
+  reply. No text says a reply is sent back.
+- A login that blocks the work is answered with the exact command the person must run (see
+  `04-prompt.md` § Reporting).
+
+## Consequences
+
+- An early stop is no longer caught by the harness. The prompt is the only layer that asks the model
+  to finish the request, and a person reading the reply has to notice a stop with work left.
+- The App no longer shows an interrupted-run notice for open todo items; it still does for a slice,
+  a goal and a person's interrupt.
+- The stable prefix loses the old `STOP_GATE_GUIDANCE` sentence and gains the credential rule in the
+  reporting section; existing sessions miss the provider cache once after the upgrade.
+- `XINGULAR_STOP_GATE` is retired and ignored if set. No data or protocol change; run records
+  written before this change keep their statuses.
+
+## Alternatives
+
+- **Keep the gate and only make it opt-in, off by default.** Rejected: the machinery and its
+  messages would still exist for the default path people read, and the harness would carry a
+  capability nobody turns on.
+- **Keep one reminder.** Rejected: the person asked for the nudges to go, and one reminder still
+  writes a harness message into their reply.
+- **Remove the message but keep the `unfinished` status.** Rejected: the status comes from a list the
+  model may not maintain, so a stale item would mark finished work unfinished with no way to fix it.
+- **Keep the gate.** Rejected: it is the thing the person objected to, and the majority of the
+  studied peers leave the end of a turn to the prompt.

package/docs/decisions/ADR-0076-codex-final-answer-verbatim.md

@@ -0,0 +1,98 @@
+---
+id: ADR-0076
+title: Codex's final-answer guidance, adopted verbatim
+status: accepted
+created: 2026-11-01
+updated: 2026-11-02
+supersedes: ADR-0074 (its four content questions, human-check block, next-step block and examples)
+amended_by: ADR-0079
+related:
+  - ADR-0074
+  - ADR-0075
+  - STUDY-0006
+---
+# ADR-0076 — Codex's final-answer guidance, adopted verbatim
+
+> **Supersedes [ADR-0074](ADR-0074-report-content-not-report-blocks.md):** the four content
+> questions, the human-check block, the next-step block, the evidence table, the anti-pattern table
+> and the three examples are replaced by Codex's final-answer and technical-communication text.
+
+> **Amended by [ADR-0079](ADR-0079-phase-led-reporting-guidance.md):** add the cold-reader test,
+> explicit verification honesty, concise subagent reports and a preference for content-named `#` / `##`
+> headings in substantial reports. The phase order is explicit; heading wording remains flexible.
+
+## Context
+
+ADR-0074 replaced four required blocks with four content questions, a one-line evidence rule, an
+optional human-check block, a next-step rule and three examples. It removed the filler ending and
+brought the section to 9,235 characters (2,188 o200k tokens).
+
+A rule-by-rule comparison with Codex's `gpt-6.1-sol` prompt found that most of the autonomy and
+permission text was already Codex's, word for word, while the report section carried the strictness:
+18 prohibition phrases, 19 obligation words, a pre-send checklist and an anti-pattern table, against
+Codex's 454-token `## Final answer` block, which mostly describes qualities and rendering.
+
+The person chose Codex's wording for the report: self-contained final, technical communication,
+evidence and limits, table guidance and length by complexity. They also added the model name to the
+identity, adopted Codex's personality paragraph and unclear-scope sentence (with `ask_user`), and
+adopted Codex's tool hygiene, test restraint and skill rules.
+
+## Decision
+
+- **Identity.** `harness-identity` carries the product name, `Launch.model` when the host knows it,
+  and Codex's goal sentence: "You and the user share one workspace, and your job is to collaborate
+  with them until their intended goal is completely handled." The model name is a stable-prefix
+  line; a `/model` switch after the pack is compiled leaves it naming the model the session started
+  with.
+- **Personality.** A new standard section (`prompt/standard.ts`, order 22) carries Codex's
+  personality paragraph, with "As Codex" changed to "As an AI agent" so the harness names no other
+  product.
+- **Unclear scope.** Codex's sentence replaces the harness wording: "If the user's intent or task
+  scope is unclear, progress towards the user's goal with the information available and then ask the
+  user for clarification while continuing independent work." A following sentence names `ask_user`
+  for the question.
+- **Reporting.** `REPORTING_GUIDANCE` becomes Codex's final-answer block and technical-communication
+  paragraphs: self-contained, most important information, outcome first, what changed and why, how
+  it was tested, material risks and limits, the evidence needed and its limits, verification
+  summarized rather than listed, progress updates as learned/uncertain/next. Tables for mappings and
+  comparisons. Headings stay free. A shape-by-work table says what different work needs. Length
+  scales with complexity. Prose first, lists when the information is parallel or sequential. Two
+  examples (a screen change, a blocked publish) and a four-line pre-send list replace the old
+  blocks, the anti-pattern table and the three examples.
+- **Removed from reporting.** The four content questions, "Your checks are evidence", "What only a
+  person can check", "What the person does next", "What to leave out", "Tone", "Claims carry
+  evidence" and the anti-pattern table. The exact command for a blocked login remains in
+  `autonomy` and in the blocked-publish example.
+- **Tools.** Codex's work rules join the Native guidance: `rg` first, no decorative command
+  separators, shell text treated as code, no reused `$HOME`, no long blocking sleeps, no tests for
+  reversible changes or tests that mirror the implementation, and broadening tests only when
+  justified. Codex's skill rules (SKILL.md, user precedence, announce the first use, `$name`,
+  missing skill) and its plugin principle join the Wiki guidance.
+- `REPORTING_BUDGET` stays 12,000; the text is 3,697 characters (about 800 o200k tokens) and is
+  never cut.
+
+## Consequences
+
+- The stable prefix shrinks by about 5.5k characters and 1.3k tokens. Existing sessions miss the
+  provider cache once after the upgrade.
+- The report no longer has a by-hand check block or a next-step block. A person reading a reply gets
+  the outcome, the change, the evidence and the risks, and must notice when the reply leaves
+  something undone; ADR-0075's removal of the todo gate already accepted that.
+- The personality section adds a sixth standard section; the terminal and every host read the same
+  text (INV-PAR-1).
+- `Launch.model` is a new optional launch field; hosts that do not know the model get the identity
+  without "based on".
+- No data, storage or server-protocol change.
+
+## Alternatives
+
+- **Keep ADR-0074 and only trim the anti-patterns.** Rejected: the comparison showed the strictness
+  was in the block structure itself, and the person chose Codex's wording.
+- **Copy Codex's whole prompt.** Rejected: its channels, `update_plan`, `functions.exec`, apps and
+  plugin mechanics do not exist in this harness; only the report, personality, permission and work
+  rules apply.
+- **Keep the human-check and next-step blocks alongside Codex's text.** Rejected: they were the two
+  blocks the person asked to remove, and Codex's technical communication covers what remains.
+- **Make the model name dynamic.** Deferred: a `/model` switch would need the identity in a dynamic
+  section or a recompile, and both change the cache contract; the stable line is the simpler
+  starting point.

package/docs/decisions/ADR-0077-plan-runs-may-conclude-no-plan-needed.md

@@ -0,0 +1,120 @@
+---
+id: ADR-0077
+title: A plan run may conclude that no plan is needed
+status: accepted
+created: 2026-11-02
+updated: 2026-11-02
+supersedes: ADR-0055 (its "every attended plan reply must carry a block" criterion), ADR-0057 and ADR-0058 (their repair criterion), not their mechanisms
+related:
+  - ADR-0055
+  - ADR-0057
+  - ADR-0058
+  - ADR-0074
+  - ADR-0075
+---
+# ADR-0077 — A plan run may conclude that no plan is needed
+
+> **Supersedes the repair criterion of [ADR-0055](ADR-0055-plan-output-repair.md),
+> [ADR-0057](ADR-0057-structured-plan-outcomes.md) and
+> [ADR-0058](ADR-0058-ask-user-only-plan-clarification.md), not their mechanisms.** The same-run,
+> one-attempt repair, the shared classification, the tool gate and the `<plan_blocked>` channel stay.
+
+## Context
+
+Plan mode had no legitimate empty outcome. Its classification recognized `plan_ready` (one complete
+`<proposed_plan>` block), `blocked` (required input that `ask_user` could not obtain) and `invalid`
+for everything else, so a reply that concluded there was nothing to do was a formatting failure.
+Two instructions then demanded an artifact: the plan section ended "end the reply with exactly one
+block", and the hidden repair turn told the model to re-send its plan inside one block and offered
+only a blocked block as the alternative.
+
+The result is a fabricated plan. A person who asked the agent to plan work that already exists, or
+who said not to plan at all, received a plan anyway: the harness's own instruction outranked the
+person's, and the repair repeated it. Two live cases in one harness test session did exactly that —
+a no-op plan whose only content restated the request, and then, after the person rejected it, a
+second plan produced by the repair turn. The appetite for a required artifact had already been
+rejected elsewhere: ADR-0074 removed the required report blocks, and ADR-0075 removed the stop gate.
+
+A second defect sits beside the first. Tag accounting was a raw substring count over the whole
+reply, so a reply that quoted plan syntax inside a fenced or inline code block declared extra
+outcomes and became `invalid`. That is how a plan *about* the plan tags failed its own parser.
+
+## Decision
+
+Add `no_plan` to the plan outcome contract:
+
+| Reply ending | Outcome |
+|---|---|
+| One complete, nonempty `<proposed_plan>` block, outside code | `plan_ready` |
+| One complete, nonempty `<plan_blocked>` block, outside code | `blocked` |
+| No outcome tag at all, nonempty text | `no_plan` |
+| Unbalanced, empty, duplicated or conflicting tags; legacy `<plan_clarification>`; empty reply | `invalid` |
+
+- `no_plan` is a conclusion, not a failure. It offers no plan card, no Implement, no notice and no
+  warning in any surface, and it never costs a second model request.
+- The plan section says that a reply with no block is a valid ending, that the model must check
+  whether the requested work already exists before designing it, and that a person's instruction
+  not to plan outranks the mode's output shape.
+- The repair keeps its one bounded attempt, the same run and the same tool gate, but exists only
+  for `invalid`: a block the model started and left incomplete, empty or in conflict. It may finish
+  that block, may state that there is nothing to plan, or may return the blocked block. It may not
+  re-plan, research again, invent a decision or invent work to fill a block.
+- Tags outside fenced and inline code alone declare an outcome; a quoted example is text. The rule
+  matches the one the App already used to split a plan out of a reply.
+
+The outcome stays derived from reply text. No run event, run-record field, storage layout, server
+method or host schema changes, so clients that understand only the plan tag keep working.
+
+## Rationale
+
+The contract conflated *format* with *outcome*. Once the artifact is the only way to answer, every
+honest "nothing to do" becomes a lie about the work, and the repair turn is the machinery that asks
+for the lie. Making the empty conclusion explicit fixes the cause instead of the symptom, and it
+keeps the plan card exactly where it is useful: on a reply that actually contains a plan.
+
+Text-derived classification is cheaper than the alternatives. A `no_plan` tag would still demand an
+artifact for every request. A plan tool would change the tool list at the moment the mode switches,
+changing the cached prompt prefix in headless runs, and would need a new renderer path in the
+terminal and the App. A declared free-text line (`No plan needed: …`) adds a phrase the model must
+remember and makes its absence ambiguous again.
+
+## Consequences
+
+- A plan request that needs no plan answers in ordinary prose. The person sees no card and no
+  warning, and the turn costs one request instead of two.
+- A model that forgets the block for a real plan now loses the card and the Implement choice
+  silently. The reply text remains, and asking again produces the plan; the alternative was to keep
+  demanding an artifact that is sometimes fiction. The plan section still makes the block the
+  default when there is work to design.
+- Plan mode read as "research-only mode" rather than "always produce a plan", which is what a bare
+  `/plan` toggle already meant in practice.
+- Quoted or fenced plan syntax no longer invalidates a reply, so a reply may discuss the format
+  without being repaired.
+- `blocked` is unchanged: it still reports a required decision that `ask_user` could not obtain, and
+  the terminal still warns about it.
+- New final replies still must not use `<plan_clarification>` or free-text questions; `ask_user`
+  remains the clarification channel.
+
+## Alternatives
+
+- **Keep requiring a block and allow a "nothing to do" sentence inside it.** Rejected: that is the
+  ceremony the defect is about, and it makes a no-op plan look like a plan.
+- **Add a `<no_plan>` tag.** Rejected: symmetric and simple to parse, but it still forces an
+  artifact and a repair for every request, so the person's "do nothing" instruction is again
+  overridden.
+- **Add a plan tool.** Rejected for now: it changes the tool list and the cached prompt prefix, and
+  needs new renderer paths in both surfaces, for a problem a classification change solves.
+- **Drop the repair entirely.** Rejected: an incomplete block is a real, observable failure, and one
+  bounded turn fixes it without costing the card.
+- **Keep raw substring counting.** Rejected: a reply that quotes the tags was already misclassified,
+  and with `no_plan` in place the false `invalid` would trigger the repair for a correct answer.
+
+## Checks
+
+`src/sessions/planMode.test.ts` covers the outcome table, the code-fence rule, repair exclusion for
+`no_plan` and the instruction text. `src/sessions/sessions.test.ts` covers a plain no-plan reply
+with no repair and no warning, a repaired no-plan reply, and a malformed block repaired once.
+`src/terminal/piExtension.lifecycle.test.ts`, `src/terminal/opentui/app.test.ts` and
+`src/terminal/tui/runtime.socket.test.ts` cover the same contract at the terminal's settlement
+boundary and in the plan choice. The App needs no code change: it renders a card only for a complete
+block and shows nothing otherwise.

package/docs/decisions/ADR-0078-child-aware-stall-watch.md

@@ -0,0 +1,46 @@
+---
+id: ADR-0078
+title: A reply waiting on subagents is judged by its children, and the working row names the wait
+status: accepted
+created: 2026-11-01
+updated: 2026-11-01
+related:
+  - ADR-0054
+---
+# ADR-0078 — A reply waiting on subagents is judged by its children
+
+## Context
+
+Run `da1a7e39` ("Fix follow-up steering UX") looked stuck for 19 minutes: a spinner and a random
+verb on the working row, a spinning subagent, and a trajectory of 40 identical heartbeats. Nothing
+was wrong. The parent was inside `wait_subagents` and its child (run `5cd1d8aa`) did a tool call or
+a model request every minute until it finished. The person could not tell that from a hang, and the
+harness could not either: the stall watch saw one tool running (30-minute limit) and none of the
+child's progress, so a child that really wedged would have held the parent for half an hour and then
+ended the parent, not the child.
+
+Two other limits made real outages worse: Pi's default of three retries at 2, 4 and 8 seconds ended a
+reply after about fourteen seconds of network trouble, and the retry showed only as a passing toast.
+
+## Decision
+
+- Each subagent the terminal reply waits on has its own stall clock in `TerminalController`: its last
+  event other than a heartbeat and the tools it is inside. A child quiet for the reply window (15
+  minutes) or inside one tool for the tool window (30) is interrupted with reason `stalled`; the wait
+  returns it as `interrupted` and the parent continues without the person.
+- While the only running tools of the reply are `wait_subagents` or `spawn_subagent`, the parent's own
+  rule is paused as long as a child answers to its own watch. It resumes if no child is tracked or a
+  child ignored the stop for five minutes.
+- Heartbeats carry `activeTools` and `oldestToolMs`; the trajectory page shows what a beat was
+  inside and folds runs of beats into one row.
+- The working row names the phase (waiting on subagents, a long tool, a silent model, a retry
+  countdown) in place of the verb whenever the verb would hide it.
+- Model requests that fail for a transient reason are retried up to eight times over about four
+  minutes. A person's own `retry` settings are kept.
+
+## Consequences
+
+A long, healthy wait is no longer cut short, and a wedged child no longer costs the parent. The
+retry budget lengthens the time before a real outage reaches the person, and the row shows the
+countdown meanwhile. Constants (15 and 30 minutes, five-minute grace, eight retries) are unchanged
+or new knobs in `stallWatch.ts` and `retryPolicy.ts`.