@xingular/harness 0.1.6 → 1.0.0

package/docs/study/arms/05-context-management.md

@@ -0,0 +1,90 @@
+# Arm 05 — Context management
+
+Status: **core three audited** (opencode, omp, dsh); smolagents skeleton;
+ours=pending inventory beyond contracts; claude-code/openhands pending.
+
+## Design space
+
+What is sent per turn vs fetched on demand; compaction triggers and strategies;
+where summarization sits relative to the cache; truncation of tool outputs;
+token accounting granularity (uncached input / cache read+write separation).
+
+## Comparison
+
+**this harness (contracts).** Stable system prefix + hidden `xingular-context`
+native-history message for changing state; usage accounting: `inputTokens` is
+uncached input, cache reads/writes separate, reasoning inside output,
+`usage.updated` cumulative per run (repo contracts). Compaction story pending
+inventory (whether sessions rely on Pi native history management + context
+updates).
+
+**opencode — summarizer as a resident agent.** Triggers: `auto` when estimated
+context ≥ ceiling (window − max(15%, 16k) reserve), `overflow` after provider
+rejection, `manual` (`.../session/compaction.ts:53-57,93-101,849-856`); auto
+skips until a fresh provider measurement exists (`:245-253`).
+Strategy: a dedicated compaction agent/model summarizes every dialog into a
+**fixed template** (Objective / Requirements / Decision / Work State / Next
+Move / Relevant Files) while keeping the newest `keep` tokens verbatim as a
+`<conversation-checkpoint>`; **the whole conversation is sent to the
+summarizer to reuse the prefix cache** (`:107-138,256-332`). Rejection retries
+at 70/50/35% of the rejected size (`:455-461`). Generic ToolOutput truncation to
+maxLines/maxBytes with `metadata.truncated`
+(`.../core/src/tool-output.ts:28-88`); shell saves full output to a file and
+returns a bounded tail (`.../tool/plugin/shell.ts:42-43`).
+Accounting: latest assistant response is the anchor
+(`input+cacheRead+cacheWrite+output+reasoning` measured) plus an estimate of
+unmeasured since (`:812-842`); 4 chars/token estimate ±15%
+(`.../session/model-request.ts:53-54`).
+
+**omp — the strategy ladder + deterministic frontier.** Trigger points: post-turn
+over `resolveThresholdTokens`, mid-turn, idle, overflow-recovery
+(`.../session/session-maintenance.ts:626,2147,2246,2412`).
+`compaction.methodOrder` ladder: LLM summarize (regular/handoff), `shake`
+(local mechanical elision to `artifact://` refs), `snapcompact`
+(`docs/compaction.md:202-215`). **Snapcompact is local/deterministic, no LLM**:
+discarded history serialized with per-result caps into provider-aware PNG
+bitmap frames (typography per provider family), persisted and re-attached each
+rebuild (`packages/snapcompact/README.md:3-29,44-68`). Budgets: kept context
+≤60% of threshold, target ≤80% (`docs/compaction.md:217,221`). Cache care:
+pruning blanks outputs only within the model's `prompt-cache-lookback`
+(`docs/compaction.md:248`); summaries drop whole call/result pairs (`:250`).
+Byte-stable system prompt between turns is an invariant
+(`.../session/agent-session.ts:2607`).
+
+**dsh — formulas + query-ability.** `compaction-basic` trigger:
+`floor(min(W×0.8, W−O−headroom))`, headroom 65_536, keeps newest 16% of the
+usable window, one extra model request, summary-only retention
+(`.../packages/compaction/compaction-basic/README.md:12,32,62-68`).
+Oversized tool results pruned first; images offloaded to placeholders
+(`.../packages/compaction/README.md:31-32`). `session-query` = SQLite FTS5
+full-text search over the durable log, independent of compaction
+(`.../packages/session-query/README.md:12,30`).
+
+**smolagents.** `AgentMemory` is a step log (ToolCall/ActionStep/PlanningStep/
+FinalAnswer) rebuilt to messages with `summary_mode` each step — replay-style,
+no incremental fades (`external/smolagents/src/smolagents/memory.py:25,46,92,206-229`).
+
+## Trade-offs
+
+- **Summarizer economics.** opencode sends the *whole transcript* to the
+  summarizer to reuse the prefix cache — larger paid input per compression, but
+  cache-discounted and higher-fidelity. dsh keeps only the summary (cheapest
+  retention). The choice hinges on whether compaction runs once or repeatedly.
+- **A deterministic rung is the safety net.** omp's ladder means a compaction
+  never fully depends on a slow/failing LLM pass (shake/snapcompact). That
+  resilience has no counterpart in opencode/dsh (dsh retries on overflow).
+- **Searching beats re-shipping.** dsh's session-query (and omp's shard
+  omp's shard-style retrieval in `shake`) treat old context as a database, not a
+  transcript; "retrieve details through tools when needed" matches our
+  CONTEXT_GUIDANCE wording (`src/prompt/compile.ts:333`).
+- **Accounting honesty.** opencode's anchor-measured + estimated-elsewhere and
+  our uncached/cached split are compatible; the 4-chars/token estimate is the
+  common fixed-density fallback (dsh token-meter identical semantics).
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| C1 | A fixed-template summary shape (named sections) for any summarization run, so restored context is predictable and diffable | opencode compaction template | refine/trajectory or session docs; needs Pi-native compaction knowledge first | T2 verify-first |
+| C2 | Prune-first ordering (oversized tool outputs) before any summarization | dsh + omp | facet of the context update path | T2 verify-first (what already trims?) |
+| C3 | Keep a verbatim tail checkpoint marker in any summary | opencode | same home as C1 | T2 |

