@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/study/00-index.md

@@ -0,0 +1,112 @@
+# Harness arm study — index
+
+An audit of agent-harness designs, arm by arm: where each studied harness puts its
+prompt assembly, tools, memory, subagents, skills, context management, refinement,
+governance, execution and observability, and what to adopt into this harness.
+
+Positioning: this is analysis, not checked source behavior. Living contract docs and
+decisions stay in `docs/`; when a study produces an actual change here, an ADR is
+written and the claim moves to checked behavior. Cite material as
+`external/<name>/<path>:<line>` — never second-hand summaries.
+
+## Focused notes
+
+- [Proactive autonomy and three feature directions](proactive-autonomy.md) — scheduled initiative,
+  a human-readable agenda, UI repair, cleanup and product experiments; fresh
+  [proactive-system evidence](autonomy-sources.md) and
+  [autonomous-engineering evidence](autonomous-engineering-sources.md). Research hypotheses,
+  not an accepted architecture change.
+- [`/btw` side-question comparison](btw-comparison.md) — this terminal, the App-owned
+  side question, and checked-out external implementations.
+- [Harness feature-gap review](feature-gap-review.md) — task/goal management, long-running work,
+  memory, execution isolation, verification, and observability gaps against the studied peers.
+- [Why a long run takes hours](STUDY-0003-long-horizon-runs.md) — measured diagnosis of two 70–97
+  minute replies (447 and 266 tool calls, 5 and 2 compactions, zero assistant text), what other
+  harnesses do about it, and the fixes proposed in [PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md).
+- [How other harnesses control the end of a turn](STUDY-0004-turn-end-controls.md) — stop hooks,
+  completion tools, follow-up loops and lint-driven re-prompts across ten harnesses, with sources;
+  why a self-ended reply settles `completed` here, and the one deterministic layer to add.
+- [How peers shape the final report](STUDY-0006-reporting-prompts.md) — the final-answer rules of
+  Claude Code, Codex and Kimi; what this harness's 3,400-character reporting section lacked; and the
+  large content-block prompt in [ADR-0073](../decisions/ADR-0073-large-reporting-prompt.md).
+- [Claude Code's prompt against this harness's, in 20 areas](STUDY-0007-claude-code-prompt.md) — the
+  leaked v2.1.88 prompt measured against the pack a real session was given: 12.9k characters against
+  23.4k, the 9.2k reporting section with no Claude Code counterpart, and the rules Claude Code has
+  that the harness does not (parallel calls, read-before-edit, minimal diffs).
+- [How Codex and Claude Code use the person's browser](STUDY-0008-browser-control.md) — Claude Code drives
+the person's own Chrome as a built-in MCP server with refs, console, network and JavaScript; Codex has
+no browser in the CLI and reaches the person's browser only through Computer Use and its extension,
+keeping a separate-profile built-in browser of its own; this harness now offers isolated Chromium,
+App WebKit, and an explicitly paired Brave extension through shared browser tools. The Brave bridge
+is implemented with live disposable-profile acceptance still pending; see [ADR-0082](../decisions/ADR-0082-connected-brave-browser.md).
+- [Claude Code's report structure against this harness's, phase by phase](STUDY-0009-claude-code-reporting.md)
+  — the leaked v2.1.88 external and internal prompts plus the published Concise style against the
+  original 3,696-character reporting section: audience, pre-tool text, in-flight updates, first
+  sentence, change content, evidence, next steps, headers, tables, length, references and examples.
+  Neither Claude Code build requires headers; ADR-0079 records the Harness's choice to encourage
+  content-named `#` / `##` headings in substantial reports.
+- [Does the harness tell an agent how to install a skill](STUDY-0005-skill-installation-guidance.md)
+  — the global and project routes this harness already loads, checked with its own resolver; why a
+  session model is told none of them; and how Codex, Gemini, Claude Code, Kimi and others put that
+  knowledge in a bundled skill instead of the prompt.
+
+## Sources
+
+Clones live in `external/` (this repo). Field notes in `sources/`.
+
+| Source | Origin | Note | Stage |
+|---|---|---|---|
+| opencode | [sst/opencode](https://github.com/sst/opencode) — TypeScript, the tool this harness family runs sessions in | [opencode.md](sources/opencode.md) | arm-01 audited |
+| pi / omp | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) — tuned fork of [pi-mono](https://github.com/badlogic/pi-mono), the session runtime underneath this harness | [omp.md](sources/omp.md) | arm-01 audited |
+| deepseek-harness (`dsh`) | [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — MIT, Cordis, "everything is a plugin" | [deepseek-harness.md](sources/deepseek-harness.md) | arm-01 audited |
+| harness2 | [google-research/harness2](https://github.com/google-research/harness2) + paper *Harness²: Recursive Agent Harnessing for an Open World* (arXiv:2610.14224, PDF in the clone) | [harness2.md](sources/harness2.md) | arm-01 audited |
+| swe-agent | [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) | [swe-agent.md](sources/swe-agent.md) | inventory |
+| openhands | [All-Hands-AI/OpenHands](https://github.com/All-Hands-AI/OpenHands) (UI) + [OpenHands/software-agent-sdk](https://github.com/OpenHands/software-agent-sdk) (agent server runtime) | [openhands.md](sources/openhands.md) | inventory |
+| kimi-cli | [MoonshotAI/Kimi-CLI](https://github.com/MoonshotAI/Kimi-CLI) | [kimi-cli.md](sources/kimi-cli.md) | inventory |
+| smolagents | [huggingface/smolagents](https://github.com/huggingface/smolagents) — CodeAct | [smolagents.md](sources/smolagents.md) | inventory |
+| claude-code | [Anthropic Claude Code](https://www.anthropic.com/claude-code) — not open source; the leaked v2.1.88 source map gives a full read | [claude-code.md](sources/claude-code.md) | v2.1.88 source in `external/claude-code-src`, prompt audited |
+
+## Arms
+
+One doc per arm: *design space → per-source comparison → trade-offs → adoption
+candidates*. Adoption candidates feed a two-tier roadmap: Tier 1 = patterns already
+battle-tested in open harnesses (OpenCode / pi / dsh); Tier 2 = research-backed ideas
+(harness² and the literature) attempted after Tier 1.
+
+| # | Arm | Doc | Stage |
+|---|---|---|---|
+| 1 | System prompt / context assembly | [arms/01-system-prompt.md](arms/01-system-prompt.md) | core four audited (opencode, omp, dsh, harness²); 5 sources pending |
+| 2 | Tools | [arms/02-tools.md](arms/02-tools.md) | core four audited (opencode, omp, dsh + harness²/swe-agent/smolagents in person); partial |
+| 4 | Subagents | [arms/03-subagents.md](arms/03-subagents.md) | core four audited; openhands/claude-code pending |
+| 5 | Skills & loading | [arms/04-skills.md](arms/04-skills.md) | three sources audited (dsh, opencode, harness²) + our tree; omp partial |
+| 6 | Context management | [arms/05-context-management.md](arms/05-context-management.md) | core three audited; ours needs inventory |
+| 3 | Memory | [arms/06-memory.md](arms/06-memory.md) | core four audited + our Wiki |
+| 8 | Governance | [arms/07-governance.md](arms/07-governance.md) | core three audited; claude-code/openhands pending |
+| 9 | Execution | [arms/08-execution.md](arms/08-execution.md) | core three audited; hands pending |
+| 10 | Observability | [arms/09-observability.md](arms/09-observability.md) | core three audited; hands pending |
+| 7 | Refinement / self-improvement | [arms/10-refinement.md](arms/10-refinement.md) | **done in person — port confirmed**; judge delta + drift sync open |
+
+Wide comparison: [arms/00-matrix.md](arms/00-matrix.md). Standing conclusions:
+[insights.md](insights.md). Roadmap: [roadmap.md](roadmap.md).
+
+## Work order
+
+1. `sources/` inventories (all nine), then arms 01–02 (prompt, tools)
+2. Arms 03–06 (subagents, skills, context management, memory)
+3. Arms 07–09 (governance, execution, observability)
+4. Arm 10 (refinement ⭐ — the merge study against harness²) + `roadmap.md`
+5. `arms/00-matrix.md` last, from the finished arm docs
+
+## Method rules
+
+- **Ground truth first.** Read the code before forming a position; every claim in an
+  arm doc needs at least one `path:line` citation per source, or an explicit
+  "unverified".
+- **Describe, then judge.** The comparison table states what each harness does; the
+  trade-off section says why; only `adoption candidates` mentions this harness.
+- **Respect the boundary.** Nothing here changes `src/`; study docs name no product
+  concept that the harness would learn. Adoption goes through the extension-point
+  flow later.
+- **The anchor arms are the seven surfaces.** Prompt sections, tool providers,
+  `ToolPolicy`, `SecretStore`, `Directory`, plugin descriptions, `RefineHost` — map
+  foreign mechanisms onto these without inventing application concepts.

package/docs/study/STUDY-0003-long-horizon-runs.md

@@ -0,0 +1,210 @@
+---
+id: STUDY-0003
+title: Why a long run takes hours — measured diagnosis of two long sessions
+status: measured-diagnosis; fix proposed in PROP-0041
+created: 2026-10-26
+updated: 2026-10-26
+related:
+  - PROP-0033
+  - PROP-0041
+---
+
+# Why a long run takes hours
+
+**Answer.** Neither session was looping on a single action — both kept changing files and running checks. But both ran as **one unbroken reply**: 448 and 274 tool calls, 5 and 2 context compactions, and a single assistant message at the very end, or none at all. The 75-minute session produced one final report and said **"release is still blocked"**. The other was **still running at 114 minutes when measured, with 448 tool calls and not one word to the person**. 41 of those minutes were three Playwright runs, 25 of them on two timeouts, and 55 minutes were 307 model requests averaging 10.7 s each over a ~140k-token context.
+
+The loop is in the **shape of the reply**, not in the goal. The fix is not a better prompt; it is a bounded reply, a durable checkpoint, and a loop guard. [PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md)
+proposes them.
+
+## What was measured
+
+Both sessions are ordinary records under the dev data root
+(`~/.xingular-harness-dev/data/runs/<id>/`), read together with their native Pi session. Nothing was
+re-run; every number below comes from `events.jsonl`, `run.json` and the native `*.jsonl`.
+
+| | A — "Finish App Harness parity integration" | B — "Complete secure Harness release candidate" |
+|---|---|---|
+| Run | `64cdd5f0` | `2d62eaec` |
+| User text that started it | "continue where you left of" | "continue where left of" |
+| Started / last event | 17:50:43Z / 19:44:57Z at the cut, still active | 18:27:46Z / 19:42:40Z |
+| Wall clock | **114.3 min at the cut, still running** | **74.9 min** |
+| How it ended | no end: the same reply was still going | one final report, `completed` |
+| Recorded state afterwards | `running` | `completed` |
+| Model requests | 307 | 197 |
+| Model time | 3299 s (55.0 min), mean 10.7 s, p90 20.0 s | 2924 s (48.7 min), mean 14.8 s, p90 30.4 s |
+| Tool calls | 448 | 274 |
+| Tool time | 3491 s (58.2 min), 51 % of the run | ~1420 s (23.7 min), 32 % |
+| Reads | 163 over 96 paths (`host.rs` 11×) | 101 over 56 paths (`verify-terminal.py` 6×) |
+| Edits | 61 over 35 files (`app.test.ts` 10×) | 78 over 30 files (`07-tools-and-gate.md` 9×) |
+| Identical repeated calls | 42 instances, 20 signatures | 10 instances, 5 signatures |
+| Billed tokens | 18.85 M input + 25.01 M cache read | 16.70 M input + 12.94 M cache read |
+| Output tokens | 221 k, of which 175 k reasoning (79 %) | 205 k, of which 173 k reasoning (84 %) |
+| Cost recorded by the harness | $2.23 | $1.66 |
+| Compactions inside the run | **5**, at 255 852–269 591 tokens | **2** (7 across the 5-hour thread) |
+| Cold re-sends (no cache read, >20 k input) | 9 requests, 1.58 M uncached tokens | 9 requests, 1.51 M uncached tokens |
+| Assistant text inside the run | **0 characters** | **0 characters until 74.9 min**, then one 2 028-character report |
+| Approvals | 49, all remembered, 0.0 s wait | 2, both remembered |
+
+Run A was still producing events while this was written (314 model requests at 19:48Z); every number
+for it is frozen at 19:44:57Z, 114.3 minutes in. Run B had already settled.
+
+### Where run A's 114 minutes went
+
+| Bucket | Time | Share |
+|---|---|---|
+| Model requests (307) | 55.0 min | 48 % |
+| Bash (129 calls) | 57.6 min | 50 % |
+| — three Playwright runs: 600 s timeout, 900 s timeout, 986 s success | 41.4 min | 36 % |
+| Reads, edits, searches, subagent waits | ~0.5 min | 1 % |
+| Unaccounted idle | ~1.2 min | 1 % |
+
+The harness was busy for 98.5 % of the wall clock. Nothing was hung; the reply was simply too long,
+and every step paid full-context latency. The same browser suite ran three times because it timed out
+twice without narrowing itself, and each retry cost the full command budget.
+
+That 986-second command is also why a heartbeat matters: from request 306 at 19:27:56 to request 307
+at 19:44:29 there is **no event for 16.6 minutes**. A busy run and a wedged one look identical on the
+record.
+
+### Was it progressing?
+
+Yes, measurably:
+
+- 57 `file.changed` events in A at a steady rate (13, 6, 9, 6, 4, 9, 10 per ten minutes), longest gap
+  between changes 23.6 min; 74 in B, longest gap 17.5 min.
+- 57 successful test/typecheck commands in A; 28 of 129 Bash calls failed and were retried.
+- The checklist moved (B: 3 of 7 items completed across 9 checklist writes, and items were added as
+  gaps were found).
+- B's last message is a real report: what changed, which checks passed (1 255 Harness tests, 586 App
+  tests, 185 Rust tests), and what remains blocked. That is genuine incremental work with an honest
+  ending — after 75 minutes and 274 tool calls.
+
+But the same data shows the waste:
+
+- 42 calls in A were byte-identical repeats of an earlier call; 20 distinct signatures were repeated.
+- `host.rs` was read 11 times; `07-tools-and-gate.md` was edited 9 times as the checklist reworded
+  what "done" meant.
+- Run B read its own trajectory 63 times and searched it 8 times — recovering, inside the run, state
+  that earlier compactions had dropped.
+- Neither session produced a commit. The worktree is still dirty: B's own report counts 119 tracked
+  changes and 267 untracked files, which failed release preflight's clean-tree check. So "continue
+  where you left off" had no unambiguous answer — the work is real, but it is not a deliverable.
+- A's checklist was rewritten 7 times (B's 9) and its items were reworded each time
+  ("Complete Harness launch…" → "Complete App commands…" → "Complete App shared-profile…" →
+  "Close profile-root migration…" → "Finish App shared-profile…"). That is scope drift, not a
+  maintained plan.
+
+So: **incremental work, at roughly half efficiency, with no visible progress and no way to stop
+cleanly.** A person watching saw tool rows for 75–114 minutes, then either a single report or nothing
+at all.
+
+## The mechanisms that are missing
+
+Measured against the code (all verified in this tree):
+
+| Mechanism | State in this tree | Consequence |
+|---|---|---|
+| Reply budget | Only the opt-in `budget-guard` plugin (`src/plugins/firstParty.ts:31,105-140`), **off by default** and a blunt stop: it refuses tools and terminates the reply with no checkpoint | One reply ran 114 min and 448 calls |
+| Checkpoint | PROP-0033's checkpoint exists (`src/sessions/compactionCheckpoint.ts`), but it restores only *goal + checklist + plan*, and `renderCompactionCheckpoint` returns `null` when there is no checklist (`src/prompt/compile.ts:196`) | No files, no failing commands, no decisions; A wrote no assistant text at all |
+| Compaction discipline | Pi compacts at ~94 % of the window; the harness only observes it (`src/sessions/runner.ts:470-478`) | 5 compactions in one reply, each a cold re-send; state rebuilt by re-reading files |
+| Command ceiling | Bash `timeout` is optional, "no default timeout" (`src/core/workspaceBashTool.ts:23`) | 41 minutes in three Playwright runs; 36 % of run A |
+| Loop / stall detection | None (`rg loop|stuck|repeat` finds nothing in `src/sessions`) | 42 duplicate calls; 9 edits to one document |
+| Liveness | Reconciliation runs only at startup and is keyed on the owner pid (`src/sessions/runStore.ts:228`); `owner.json` holds a bare pid | A run that stops producing events while its process lives is never settled, and a recycled pid can make a dead owner look alive. A long command already writes nothing for 16.6 minutes |
+| Progress visibility | No mid-reply text requirement; `REPORTING_GUIDANCE` shapes only the final reply | 0 characters in 114 minutes and counting for A; one message at 74.9 minutes for B |
+
+The layer boundary matters for the fix: task and goal lifecycle belong to the application
+(`docs/study/feature-gap-review.md:7,35`). Everything above is **run execution**, which the harness
+owns. PROP-0041 keeps it there.
+
+## What other harnesses do about this
+
+Fetched 2026-10-26; URLs are the primary sources.
+
+| Mechanism | Who | Trigger | What it prevents |
+|---|---|---|---|
+| Stop hook that blocks the turn from ending until a check passes, with a cap on consecutive blocks | [Claude Code](https://code.claude.com/docs/en/best-practices) | Turn end | "Looks done" endings and endless turns |
+| Auto-compaction thrash guard: after a few refills, stop compacting and report the offending oversized result | [Claude Code troubleshooting](https://code.claude.com/docs/en/troubleshooting) | Repeated compaction in one turn | Summarise–refill loops |
+| Post-compaction re-injection of the plan file and up to five recently touched files (path only above 5k tokens) | [Claude Code context window](https://code.claude.com/docs/en/context-window) | Compaction | State lost to the summarizer |
+| Tool-result clearing before summarisation | [Anthropic context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | Context pressure | Unbounded context growth |
+| Subagents with a 1–2k-token return contract | [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents) | Model decision | Exploration flooding the main context |
+| `todo.md` recitation at the end of context; restorable compression (drop content, keep URL/path); keep failed actions | [Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) | Every step / compression | Goal drift, repeated mistakes |
+| Loop detection by hashing `toolName + args`, cycle length 1–5 repeated 5×, plus an LLM judge after 30 turns | [Gemini CLI loopDetectionService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/loopDetectionService.ts) | Every streamed tool call | Oscillation and repeated failing commands |
+| Stop hook with `loop_count` and `MAX_ITERATIONS = 5` | [Cursor](https://cursor.com/blog/agent-best-practices) | Turn end | Unbounded single turn |
+| `max_requeries = 3` on malformed or blocked actions | [SWE-agent config](https://swe-agent.com/latest/reference/agent_config/) | Action error | Infinite retry |
+| Repo map under a 1k-token budget (PageRank over the dependency graph) | [Aider repomap](https://aider.chat/docs/repomap.html) | Every request | Re-reading files to re-orient |
+| Auto-commit, lint and test after each edit | [Aider git](https://aider.chat/docs/git.html) | Each edit | Long stretches with no checkpoint |
+| Event-count condenser that keeps the first events | [OpenHands context condenser](https://docs.openhands.dev/sdk/guides/context-condenser) | History size | Cost and latency growth |
+| Pre/post-turn compaction phases and pre/post-compact hooks | [Codex compact.rs](https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/compact.rs) | Turn boundaries | Unpredictable compaction |
+| Truncate-then-summarise plan saved to memory because the window will truncate | [Anthropic multi-agent research](https://www.anthropic.com/engineering/multi-agent-research-system) | Context limit | Losing the plan |
+
+Two reference scales are worth stating plainly: Manus reports **~50 tool calls per task**, and
+Claude Code's published loop cap is **5 iterations**. Both runs here exceeded those by 5–9× inside a
+single reply that addressed the person once, at the end, or not at all.
+
+Context rot compounds it: performance degrades as input grows and is worst for content in the middle
+of a long context ([Chroma](https://www.trychroma.com/research/context-rot),
+[Lost in the middle](https://arxiv.org/abs/2307.03172)). A 250k-token context is therefore both slow
+and less reliable — the re-reads and reworded checklists are what that looks like.
+
+## What to adopt, in order
+
+1. **P0, configuration only, today.** Switch on `output-trim` (20 000 chars) and `budget-guard`
+   (120 requests) in the plugin attachments of the affected account/project. That alone caps the
+   reply and shrinks tool results. No architecture change, reversible per account and per project.
+2. **P0b, small foundation fixes.** A default Bash timeout that returns partial output, and a stall
+   watchdog keyed on heartbeat age rather than only the owner pid. Both are narrow and independent of
+   the slice design below.
+3. **P1, bounded work slices (PROP-0041).** A reply budget of 160 tool calls / 40 min / 320k new
+   tokens, a validated checkpoint at the boundary, and a continuation that starts from that
+   checkpoint. This is the structural fix.
+4. **P2, the checkpoint as state, not prose.** Bounded, evidence-linked (files, failing checks,
+   decisions, next step) and injected at every slice start and after compaction, so the model never
+   re-derives state by archaeology.
+5. **P3, deterministic loop guard.** Identical `tool + args` three times, the same command failing
+   twice, or 25 steps with no file change and no passing check: nudge once with the evidence, then
+   end the slice as `blocked`.
+6. **P4, command budget.** Hard ceiling, and long suites (Playwright, full CI) as background work
+   rather than 16 blocking minutes.
+7. **P5, compaction pipeline.** Clear old tool results first; summarise with restorable references
+   (path + line range); stop after three compactions in one reply and hand off instead.
+8. **P6, visible progress.** Record narration as `progress` events and a heartbeat with steps,
+   elapsed time, slice and compactions; show "next checkpoint in N steps" in both surfaces.
+
+## How to judge whether it worked
+
+Baseline from these two runs, to compare after PROP-0041:
+
+| Metric | Baseline |
+|---|---|
+| Time to first user-visible text | never (A) / 74.9 min (B) |
+| Tool calls per user-visible text | ∞ (A) / 274 (B) |
+| Longest reply | 114 min and counting / 448 calls |
+| Compactions per reply | 2–5 |
+| Repeated identical calls | 42 per 448 (9 %) |
+| Reads per distinct file | 1.7 (163/96), worst 11 |
+| Time in three Playwright runs | 36 % of run A |
+| Runs left `running` after owner death | 1 of 2 |
+
+A working slice policy should keep the longest reply under ~45 minutes, put text in front of the
+person at every boundary, hold compactions to at most one per slice, and never leave a run
+`running` after its owner is gone.
+
+## What this does not fix
+
+Model latency per token, the correctness of the work itself, or a task whose acceptance criteria
+were never written down. A slice boundary cannot invent a definition of done; it can only make the
+absence of one visible early.
+
+## Appendix: how to reproduce
+
+Read-only, from the dev data root:
+
+```sh
+R=~/.xingular-harness-dev/data/runs/64cdd5f0-da45-43a1-9130-89c54f298f21
+jq -r 'select(.type=="usage.updated") | .payload.request.durationMs' "$R/events.jsonl" | awk '{s+=$1/1000; n++} END {print n" requests, "s" s"}'
+jq -r 'select(.type=="tool.completed") | .payload.name' "$R/events.jsonl" | sort | uniq -c | sort -rn
+jq -r 'select(.type=="message.completed") | .payload.role' "$R/events.jsonl"
+```
+
+The assistant's own text lives in the native session named by `run.json`
+(`nativeSessionId`), as `message` entries whose `content` blocks have `type: "text"`.

package/docs/study/STUDY-0004-turn-end-controls.md

@@ -0,0 +1,130 @@
+---
+id: STUDY-0004
+title: How other harnesses stop a turn early — and what to adopt
+status: adopted-with-changes
+created: 2026-10-30
+updated: 2026-10-31
+related:
+  - STUDY-0003
+---
+# How other harnesses control the end of a turn
+
+> **Update (2026-11-01, [ADR-0075](../decisions/ADR-0075-no-todo-gate.md)):** the todo gate is
+> removed. A peer check found that omp ships the same three-reminder gate on by default
+> (`todo.remindersMax` 3), while Claude Code only reminds the model to use TodoWrite
+> (`ccVersion` 2.1.139), Codex's `update_plan` is opt-in (0.152) and Kimi CLI has no nudge. A reply
+> the model ends now settles `completed`; the goal loop and the work-slice guard keep their stop
+> codes and checkpoints.
+
+> **Update (2026-11-01, [ADR-0072](../decisions/ADR-0072-codex-prompts-and-goal.md)):** OpenAI Codex is open source. It has no completion check on ordinary turns and keeps its model-called `update_goal` behind an opt-in `/goal`. The harness followed: ordinary replies rely on Codex's prompt wording and the todo gate, and the judge now checks a `/goal` completion claim only.
+
+> **Update (2026-10-31, [ADR-0071](../decisions/ADR-0071-completion-check.md)):** the model-judged evaluator rejected above was adopted after all, as an automatic completion check on the run's own model, because a live A/B showed a closed todo list hiding unfinished work and `finish(needs_decision)` used as an early exit; `finish` is removed.
+
+> **Outcome (2026-10-31):** adopted with changes in [ADR-0069](../decisions/ADR-0069-stop-gate-and-finish.md).
+> - **Gate placement.** The continuation is a stop gate at Pi's `agent_before_settle` boundary
+>   inside the same run, not a widened `continueSlice`. That covers the terminal and avoids
+>   reopening a `completed` run.
+> - **Cap.** Three nudges per reply, plus a no-progress rule.
+> - **`finish` tool.** Added as the explicit way to stop for the person.
+> - **`checkpoint_write` removed.** Run `62c7fc6c` used it as a sign-off and stopped with work open.
+
+**Recommendation:** keep the prompt rules that landed today (scope of the work, the end rule, two
+completion headings) as the cheap layer, and add **one** deterministic layer: let the existing
+work-slice policy continue a reply that ended by itself while the run's todo list still holds an
+open, unblocked item — the same machinery that already continues a budget-ended slice, with a cap
+and the same guards. Do not adopt a model-judged evaluator, and do not adopt unconditional
+"keep going" loops.
+
+This note is analysis. It changes no contract; the prompt change it refers to is recorded in
+[ADR-0068](../decisions/ADR-0068-scope-and-completion-report.md) and
+[04-prompt.md](../architecture/04-prompt.md#when-a-reply-may-end).
+
+## Why this note exists
+
+207 of 822 runs in the week to 2026-10-30 ended with work left, at a median of 17 tool calls, and 191
+of those wrote no checkpoint. The clearest case, `d73804c8`, ended at 63 of 320 tool calls with
+B3–B10 of a handoff untouched and no approval, question, refusal or compaction in the record
+(`outputs/diagnoses/2026-10-30-d73804c8.md`). The prompt was the first lever; this note asks what
+harnesses with more users do about the same failure.
+
+## What Xingular does today (verified in this repository)
+
+| Mechanism | Where | What it can do |
+|---|---|---|
+| Work-slice guard | `src/sessions/workSlice.ts:40` (320 calls / 60 min / 8 slices), refusal path and derived checkpoint in `src/sessions/runner.ts:710` | Ends a reply at the budget and records `interrupted{slice_complete}` |
+| Slice continuation | `src/sessions/sessions.ts:410` `continueSlice` | Starts the next slice as a new run — but only when `terminalReason === 'slice_complete'`, the slice progressed, no checkpoint is `blocked`, and it is not automatic, plan, command or a worktree run |
+| Continuation by request | `src/sessions/continuation.ts:60`, `continueFrom`, `runs.continuation`; `CONTINUE_TEXT` = "Continue from where you stopped." (`src/sessions/sessions.ts:157`) | The host or a subagent's parent can reopen a stopped run with its pinned account, variant and capability set |
+| Plan repair | `src/sessions/runner.ts:702` (`PLAN_REPAIR_INSTRUCTIONS`, `triggerTurn: true`) | Re-asks once for a missing plan block |
+| Human affordance | App `src/app/AppState.tsx:353` (notice only for `interruptedRuns`), `Continue` on a paused reply | The person resumes; the app never continues by itself |
+
+The gap is exact: a reply the model ends by itself settles `run.finish('completed')`
+(`src/sessions/runner.ts:718`) and `continueSlice` returns at its first check
+(`terminalReason !== 'slice_complete'`). So the layer that already exists never fires for the
+failure mode that dominates the record. `INV-RUN-4` allows this: continuing is always a new run with
+`continueFrom`, asked by the application **or the work-slice policy** (`INV-RUN-13`).
+
+## What other harnesses do (live documentation, read 2026-10-30)
+
+| Harness | Mechanism (exact name) | Trigger | What it can force | Source |
+|---|---|---|---|---|
+| Claude Code | `Stop` / `SubagentStop` hook returning `decision: "block"` with a required `reason`; `hookSpecificOutput.additionalContext` | "Runs when the main Claude Code agent has finished responding" | Keeps the model working; the `reason` is fed back | <https://code.claude.com/docs/en/hooks> |
+| Claude Code | `/goal` — a separate small-model evaluator | Each reply end | Judges whether the goal is met; stops when there is no tool use "for several turns in a row" | <https://code.claude.com/docs/en/goal> |
+| OpenAI Codex CLI | `Stop` hook, `{"decision":"block","reason":…}` or exit code 2 | Turn stop; input carries `stop_hook_active`, `last_assistant_message` | "tells Codex to continue and automatically creates a new continuation prompt" | <https://learn.chatgpt.com/docs/hooks> |
+| Cursor | `stop` hook output `followup_message`; input `loop_count`; `loop_limit` (default 5, `null` = uncapped) | "Called when the agent loop ends" | Submits the message as the next user turn | <https://cursor.com/docs/hooks> |
+| Amp | Plugin hook `agent.end` returning `{ action: 'continue', userMessage }` | End of a turn | Starts another turn | <https://ampcode.com/docs/plugin-api> |
+| Cline | Completion tool `submit_and_exit`; plugin hooks can only end a run | Model calls the tool | Nothing — a text-only reply ends the turn | <https://docs.cline.bot/tools-reference/all-cline-tools.md> |
+| OpenHands | `finish` tool (`FinishAction`) | Model calls `finish` | Nothing; its description permits finishing when "you cannot proceed further due to technical limitations" | <https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/builtins/finish.py> |
+| Gemini CLI | `complete_task` tool (`CompleteTaskTool`) | Model calls it | Nothing, but the strictest completion wording found: "This is the ONLY way to finish" | <https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/complete-task.ts> |
+| Aider | `--auto-lint` / `--auto-test` / `/test` | Non-zero exit of the lint/test command after an edit | Re-prompts until the command passes — failure-driven, not confession-driven | <https://aider.chat/docs/usage/lint-test.html> |
+| Goose | unconfirmed — `final_output` not located in two fetches | — | — | — |
+| OpenCode | No stop hook; `session.idle` is an observational event | — | Nothing | <https://opencode.ai/docs/plugins/> |
+
+## Failure modes these documents themselves record
+
+- **Runaway refusal.** Claude Code "overrides a Stop hook after it blocks eight times in a row with no
+  tool call"; a hook must check `stop_hook_active` or it "block[s] on a condition that will never
+  resolve". <https://code.claude.com/docs/en/hooks-guide>
+- **Per-reply cost.** "`Stop` hooks fire whenever Claude finishes responding, not only at task
+  completion" — a verification hook runs on every reply, trivial ones included.
+  <https://code.claude.com/docs/en/hooks-guide>
+- **A judge cannot act.** `/goal`'s evaluator "does not call tools, so it can only judge what Claude
+  has already surfaced".
+- **Uncapped loops are a switch, not an accident.** Cursor exposes `loop_limit: null`.
+- **Conflicting controls.** Codex: "If any matching `Stop` hook returns `continue: false`, that takes
+  precedence over continuation decisions."
+- **Completion tools do not check the world.** OpenHands `finish` and Gemini `complete_task` validate
+  only that the final message is non-empty; a model that declares done is believed. (Inference from
+  both sources — no harness documents a done-ness check at the tool boundary.)
+
+## What to adopt, in order
+
+1. **Scope + headings (landed today).** `ROLE` now names the job the request implies and its bounds;
+   `REPORTING_GUIDANCE` requires `## Beyond what you asked` and `## What would make this complete`.
+   Zero runtime risk, no new state, one cached-prefix invalidation
+   ([ADR-0068](../decisions/ADR-0068-scope-and-completion-report.md)).
+2. **Policy continuation on an unfinished reply (recommended next).** Widen `continueSlice`'s first
+   check from `terminalReason === 'slice_complete'` to also accept `completed` when the run's own
+   `todo_write` list holds an open item, no `checkpoint` is `blocked`, no question or approval is
+   pending, and the reply is not answer-only (no tool call in the run). Reuse everything else: the
+   `continueFrom` pin, `CONTINUE_TEXT` naming the open items, `maxSlices`, and the `progressed` test
+   so a fruitless slice does not loop. This is the stop-hook mechanism the table shows, expressed in
+   our own vocabulary instead of a new hook surface.
+3. **A cap and a person's escape.** Continue at most N times in a row (3, like Cursor's default of 5
+   but tighter), and never when the last reply asked the person something. Record the continuation as
+   its own run so the transcript shows the handoff; `runs.continuation` already reports it.
+4. **Do not adopt** a model-judged goal evaluator: it adds a second model call per reply and can only
+   judge what the transcript shows, which is exactly the information the doer already has.
+
+What to measure after 2: the share of `completed` runs with an open todo at the end (baseline 81 of
+207 `model_behaviour` runs), and the count of continuation runs per session (should be small — more
+than 3 in a row means the acceptance test is wrong, not that the model is lazy).
+
+## Evidence grade and gaps
+
+- The Xingular rows are first-party: file and line in this repository, today's checkouts.
+- External rows were read from live documentation on 2026-10-30 by a research pass with URLs cited;
+  they are **not** pinned to commits, so a later docs edit can invalidate a row. Where the wording is
+  quoted, it is verbatim from that page.
+- Not covered: Goose's completion tool, Cline's verbatim `attempt_completion` text, OpenCode step
+  limits, and the outer-loop literature (Ralph-style re-prompt loops, LangGraph recursion limits,
+  budget-forcing token loops). Treat any use of those as unverified.

package/docs/study/STUDY-0005-skill-installation-guidance.md

@@ -0,0 +1,146 @@
+# STUDY-0005 — Does this harness know how to install a skill, globally and per project?
+
+Status: **checked source and published docs**, no contract change. Extends
+[arms/04-skills.md](arms/04-skills.md), which covers skill format, loading and validation but not
+installation.
+
+## The question, in two parts
+
+"Install a skill" means two different things here, and they have different answers:
+
+1. **What the model in a session is told** about where skills live and how one gets installed.
+2. **What the product does** — which file locations and commands a person can use to put a skill in
+   a global scope or one project.
+
+The short answer: the product knows both scopes and they work. The session model is told neither.
+No prompt text, tool description or shipped skill names a skill location, a global-versus-project
+choice, or a way to install one. The model can only infer the folder convention from the absolute
+`location` of skills Pi already listed for it.
+
+## Part 1 — Everything a session model is told about skills
+
+| Text | File | What it says |
+|---|---|---|
+| Pi's skill list | `dist/core/skills.js` (`formatSkillsForPrompt`), installed at `/opt/homebrew/lib/node_modules/@xingular/harness/node_modules/@earendil-works/pi-coding-agent` | name, description, absolute `location` per skill, and "load a skill's file when the task matches its description" |
+| Harness tool guidance | [src/prompt/compile.ts:293](../../src/prompt/compile.ts) | "`skill_load` loads one of your skills by name." |
+| `skill_load` description | [src/tools/definitions.ts:131](../../src/tools/definitions.ts) | "Load the steps of one of your skills by name … Without a name, lists your skills." |
+| `plugin_propose` description | [src/tools/definitions.ts:141](../../src/tools/definitions.ts) | authoring only: "This does not install, enable, or trust it." Files are given as a map, `skills/<name>/SKILL.md` (validated in `plugins/proposals.ts`) |
+| Shipped `plugin-authoring` skill | [builtin/skills/plugin-authoring/SKILL.md](../../builtin/skills/plugin-authoring/SKILL.md) | step 3: "Put shared resources under the package's `skills`, `extensions`, `prompts` or `themes`" — packaging a plugin, not placing a skill in a scope |
+| Improver prompt (refinement only) | [src/refine/prompts.ts:141](../../src/refine/prompts.ts) | the exact c6 layout `skills/<name>/SKILL.md`, frontmatter rules, and that the name must appear in always-on text |
+
+So the only place a model is told the on-disk layout is the **improver** prompt — the model that
+edits the agent's own variant — and it describes the variant's folder, never `~/.agents/skills` or
+`<repo>/.agents/skills`. That rule came from harness², and its machine check lives in
+[src/variant/variant.ts:246](../../src/variant/variant.ts) ("a skill is never named in the always-on
+text"), whose hint text also reaches only the person or improver fixing a validation error.
+
+A session model that is asked "install this skill for the project" therefore has to rediscover the
+routes from the repository, which is what happened in the session that produced this study: about
+ten searches across `src/plugins`, `src/variant` and `docs/architecture` before the answer was
+secure. The `location` field in Pi's list is the only hint available in-band, and it carries the
+project case only (a variant skill's path is inside the state directory, so it teaches the wrong
+lesson).
+
+## Part 2 — What the product actually supports
+
+Verified with the harness's own resolver (`plugins/discover.ts`, the same call `Plugins.loading`
+makes before a terminal starts) against this repository, with the real home folder:
+
+| Scope | Path | Reaches a run as | Verified |
+|---|---|---|---|
+| Project (interop) | `<repo>/.agents/skills/<n>/SKILL.md` | plugin `skillPaths` → `--skill` for a terminal, `additionalSkillPaths` for a structured session | resolver reports `origin: 'project'`, `enabled: true` for `fix-strategy` and `terminal-testing` here |
+| Project (Pi native) | `<repo>/.pi/skills/<n>/SKILL.md` | same | Pi's own docs: `@earendil-works/pi-coding-agent/docs/skills.md`, `…/docs/settings.md#resources` |
+| Global, per OS user | `~/.agents/skills/<n>/SKILL.md` | same, as the "Home folder skills" plugin | resolver reports `origin: 'home'` for the 12 Cloudflare skills installed there |
+| Global, per harness state | `<state>/accounts/_shared/pi/skills` (linked into every account's `home/pi`) | Pi's user-level skills for an account | `ls ~/.xingular-harness/state/accounts/_shared/pi/skills` (exists, empty today) |
+| Variant (c6) | `skills/<n>/SKILL.md` in a versioned variant | Pi skill path, pinned per run | [docs/architecture/03-variants.md](../architecture/03-variants.md) |
+| Library → variant | `<data root>/registry/skills/<n>/SKILL.md` | `/components` commits a new variant version | [docs/terminal-tui.md](../terminal-tui.md) |
+| Package | `skills/<n>/SKILL.md` inside a plugin package | installed package, switched on per project/agent/global | [docs/architecture/06-plugins-and-capabilities.md](../architecture/06-plugins-and-capabilities.md) |
+
+Person-facing commands exist for every one of these (`/plugins`, `/components`, `/skills`, Hub
+install, local skill import through the resource browser). Model-facing commands exist for none of
+them, deliberately: installing grants no trust (`INV-PLG-3`) and a variant change is a version a
+person commits.
+
+## Part 3 — How peers handle it
+
+| Harness | Global | Project | Is the model told how to install? |
+|---|---|---|---|
+| **Codex CLI** | `$HOME/.agents/skills` (+ `/etc/codex/skills` admin) | `.agents/skills` from CWD up to repo root | **Yes, strongest.** Bundled `$skill-creator` and `$skill-installer <name>`; the docs frame those as the normal path |
+| **Gemini CLI** | `~/.gemini/skills` or `~/.agents/skills` | `.gemini/skills` or `.agents/skills` | **Yes.** Bundled `skill-creator` scaffolds into workspace scope; `gemini skills install <git-url> --scope user\|workspace` (defaults to `user`) |
+| **Claude Code** | `~/.claude/skills` (personal), enterprise dir | `.claude/skills`, nested, `--add-dir` | **Partly.** Bundled `/run-skill-generator` commits `.claude/skills/run-<name>/`, `/verify` writes `.claude/skills/verify/SKILL.md`; `skill-creator` is a marketplace plugin, not bundled. Personal outranks project |
+| **Kimi CLI** | `~/.kimi/skills` (+ `~/.agents/skills`) | `.kimi/skills`, `.agents/skills` | **Scope, yes; path, no.** System prompt groups skills `Project/User/Extra/Built-in` and states the override order; ships a `skill-creator` skill |
+| **Amp** | `~/.config/agents/skills`, `~/.agents/skills` | `.agents/skills` | **Yes.** Bundled `building-skills`; `amp skill add <source> --global` |
+| **Cursor** | `~/.cursor/skills`, `~/.agents/skills` | `.cursor/skills`, `.agents/skills` | **Yes.** Built-in `/create-skill`, `/migrate-to-skills` |
+| **Cline** | `~/.cline/skills` | `.cline/skills` | GUI only: "New skill…" creates the directory |
+| **OpenCode** | `~/.config/opencode/skills`, `~/.claude/skills`, `~/.agents/skills` | `.opencode/skills`, `.claude/skills`, `.agents/skills`, walk up to the git worktree | **No.** Model gets names and descriptions |
+| **omp** | `~/.omp/agent/skills`, foreign `.agents`/`.claude` roots | `.omp/skills` | **No.** Prompt is usage-only (`skill://<name>`); `omp skill install` exists for people |
+| **deepseek-harness** | `<dshHome>/skills` | `<root>/.dsh/skills`, `.agents/skills` | **No.** Catalog plus a load tool |
+| **OpenHands SDK** | `~/.openhands/skills` | `.agents/skills` | Programmatic: `install_skill`, marketplace API |
+| **harness²** | — | `skills/<name>/SKILL.md` in the editable harness | **For the improver, yes.** Its prompt names the surface paths and the trigger-line rule |
+| **this harness** | `~/.agents/skills`, `_shared/pi/skills` | `.agents/skills`, `.pi/skills` | **No**, except the improver's variant layout |
+
+Two observations worth keeping:
+
+- The [Agent Skills specification](https://agentskills.io/specification) defines the directory and
+  frontmatter, not locations. Global-versus-project is vendor invention in every harness, and the
+  collision rules disagree (Claude Code: personal beats project; Gemini: workspace beats user;
+  Cline: global beats project; Codex: no resolution at all). There is no canonical rule to copy.
+- Every peer that tells the model how installs work does it with a **bundled skill or command**,
+  not always-on prompt prose. Codex, Gemini, Cursor, Amp and Kimi all ship one; none spends stable
+  prefix tokens on it.
+
+Sources fetched for this study: [Claude Code skills](https://code.claude.com/docs/en/skills),
+[Gemini CLI skills](https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/skills.md),
+[Codex build skills](https://learn.chatgpt.com/docs/build-skills),
+[Agent Skills spec](https://agentskills.io/specification). Peers marked only in the table rows for
+Amp, Cursor and Cline come from [ampcode.com/docs/customize/skills](https://ampcode.com/docs/customize/skills),
+[cursor.com/docs/skills](https://cursor.com/docs/skills) and
+[docs.cline.bot/customization/skills](https://docs.cline.bot/customization/skills) via the research
+pass recorded in this session, and were not re-fetched. Clone-based claims cite
+`external/<name>/<path>` as usual: `external/kimi-cli/src/kimi_cli/agents/default/system.md:140`,
+`external/kimi-cli/src/kimi_cli/skills/skill-creator/SKILL.md:1`,
+`external/opencode/packages/web/src/content/docs/skills.mdx:16`,
+`external/omp/docs/skills.md:92`, `external/harness2/harness2/core/prompts.py:141`.
+
+## Findings
+
+- **F1.** Both scopes exist and work; the gap is in the model's instructions, not the mechanism.
+- **F2.** A session model is told how to *use* skills and how to *propose a plugin*, never where a
+  skill is installed. The improver is the only model told a layout, and only for c6.
+- **F3.** The fix cannot be an install tool. Installing grants no trust (`INV-PLG-3`), variant
+  changes are committed versions, and Hub installs carry provenance receipts — all person acts.
+  Only the text-file routes are safe for a model to write, and it is not told what they are.
+- **F4.** The cheapest known shape is a bundled skill or command; the peers' evidence argues
+  against putting location rules in the always-on prompt.
+
+## Candidate changes, not implemented
+
+| # | Change | Lands in | Cost |
+|---|---|---|---|
+| S1 | Give the shipped `plugin-authoring` skill a short "where a skill is installed" section: the three text routes (project `.agents/skills`, home `~/.agents/skills`, state-shared `_shared/pi/skills`) and that variant, library and package installs are person-committed | [builtin/skills/plugin-authoring/SKILL.md](../../builtin/skills/plugin-authoring/SKILL.md), plus the one contract sentence in [page 06](../architecture/06-plugins-and-capabilities.md) | no prompt tokens, no cache-prefix risk; the skill loads on demand |
+| S2 | Add the same routes to a project's `AGENTS.md` where a repository wants its agents to install skills itself | this repo's guide, other repos' | zero runtime cost, helps only the repos that carry it |
+| S3 | One added sentence in the tool-guidance section ("A skill is a folder … install to …") | [src/prompt/compile.ts](../../src/prompt/compile.ts) | stable-prefix change; measure with the App's cache probe before adopting |
+
+## Implementation
+
+S1 shipped: [builtin/skills/plugin-authoring/SKILL.md](../../builtin/skills/plugin-authoring/SKILL.md)
+now has an "Installing an existing skill or plugin" section with the text routes, the whole-folder
+rule, the URL workflow and the person-committed paths, and its description names installing. Two
+install-correctness fixes shipped with it:
+
+- `normalizeSource` refuses a GitHub or GitLab `tree`/`blob` page address and names the repository
+  address and the skill routes, instead of passing the page to Pi's `git clone`.
+- A package's foreign plugin manifest (`plugin.json`, `.claude-plugin/plugin.json`,
+  `.codex-plugin/plugin.json`) may declare `skills`; those folders load as package skill
+  contributions, under the package's own switch and settings filter.
+
+S3 was not taken: no always-on prompt line, so the stable prefix and its cache are unchanged.
+Tests: `src/plugins/manifestSkills.test.ts`, `src/plugins/install.test.ts`,
+`src/tools/defaultSkills.test.ts`. The contract text is in
+[page 06](../architecture/06-plugins-and-capabilities.md).
+
+## Drift noticed while reading
+
+[arms/04-skills.md](arms/04-skills.md) still describes `src/tree/` (`tree.ts`, `src/tree/trust.ts`)
+and the word "tree"; those modules are `src/variant/` now. Study text, not contract, so it is left
+as written for a separate pass.