@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/study/arms/04-skills.md

@@ -0,0 +1,81 @@
+# Arm 04 — Skills & loading
+
+Status: **three sources audited** (dsh, opencode, harness² + our tree);
+omp's skill tool verified as builtin only (`manage_skill`); claude-code/openhands pending.
+
+## Design space
+
+Skill format and discovery, what ships in context (name+description only vs
+whole body), how bodies are fetched (tool call vs command), trust (does loading
+run code?), and the ruling constraint here: the harness is the only loader, with
+extension discovery switched off.
+
+## Comparison
+
+**this harness.** Skills are part of the versioned tree (c6), loaded only when
+their exact code is trusted (`src/tree/trust.ts`), surfaced via tree sections
+and `Plugins.loading` (src/plugins/) — extension discovery is disabled; the
+seed includes an `autotrigger` mechanism (`src/tree/tree.ts`, used by
+`src/tree/seed.ts`) — skills may carry trigger conditions compiled into
+always-on text.
+
+**opencode.** `SKILL.md` files found by a depth-6 scan
+(`.../core/src/config/plugin/skill-scan.ts:3,29`), also fetched from URL
+indexes into a global dir (`.../skill/discovery.ts:112,194`); availability is
+permission-gated (`.../skill.ts:33-34`). Progressive disclosure: instructions
+list skills in system context; the `skill` tool lazily loads the body "when
+the task at hand matches its description", including a sampled file list
+(`.../tool/plugin/skill.ts:19-33`).
+
+**omp.** `manage_skill` builtin (30 builtins list,
+`.../tools/builtin-names.ts:24`); skills also **emitted as a product of memory
+consolidation** (`docs/memory.md:78-88` — learned lessons land in `skills/` on
+disk), an unusual write-back path. Trust/approval per separate ability loading
+unverified.
+
+**dsh.** The cleanest contract: before the first request the model receives a
+**durable catalog** — "available skill names and capped descriptions"
+(default cap 500 chars) — and loads body instructions through the `skill` tool;
+`/name` invocation injects the same instructions the user named;
+catalog changes append a **complete replacement** message, empty catalog retires
+old names (`.../packages/skill/tool-skill/README.md:12,54-57`).
+
+**harness² — the validation-first school.** Frontmatter requires `name:`
+matching the directory and a `description:`; a malformed file is silently dropped
+load if malformed (`.../core/prompts.py:113-115` in the tts pack: naming rules,
+and `.../prompts.py:151-157`: "An unnamed skill is never opened anyway").
+Its three discard rules (trigger line naming the skill in always-on text; no
+template braces; shipped scripts travel with the skill,
+`.../prompts.py:148-167`, `.../core/tree.py` validation) turn prompt-prose
+conventions into machine-checks — the same philosophy as our `validate()`.
+
+**claude-code / openhands (pending).** SKILL.md progressive disclosure spec and
+SDK microagents respectively.
+
+## Trade-offs
+
+- **Catalog hygiene.** dsh's "complete replacement + empty retires" keeps
+  staleness windows near-zero on a cheap message; opencode's rescan keeps
+  file-truth simplicity. The durable-catalog variant is the better fit for our
+  file truth. The durable-catalog variant is the better fit for our
+  stable-prefix diagnostics (context updates could carry skill deltas).
+- **Validation turns conventions into gates.** harness² proves skill trigger
+  lines and shipped scripts can be enforced mechanically; ours additionally
+  require trust for *code* — the sharpest position (everything model-visible is
+  a plugin, c8 loads only trusted content).
+- **Cost shape.** Everyone: bodies are free until invoked; naming is the true
+  gate. An unnamed skill is dead weight in all four.
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| K1 | Emit a **skill catalog delta** (name + capped description) in the hidden `xingular-context` message instead of relying on static tree text alone, when trees change mid-run | dsh durable-catalog + our context-update channel | `src/prompt/compile.ts` context update contents | T2 |
+| K2 | Adopt harness²'s three validation rules into `validate()` (trigger-line presence for skills; script existence paths already enforced, re-verify) | harness² | tree validation + tests | T1 verify-first |
+| K3 | **Enforce skill trigger lines mechanically** (autotrigger already carries triggers; keep prose+code in sync) | both | `src/tree/tree.ts` validation | T1 verify-first |
+
+## Related
+
+Installation — where a skill is placed, globally or per project, and what the model is told about
+it — is a separate question from loading. See
+[STUDY-0005](../STUDY-0005-skill-installation-guidance.md).

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.