package/docs/study/arms/06-memory.md

@@ -0,0 +1,90 @@
+# Arm 06 — Memory
+
+Status: **core four audited** (omp, dsh, opencode, harness²) + our Wiki;
+claude-code/openhands pending.
+
+## Design space
+
+What counts as memory (instruction files, durable notes, episodic stores,
+learned harnesses), who writes and when (model via tools, background
+consolidation, per-write hooks), what shapes entries and their limits, and how
+recall is gated (never ship rubrics or other answer-leaking data).
+
+## Comparison
+
+**this harness.** Wiki notes: `noteChange` fires once the file is in place, in
+the background; a hook's failure never reaches the write; every new write point
+calls it too (repo contract). Injection sections are bounded (`WIKI_BUDGET`,
+`NOTES_LISTED` in `src/prompt/compile.ts:167` etc.), listing notes + revision,
+with more available via `wiki-list`/`wiki-search` tools. The refine experience
+library is a separate, answer-free lane (arm 10) — never ships rubrics
+(`refine/evidence.ts` guard).
+
+**omp — the memory machine.** Five `memory.backend` modes: off | local |
+hindsight | mnemopi | sharpshooter (`docs/memory.md:3-11`). A startup
+background job runs two phases (per-session extraction → global consolidation
+with lease+heartbeat, skipped for subagents), producing per-project `MEMORY.md`
+(+ summary) and lessons and **skills/** on disk
+(`.../memories/index.ts:29-67`; `docs/memory.md:22-26,74-89`). Injection =
+Memory Guidance block at session start sharing a 5000-token budget with
+lessons (`docs/memory.md:132`); `learn` lessons capped 100 entries × 2000
+chars, redacted (`docs/memory.md:70`). `mnemopi` = local SQLite
+working/episodic engine with embeddings and a `memory://` read protocol plus
+model-facing tools `recall|retain|reflect|memory_edit`
+(`packages/mnemopi/README.md:5-8`; `docs/memory.md:34-46`). `hindsight` =
+remote vector service; recall on first user turn, auto-retain every N turns
+(`.../hindsight/state.ts:385-388`). Writes happen minutes/days later — nothing
+is "auto right after task".
+
+**dsh — durability without a memory package.** No memory package by design:
+the durable session log (immutable JSONL + checkpoint policy,
+`.../packages/session/README.md:38-39`), todos persisting across sessions
+(owned by the session; whole-list replace, `.../packages/todo/README.md:12`),
+`spill` storing oversized text out of context with locator+guidance
+(`.../packages/spill/README.md:12,30-31`), `storage` for app data that is
+**never model-visible** (`.../packages/storage/README.md:12,27-30`),
+`deliverables` recording outputs as client-only events
+(`.../packages/deliverables/README.md:12,27-28`). Cross-session memory:
+deliberately absent.
+
+**opencode.** No cross-session memory product: per-session todos (feature-gated
+`experimental.todo`), skills/config as durable files, snapshot revert/restore
+(`.../tool/plugin/todo.ts:50-75`; `.../session/revert.ts:37-42`). Memory is a
+community-plugin story.
+
+**harness².** Memory belongs to refinement: the per-domain experience library
+carries full adopted trees + `EXPERIENCE.md` (why + lesson) per task, scoped
+per run and domain, starting empty
+(`external/harness2/harness2/core/library.py:15-23`). At proposal time the
+library is *read* (`INDEX.md` browse, `prompts.py:320-328`), workspace facts
+are re-verified before reuse — memory is a drift-checked `[cue→lesson]`, not a
+freeform store. The editable tree also holds `LongTermMEMORY.md` as c3 durable
+facts, "ALWAYS ON" with the output-budget price tag (`.../prompts.py:104,426`).
+
+**claude-code (pending).** CLAUDE.local.md, `#` quick-notes, user memory file
+(publishable specs; citations pending).
+
+## Trade-offs
+
+- **Where memory lives.** The file the model reads (`MEMORY.md`, our Wiki) is
+  the visible tier; the episodic store (mnemopi) is the cheap tier for
+  per-project recall. omp is the only source with both, and it pays for it with
+  background jobs and lease/heartbeat machinery.
+- **Learning to write.** harness²'s lessons have a *scope contract*
+  (generic/procedural, but never task facts; "too generic changes nothing, task
+  facts are wrong anchors") — enforced by prompt discipline and by the `cue`
+  shape in ours (`src/refine/prompts.ts:425`). Any Wiki lesson should carry the
+  same contract (pattern vs fact).
+- **Caps and redaction.** omp's budget regime (100×2000 lessons, injection caps)
+  caps) mirrors our WIKI_BUDGET approach; worth remembering that redaction is
+  part of the cap story, not just size.
+- **Nothing is model-visible that shouldn't be** (dsh `storage`): keep the
+  separation of run records (ours).validate Never model-visible: run events
+  used for the Wiki must already be validated kinds (family rule).
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| M1 | Apply harness²'s lesson-shape contract to any Wiki note that summarizes behavior (cue = shape of situation, lesson = checkable operation, NO_ENTRY when unsupported) | harness² + omp caps | Wiki note template/validation (plugin) | landed: `src/history/lessons.ts` (PROP-0008) |
+| M2 | Evaluate a `memory://`-style read protocol (note retrieval as URI) — compare cost against plain wiki tools before adopting | omp mnemopi | none (note only) | T3 |

package/docs/study/arms/07-governance.md

@@ -0,0 +1,71 @@
+# Arm 07 — Governance
+
+Status: **core three audited** (opencode, omp, dsh) + swe-agent blocklists,
+smolagents executor posture; claude-code/openhands pending.
+
+## Design space
+
+Who may call what, expressed how (per-call gate, tier×policy, event pipeline,
+modes), approval UX (`ask` as outcome), fallback behavior (fail-closed or not),
+trust for loaded code, secret/account isolation.
+
+## Comparison
+
+**this harness (contracts).** Per-call gate as the final extension; standing
+approvals; single-use operation approvals in the app scope; account pinning
+and redaction; tree plugins load only when their exact code is trusted
+(`src/tree/trust.ts`).
+
+**opencode — effect assertions with a wildcard ladder.** Rules: `allow|deny|ask`
+literals, `findLast` wildcard resource match, default ask; agent rules and
+session-level rules merge; a missing agent rule means deny-all
+(`.../core/src/permission.ts:87-97,158-172`); user-saved "always allow"
+(`:148-155`); catalog filtering only for wildcard-deny leaves
+(`.../tool.ts:233,293-296`). Plugins may reject calls via `execute.before`
+(`.../packages/plugin/src/effect/tool.ts:20-52`) — handy, but note the gate
+stays the execution boundary's last authority only if core retains its own
+assert.
+
+**omp — declared tiers and modes.** `ToolTier = read|write|exec` per tool
+(exec default when unclaimed), per-tool policy `allow|deny|prompt`, modes
+`always-ask | write | yolo`; **missing context fails closed to always-ask**
+(`.../tools/approval.ts:17-18,53-84,100,1226-1230`). Extension hooks wrap every
+call (`extensibility/hooks/tool-wrapper.ts`).
+
+**dsh — pipeline events, not a package.** Gate inside dsh-tools:
+`tools/pre-execute` (allow/deny/ask) → monotonic guard() reasons → execute →
+post-execute → result (observe-only)
+(`.../packages/core/tools/README.md:89,109`; ask at `.../index.ts:608-612`).
+Bundle base ships a default policy confining file writes and asking before
+risky actions (`.../bundle/base/README.md:50`). OS sandbox separately:
+file-effect policy classes with Landlock/Seatbelt/Windows backends and one-time
+approved escalation (`.../packages/sandbox/README.md:12,30`).
+
+**swe-agent.** Governance = curation: blocklist files in bundles
+(`external/swe-agent/tools` listing); the environment's own command filter
+(pending detail).
+
+**smolagents.** Almost none in-source; the free executor (interception-based
+local or paid remote) carries the risk — the anti-reference for our no-code-actions stance.
+
+**claude-code (pending).** Permission modes + allow/deny rules + hooks.
+
+## Trade-offs
+
+- **Declarative vs hook-composed.** A user wanting "always allow reads, ask on
+  writes" gets legibility from omp's tables; a plugin author gets power from
+  opencode's before-hooks. Our per-call gate can host both: tiers inform, hooks
+  advise, gate decides.
+- **Fail-closed culture.** omp fails closed on missing policy; opencode defaults
+  ask; dsh asks by bundle default. Convergent good posture — record as a
+  shared norm, and keep our own default equally closed.
+- **Escalations are one-time, auditable.** dsh's one-time approved sandbox
+  escalation and our single-use approvals express the same idea; forcing a
+  person to re-re-approve persistent bypasses is the safer curve.
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| G1 | Tier-per-tool declarations inform standing-approval wording (reads bulk-allowed, writes asked) | omp | ToolPolicy documents + default policy | T1 |
+| G2 | Codify "policy missing ⇒ ask" as an invariant test | omp fail-closed | src tests around the gate | T1 |

package/docs/study/arms/08-execution.md

@@ -0,0 +1,69 @@
+# Arm 08 — Execution
+
+Status: **core three audited** (opencode, omp, dsh) + swe-agent environments,
+smolagents executors; hands pending.
+
+## Design space
+
+Where a step's process runs (own process, PTY owner, container), sandbox
+mechanics per OS, output shapes (streaming, truncation, side-files), and who
+owns the terminal surface.
+
+## Comparison
+
+**this harness (contracts).** Host owns PTY and supervision; the harness owns
+the terminal launch spec; a session runs in its account's own Pi agent folder,
+never `~/.pi` (isolation by account).
+
+**opencode.** The `shell` tool runs via the core Shell service returning
+bounded tail output with full output saved to a file
+(`.../tool/plugin/shell.ts:17-23,42-43`). `persistent-pty` is a separate
+per-server daemon for owned PTYs rooted at `<state>/pty` — for interactive
+frontends, distinct from the tool path
+(`.../core/src/persistent-pty/index.ts:6-23,129` — tool-vs-PTY overlap
+unverified).
+
+**omp.** The strongest in-process Unix environment: bash runs inside a Rust
+`pi-shell` host **with vendored uutils coretools (pi-builtins)** — real
+utilities, one process (`crates/pi-shell/Cargo.toml:18`,
+`crates/pi-builtins/src/`). Always non-interactive env (pagers off,
+TERM=dumb, credential prompts fail via `false`)
+(`.../exec/non-interactive-env.ts:6-25`). No OS-level sandbox located
+(unverified absence).
+
+**dsh.** Layered: OS sandbox classes (read-only / workspace-write /
+danger-full-access on Landlock/Seatbelt/Windows tokens, one-time approved
+escalation), exactly one shell executor per composition exposing `bash`/`pwsh`
+tools, and a single `ctx.subprocess` service with bounded output and scrubbed
+env (`.../sandbox/README.md:12,30`; `.../shell/README.md:12,38`;
+`.../subprocess/README.md:12,27`).
+
+**swe-agent.** Containerized bash environments per run with tool bundles
+bound to the interface (`sweagent/environment/`); benchmark single-shot
+workspaces.
+
+**smolagents.** Local executor intercepts/denies dangerous calls in-process;
+remote (E2B etc.) otherwise (`local_python_executor.py`, `remote_executors.py`).
+
+## Trade-offs
+
+- **In-process Unix vs OS sandbox.** omp buys speed/fidelity with a Rust-hosted
+  environment; dsh buys verifiable confinement with OS primitives. This harness
+  runs on a host's PTY, so the OS-sandbox direction (dsh) is the compatible
+  one; "in-process coretools" is an execution detail of pi, not adoptable
+  machinery here without duplicating rust-supported layers.
+- **Two command paths is the norm.** opencode (tool shell vs owned PTY) and dsh
+  (shell executor vs subprocess service) both split "model calls" from
+  "platform plumbing" — our launch-spec/PTY split matches; the invariant to
+  keep: environments are per-account, launched by spec, never shared across
+  accounts.
+- **Output hygiene** (bounded tails + side files, scrubbed env, non-interactive
+  defaults) is universal; treat as a checklist for any new tool rather than a
+  design to adopt.
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| E1 | Sandboxing classes as a ToolPolicy option (read-only/workspace-write) for *host* integrations — offered, never default | dsh | ToolPolicy scope option | T2 (needs app-level sandbox plumbing) |
+| E2 | "One subprocess service" norm: all child spawns montage through one owned helper with bounded output + env scrub | dsh subprocess | App-sidecar ownership unchanged; only normative doc | T1 as ADR text |

package/docs/study/arms/09-observability.md

@@ -0,0 +1,60 @@
+# Arm 09 — Observability
+
+Status: **core three audited** (opencode, omp, dsh) + swe-agent trajectories;
+hands pending.
+
+## Design space
+
+What is recorded (events, trajectories, usage), validation of records, who may
+write run records, live relay to interfaces, retention/redaction, and cost
+accounting granularity.
+
+## Comparison
+
+**this harness (contracts).** Validated run events saved per run by the only
+writer (`sessions/runStore.ts`); `usage.updated` cumulative per run with the
+uncached-input / cache-read / cache-write split; app relays to UI.
+
+**opencode.** "event-logger.ts listens on the event bus and logs only
+allow-listed config-type events (agent/provider/model/command/config updated),
+as a global node" (`.../core/src/event-logger.ts:10-19`). Usage published as
+`SessionEvent.UsageRecorded` from the compaction anchor
+(`.../session/compaction.ts:632-639`); trajectory surface lives in session-ui
+and the TUI (packages listing).
+
+**omp.** `omp stats` — local web dashboard with live ingest (port 3847)
+covering AI usage, with per-session ledgers available
+(`packages/stats/README.md:3,9,31-35`); `wire` package supplies transport;
+judgment roles record usage too (`.../judgment/index.ts:6-10`).
+
+**dsh.** Telemetry is an OTel transport only — "business consumers own events,
+identities, redaction"; feedback-authorized upload, default `FEEDBACK_ONLY`
+(`.../packages/telemetry/README.md:12,25`; `.../bundle/base/README.md:50`).
+Business events flow through the session event stream.
+
+**swe-agent.** trajectory JSON per run + a separate inspector to browse them
+(`external/swe-agent/trajectories`, `sweagent/inspector/`).
+
+**smolagents.** `monitoring.py` metrics + `AgentLogger` markdown logs; gradio UI.
+
+## Trade-offs
+
+- **Where transport ends.** The dsh rule — a transport package knows nothing
+  about business events — is the cleanest boundary. Our runStore already
+  *is* the business schema; be careful that nothing in run records assumes an
+  application consumer (they don't: read-only records).
+- **Local dashboards vs relay.** omp's stats serves a self-hosted view; ours
+  hands validated events to a UI. Same functionality, different home; nothing
+  to adopt; the one check if we ever add an export path: no
+  duplicate charges on relaunch (event ids dedupe).
+- **Cost accounting alignment.** Everyone anchors usage at the latest provider
+  response and estimates lagging items (opencode anchor pattern at
+  `compaction.ts:812-842`). Ours does the same via usage.updated — align
+  definitions (reasoning inside output) with any upstream comparisons to
+  prevent double-cost surface.
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| O1 | A "transport owns nothing about identities" doc commitment when any telemetry-like export exists (apps may add; harness stays identity-blind) | dsh telemetry | a para note in repo README | T1 doc |

package/docs/study/arms/10-refinement.md

@@ -0,0 +1,110 @@
+# Arm 10 — Refinement / self-improvement
+
+Status: **audited (self + upstream, in person)** — this arm's headline finding changes
+the shape of the study, see §1.
+
+## Design space
+
+Who is improved (prompt files, tools, tree files), how candidates are made
+(dimension-split editors?), how they are probed (isolated, unattended; approvals
+refused), how selection stays answer-free, how experience accumulates across
+tasks, and what no step may do (act in the world with a person's assets).
+
+## 1. Headline finding: this harness already ports harness²
+
+Every module of `src/refine/` is an explicit port of harness²'s core, by its own
+header comments:
+
+| this harness | upstream |
+|---|---|
+| `src/refine/recursion.ts:5` | `harness2/core/recursion.py` |
+| `src/refine/selection.ts:5` | `harness2/core/selection.py` |
+| `src/refine/prompts.ts:5` | `harness2/core/prompts.py` (the **adapt** pack only — `prompts.ts:1`) |
+| `src/refine/ledger.ts:5` | `harness2/core/ledger.py` |
+| `src/refine/library.ts:9` | `harness2/core/library.py` |
+| `src/refine/evidence.ts:13` | `harness2/core/context.py` |
+| `src/refine/runner.ts:6` | `harness2/core/schedule.py::run_task` (shaped after) |
+
+Identities preserved: R = 4k rollouts / P = 3k sessions per mode
+(`src/refine/ledger.ts:7-11`), matching upstream `recursion.py:15-19`; Stage
+shape (`Stage {label, dim, tree, keptBase, fellBack…}` `src/refine/recursion.ts:26-37`)
+with one-retry-then-inherit upstream `recursion.py` docstring; sequential-round
+checkpoint anchoring incl. the "KEEP_BASE means the CURRENT checkpoint" rule
+(`src/refine/prompts.ts:316` vs upstream `prompts.py:852-857`); the answer-free
+selector (`src/refine/prompts.ts:399` mirrors `prompts.py:791-793`); KEEP_BASE
+doctrine (`src/refine/prompts.ts:232` mirrors `prompts.py:333-335`).
+
+The merge the study was asked to plan is therefore **already largely executed**.
+What remains is a mature-upstream delta analysis, below.
+
+## 2. Comparison with harness² as it now stands
+
+Converged (ported): parallel/sequential recursion, INV/DOM candidate split with
+independent same-evidence samplers, aggregator/composer with MERGE / ADOPT-ONE /
+KEEP_BASE, anonymized answer-free selection, per-domain experience library
+carrying the **full adopted tree plus an EXPERIENCE.ms-style why/lesson** (ours:
+`src/refine/library.ts`; theirs: `external/harness2/harness2/core/library.py:15-23`,
+"the whole tree is carried, never a summary"), reflection writing cue/lesson rows
+(`src/refine/prompts.ts:418-425` mirrors their `_EXP`-driven reflector).
+
+Deltas (upstream beyond our port):
+
+1. **Second, hardened prompt pack ("tts").** Upstream ships two packs per stage
+   (`_tts_propose` / `_tts_aggregate` / `_tts_select` vs the base pack,
+   `external/harness2/harness2/core/prompts.py:838-839,896-897`); ours carries
+   only the adapt pack (`src/refine/prompts.ts:1`). The tts pack adds: an
+   explicit **`<notes>` decision audit format** (`kept|revised|dropped -> edit ->
+   evidence`, `.../prompts.py:765-769`), a `yardstick` slot ("WHAT GOOD PROCESS
+   LOOKS LIKE HERE", `.../prompts.py:705-706,757-761`), sharper always-on
+   economics and on-demand-first framing, and pool-anonymity emphases
+   (`PICKING AN UNMODIFIED HARNESS IS VALID`, `.../prompts.py:66-74`).
+2. **Screenshot-era surface dialects.** Upstream maintains this c1–c8 tree for
+   two substrates (opencode and codex) with per-substrate hook/plugin mechanics
+   (`.../prompts.py:617-661`, `tree.py:41-60 SurfaceSpec`) — ours compiles one
+   Pi surface (`src/refine/recursion.ts` imports `PI_SURFACE`).
+3. **A decoupled judge.** `harness2/core/judge.py:15-19`: measurement of the
+   chosen run happens *after selection*, **"Nothing in the method imports this
+   module"**; a judge failure is None, excluded from denominators
+   (`.../judge.py:37-40`). **Not ported** — `src/refine/` has no judge module.
+   This is the one structural piece of upstream we do not have.
+4. **Substrate contract vs our RefineHost.** Their substrate wrap is a
+   file-level (`context/harness/` editable tree + workspace dirs); ours isolates
+   through `RefineHost` (workspace, probe session, deliverable) with probe runs
+   as unattended sessions whose approvals are refused (repo contract). Same
+   shape, different isolation vocabulary — ours is the stronger primitive, but
+   note upstream's `keep_base` inherits untouched files with no re-read
+   (`.../prompts.py:186-189`); ours should verify the same semantic survived the
+   port (pending test-level confirmation).
+
+## 3. Trade-offs
+
+- **Judge in or out.** Keeping measurement out of the harness (our family rule:
+  measurement belongs to Evaluation) preserves layering but forfeits private
+  experience labeling — the `<experience>` reflection then rests only on
+  trajectory contrast, which ours already guards ("A lesson resting only on
+  `confounded` rows is a guess", `src/refine/prompts.ts:425`). Upstream's
+  compromise: a judge that labels the *chosen* run only, never feeds forward, and
+  is excluded from denominators on failure — it cannot leak into selection
+  because selection already happened.
+- **Prompt packs.** Two packs cost maintenance but let upstream evolve hardening
+  without destabilizing the published method. Ours froze one pack at port time;
+  upstream drift since then is invisible to our selectors.
+- **One surface vs many.** Ours targets Pi only; upstream's SurfaceSpec proves
+  the same method bends to codex/opencode cheaply — a bridge test for whether
+  our `RefineHost` boundary is truly substrate-agnostic.
+
+## 4. Adoption candidates
+
+| # | Idea | From | Tier | Land as |
+|---|---|---|---|---|
+| R1 | Diff the ported prompts against upstream's `adapt` lines and pull changed sentences (e.g. pool-anonymity emphasis, deliverable-shape rule) into `src/refine/prompts.ts` | harness² drift since the port | T1 | in-place prompt text sync (tests measure wording-insensitive behavior) |
+| R2 | Add the `<notes>` audit format to compose/selected stages so adoption decisions carry their evidence | tts pack | T1 | our prompts' notes sections |
+| R3 | Consider the yardstick slot as an optional, app-supplied `BenchPrompts` field — *only if* an app needs a domain yardstick; it must remain prose, never a score | tts pack via `Spec` | T2 | `RefineHost` launch input, thinking hard before adding |
+| R4 | A post-selection judge module, ported with upstream's exact decoupling (not imported by the method; None on failure excluded from denominators) **or** explicitly glued to Evaluation | judge.py | T2 with a layering decision first — see trade-off above | new `src/refine/judge.ts` behind `RefineHost`, or nothing |
+| R5 | Re-run upstream-vs-ours substrate parity test: can our tree/validation accept an upstream-authored candidate tree without edits? (`isAllowed`, caps, autotrigger semantics) | both | T1 verification task, no code change | a test |
+
+Anti-candidates, recorded so nobody re-proposes them: do **not** move measurement
+or grading into `src/refine/` (family boundary: Evaluation owns measurement);
+do **not** let any judge label reach improver or selector (answer-free is
+invariant); do **not** carry per-task facts into the durable library without the
+cue/lesson narrowing ours already enforces.

package/docs/study/btw-comparison.md

@@ -0,0 +1,37 @@
+# `/btw` side-question comparison
+
+Status: source-reviewed comparison of the checked-out workspace snapshots; no live model or UI runs were performed. This is a study note, not a change to the Harness contract.
+
+## Scope and conclusion
+
+This compares the terminal implementation in this repository, Xingular Agent's app-owned chat feature, and the external projects with an actual `/btw` implementation in the checked-out `external/` sources. The external set is Oh My Pi (`omp`), Kimi CLI, OpenCode, and OpenHands. OpenHands' SDK is its backend, not a separate UI implementation.
+
+The similarly named features are not one shared implementation. **Xingular Harness terminal creates a separate, in-memory Pi session with a bounded transcript excerpt and hard tool suppression. Oh My Pi's native `/btw` uses the main session's ephemeral side-turn pipeline, with much more context and persistent BTW history.** Xingular Agent's `/btw` is instead owned by the App: it starts a tracked, tool-free side run using a deliberately bounded public snapshot.
+
+## Comparison
+
+| Implementation | Context supplied | Isolation and persistence | Interaction |
+|---|---|---|---|
+| **Xingular Harness terminal** | Up to six visible user/assistant turns; each is clipped to 1,200 characters and the excerpt to 6,000. Includes tool names and a running flag, not tool inputs/results. | Creates an in-memory Pi session using the active model, with tools, extensions, skills, prompt templates, themes, and context files disabled; thinking is off. The side exchange is not added to the main transcript or a Harness run record. | One dock at a time. A new question replaces the old one; an empty `/btw` or Escape dismisses it and aborts the side session. The displayed answer is limited to eight lines. (`src/terminal/tui/sideQuestion.ts:13-21,39-53,69-85,106-165`; wiring: `src/terminal/opentui/app.ts:376-399`.) |
+| **Xingular Agent (App-owned)** | Up to eight visible conversation messages plus a bounded public-progress snapshot: current request, visible partial answer, status, and up to six public tool-activity summaries. Excludes hidden reasoning, tool arguments/results, and attachments. | Separate tool-free run using the conversation's account/model/effort and an opaque one-use session identity. It does not control or enter the main transcript; it has an ordinary run record/events for Trajectory and Usage. | One temporary dock per one-to-one Agent/Solo conversation. Stop and Dismiss affect only the side run; a new question replaces it. Groups and attachments are unsupported. (`../App/docs/features/FEAT-0014-side-questions.md:25-43`; snapshot and run launch: `../App/src-tauri/src/agents.rs:2748-2881`; dock lifecycle: `../App/src/modes/chat/useSideQuestion.ts:15-110`.) |
+| **Oh My Pi (`external/omp`)** | Uses the main system prompt and session history, and includes the in-progress assistant text. The snapshot preserves thinking blocks too. Its main tool catalog is supplied for the request, but the side turn does not execute tool calls. | Ephemeral side turn does not mutate the main session history. BTW questions and answers are checkpointed in a separate on-disk history sidecar; topics support follow-ups. | TUI history panel, cancellation, copy, optional promotion of a single answer to a branch, and RPC commands/stream events. (`external/omp/packages/coding-agent/src/session/agent-session.ts:11363-11550,11555-11600`; turn/follow-up context: `external/omp/packages/coding-agent/src/session/btw-turn.ts:13-93`; sidecar: `external/omp/packages/coding-agent/src/session/btw-history.ts:80-146`; controller: `external/omp/packages/coding-agent/src/modes/controllers/btw-controller.ts:121-190,356-448`; RPC: `external/omp/packages/coding-agent/src/modes/rpc/rpc-btw.ts:1-18`.) |
+| **Kimi CLI** | Uses the same system prompt, normalized conversation history, and tool definitions as the main agent, explicitly to align the prompt cache. It does not explicitly add the current partial stream to that history. | Tool definitions are visible, but a deny-all toolset rejects calls. If the model tries a tool, it gets one retry (two model steps maximum). The side exchange is not written into main conversation history. | Streams into a scrollable modal; Escape dismisses. Interactive shell and wire events are supported. (`external/kimi-cli/src/kimi_cli/soul/btw.py:33-93,102-190,233-247`; behavior: `external/kimi-cli/docs/en/reference/slash-commands.md:247-256`; modal handling: `external/kimi-cli/src/kimi_cli/ui/shell/visualize/_interactive.py:120-189,281-324`.) |
+| **OpenCode** | Makes a one-shot generation from the selected session's previewed history, system transcript, and tool definitions, followed by the BTW instruction and question. | The generation explicitly does not mutate the session; it returns text rather than entering a tool-execution loop. The question/answer live in a separate per-session extension store until the tab closes. | One side tab per question; supports retry and copy. The command is enabled only with an open session in a desktop-width window. (`external/opencode/packages/core/src/session/generate.ts:25-65`; extension state: `external/opencode/packages/gui-extensions/src/btw/model.ts:7-110`; command/panel: `external/opencode/packages/gui-extensions/src/btw/renderer.tsx:32-101`.) |
+| **OpenHands** | The default SDK path prepares a request from the enforced conversation snapshot plus the side question, using the agent's model and tool definitions. | `ask_agent` is documented as stateless: it does not alter conversation state, persist events, or change execution status. It makes a direct generation rather than running tool actions. The UI entries are held in a client-side store. | The UI shows a pending card and then the answer, which can be expanded or dismissed; it waits for the response rather than rendering token deltas. (`external/openhands-agent-sdk/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py:2903-2966`; interception: `external/openhands/src/hooks/chat/use-btw-interceptor.ts:13-43`; client state and card: `external/openhands/src/stores/btw-store.ts:1-68`, `external/openhands/src/components/features/chat/btw-messages.tsx:11-55`.) |
+
+## Cross-cutting trade-offs
+
+- **Context breadth:** Harness terminal and Agent App construct bounded excerpts. Oh My Pi, Kimi CLI, OpenCode, and OpenHands reuse broader session context. Oh My Pi is the most explicit about carrying live state—and its code includes current thinking blocks—so it is also the least restrictive about what private context the side request can see.
+- **Tool boundary:** Harness terminal and Agent App suppress tools at launch. Kimi advertises the main tool definitions but denies execution and retries after a tool attempt. Oh My Pi, OpenCode, and OpenHands make direct side generations without dispatching the returned answer through the main agent's tool-execution loop; some still send tool definitions for context or cache alignment.
+- **Retention:** Harness terminal is intentionally transient. Agent App retains an ordinary run record for observability. Oh My Pi has durable, followable BTW topics; OpenCode retains one tab's question and answer in its session store. OpenHands' displayed entries are client-side state, not main conversation events.
+- **Cache versus least privilege:** Kimi CLI explicitly aligns system prompt and tool definitions for cache reuse; Oh My Pi reuses the main session's prompt/cache path. This means broader context and tool metadata may be sent than the bounded-snapshot designs require.
+
+## Study implications
+
+1. Keep the Harness terminal's bounded context and hard no-tools setup as the conservative generic default.
+2. If a side question needs better awareness of an active run, prefer a bounded summary of public progress over forwarding hidden reasoning or raw tool inputs/results. Agent App already demonstrates that application-specific snapshot at the App layer; keep that ownership boundary intact.
+3. Treat persistent follow-up topics, branching, and RPC support as optional product capabilities, not requirements of a basic side question.
+
+## Coverage note
+
+A source scan found no `/btw` implementation in the checked-out `external/deepseek-harness`, `external/harness2`, `external/smolagents`, or `external/swe-agent` trees. Matches in `external/orca` were fixture/test references, not an implementation. These are observations about the local snapshots, not claims about current upstream releases.

package/docs/study/feature-gap-review.md

@@ -0,0 +1,42 @@
+# Harness feature-gap review
+
+**Scope:** What `@xingular/harness` provides compared with the agent systems in the local harness study. This is a feature-gap review, not a parity score. Comparisons refer to the studied snapshots; the deeper OpenHands and Claude Code audits are still marked pending in the [study index](00-index.md).
+
+## Summary
+
+The Harness is a generic single-run runtime, not a task manager or long-running workflow engine. Some apparent gaps are deliberate layer boundaries: the architecture assigns product tasks, schedules, teams, worktrees, and UI to the embedding application. The run record has an opaque `goal` string, but no goal lifecycle or progress model. See [00 Overview](../architecture/00-overview.md#layers) and [02 Sessions and runs](../architecture/02-sessions-and-runs.md).
+
+| # | Capability missing from the Harness | Current state and comparison | Appropriate owner |
+|---:|---|---|---|
+| 1 | **First-class task lifecycle** — create, assign, track status, dependencies, review, and acceptance | Normal sessions track runs; `RefineTask` is for harness-tree refinement, not product work. OMP has a task-delegation tool. | **Application** |
+| 2 | **Persistent goals and progress** — goal hierarchy, checklist, and durable progress | Plan mode produces a proposed plan, not tracked progress. `goal` on a run is opaque metadata. OpenCode has per-session todos; OMP exposes a goal helper. | **Application**, optionally through a tool provider |
+| 3 | **Long-running job scheduler** — durable queue, cron/event triggers, deadlines, retries, and leases | Sessions can run asynchronously, but the Harness has no durable scheduler. The OpenHands study identifies scheduling in a separate automation project. | **Application** |
+| 4 | **Crash-safe continuation** — resume from a checkpoint after a process or machine restart | Run events and Pi history persist, and terminal history can be resumed manually. However, startup marks active runs interrupted; the Harness does not restart model work. | **Harness + application**: recovery contract plus requeue policy |
+| 5 | **Automatic cross-run memory consolidation** — extract useful task state and lessons from completed runs | The Harness has Wiki notes, history, and a refinement experience library, but no automatic task-state consolidation pipeline. OMP's study describes background memory extraction and consolidation. | **Harness** for generic memory; **application** for task state |
+| 6 | **Team and work-queue orchestration** — persistent workers, assignments, dependencies, and shared coordination | Harness subagents are fresh parent-child runs with result delivery, not a persistent team or shared queue. OMP has task-worker machinery; product-level coordination belongs outside the Harness. | **Application** |
+| 7 | **Managed per-task sandbox/workspace** — containers, worktrees, snapshots, and rollback | The host supplies the working folder and tools; the Harness tool gate is not an OS sandbox. The study contrasts this with OpenHands/SWE-agent containers and OMP worktrees. | **Application/host** |
+| 8 | **Native browser and computer interaction** | Web search/fetch can be provided as tools, but browser or computer control is not built in. Plan-mode text mentioning managed controls is recorded as known drift (D-6). | **Application**, through tool providers and policy |
+| 9 | **Goal-specific verification and acceptance** — tests, graders, and a “done” gate | The refinement matrix records execution and deliverability; it does not grade whether a user's goal was achieved. Frozen task grading belongs in Evaluation. | **Evaluation/application** |
+| 10 | **Aggregate operations dashboard and budgets** — cross-run cost limits, alerts, and health views | The Harness records per-run events and usage. It has no built-in aggregate dashboard; an optional budget-guard plugin partially covers per-run limits. OMP's study describes a local stats dashboard. | **Application UI**, using Harness run data |
+
+## Status (2026-10-22)
+
+The Harness-owned parts of three gaps have landed. The application-owned parts and the other
+seven gaps are unchanged.
+
+| # | What landed in the Harness | Taken from | Still the application's |
+|---:|---|---|---|
+| 2 | `checklist_write`: the model's whole checklist as a `checklist.updated` run event, read with `runs.checklist` ([PROP-0006](../architecture/proposals/PROP-0006-run-checklist.md)) | dsh `todo_write` (whole-list replace, three statuses, replayed from the log); OpenCode `todowrite` (usage rules in the tool description) | Goal records, goal hierarchy, progress across runs, showing the checklist |
+| 4 | `continueFrom` and `runs.continuation`: a stopped run is continued as a new run with the same account, tree version and capabilities, and the model is told where it stopped; `Recovery.interruptedRunIds` ([PROP-0007](../architecture/proposals/PROP-0007-run-continuation.md)) | Every peer's "never restart silently" rule; dsh's durable log as the checkpoint; OpenHands' requeue outside the agent | The requeue policy: which runs to continue, when, and whether to ask first |
+| 5 | The opt-in `lessons` plugin: a read-only reflection after a completed run may keep one lesson in the Wiki under `library/lessons/` ([PROP-0008](../architecture/proposals/PROP-0008-lessons-from-runs.md), [ADR-0010](../decisions/ADR-0010-lessons-in-the-wiki.md)) | harness²'s reflector (cue → lesson, `NO_ENTRY`, never task facts, answer-free guards); OMP's background extraction and caps | Task state and its consolidation; a switch for the plugin in its UI |
+
+## Recommendation
+
+For products that need autonomous long-running work, start with an application-owned task/goal model and scheduler, then define how they request safe continuation of Harness runs. Keep task and schedule concepts out of the Harness itself; its architecture deliberately assigns them to the application. A useful first sequence is: (1) task and goal records with acceptance criteria, (2) durable scheduling and human handoff, (3) explicit restart/recovery policy, then (4) isolated workspaces and an evaluation gate.
+
+## References
+
+- Harness ownership and application boundary: [00 Overview](../architecture/00-overview.md#layers), [02 Sessions and runs](../architecture/02-sessions-and-runs.md#invariants).
+- Harness memory and refinement: [08 Memory and history](../architecture/08-memory-and-history.md), [05 Refinement](../architecture/05-refinement.md).
+- Peer comparisons: [Tools](arms/02-tools.md), [Subagents](arms/03-subagents.md), [Memory](arms/06-memory.md), [Execution](arms/08-execution.md), [Observability](arms/09-observability.md), [wide comparison matrix](arms/00-matrix.md).
+- Source inventories: [OpenHands](sources/openhands.md), [OMP](sources/omp.md), [SWE-agent](sources/swe-agent.md), [OpenCode](sources/opencode.md).