@xingular/harness 0.1.7 → 1.1.1

package/docs/study/arms/03-subagents.md

@@ -0,0 +1,90 @@
+# Arm 03 — Subagents
+
+Status: **core four audited** (opencode, omp, dsh, plus our ADR-0003 lineage);
+openhands/claude-code pending.
+
+## Design space
+
+Spawn model (tool vs scheduler vs server), child context (fresh, forked, or
+continuable), isolation primitives (separate session, separate history, own
+worktree/capabilities), delivery (block vs background + receipts), routing
+(manual naming vs description-based auto-selection), and depth/capacity limits.
+
+## Comparison
+
+**this harness.** `spawn_subagent` + `wait_subagents` tools
+(`src/tools/spawnSubagent.ts`): child is "a fresh child run for independent
+work… no conversation history and no more capabilities than you"; spawn returns
+the child run id immediately; results arrive **automatically before you finish**
+(native-history delivery receipts per ADR-0003); 24k per-report cap
+(`spawnSubagent.ts` `reported()`); depth limits live in
+`src/sessions/subagents.ts` (exported constants). Architectural statement:
+Architectural statement:
+opaque-run children (runStore writes, opaque ids).
+
+**opencode — subagent is a tool, not a scheduler.** Agents registry
+(`mode: primary|subagent`) with selectability excluding subagents from direct
+conversation (`.../core/src/agent.ts:74-75`). The `subagent` tool rejects
+primaries/unknowns, enforces depth via config, asserts permission, then creates
+a child session and prompts it "You are a subagent spawned by another session."
+— **fresh context, nothing inherited** (`.../tool/plugin/subagent.ts:129-218`).
+Foreground variant blocks and wraps the final text in
+`<subagent sessionID=… state="completed">`; background replies immediately with
+an explicit **never-poll instruction** and completion notification
+(`.../subagent.ts:19-27,229-265`). **Routing is description-based**: a context
+hook appends "Available subagents:" with each agent's own description to the
+tool description (`.../subagent.ts:282-309`).
+
+**omp — spawn machinery with isolation budgets.** The `task` tool; agent
+definitions from bundled + `~/.omp/agent/agents/*.md` + `.omp/agents/*.md`
+(`.../task/index.ts:4-10`). `SpawnRun` holds a semaphore permit and streams
+progress; the owner adopts binding abort signal/sinks
+(`.../task/spawn-run.ts:47-88`). **Speculative launch starts the child while
+the `tasks[]` argument is still streaming** (`.../task/speculative-launch.ts`).
+Isolation: pinned settings, advisor forced off, **mid-turn compaction forced on
+(whole assignment is one turn)**, isolated runs get their own **worktree** and
+may not expose roots outside it (`.../task/executor.ts:1132,4033-4055,4339`).
+Structured children get `yield` to stream partial results
+(`docs/task-agent-discovery.md:38`).
+
+**dsh — services + backends, two child topologies.** `ctx.subagents` +
+provider backends (local, ACP, Codex, Claude DSH-SDK) + a tool plugin
+(`.../packages/subagent/README.md:27-35`). Spawn returns `started subagent
+<childId>` immediately; a completion notice delivery later
+(`.../tool-subagent/README.md:59`). `spawn` = fresh child; **`fork` = seeded
+from the parent's completed history** (`.../subagent/README.md:28-29` — the one
+source with tree-history in context children). Local children **continue
+accepting messages** (cold-resume); external backends "execute once"
+(`:12,61`). Defaults: 8 active, depth 1 (`.../subagent/README.md:53,49`).
+The model names presets from an enum allowlist; **no description routing**
+(`.../tool-subagent/README.md:52,68`).
+
+**openhands (pending)** conversation-per-container REST server;
+**claude-code (pending)** `.claude/agents/*.md` description routing.
+
+## Trade-offs
+
+- **Receipts vs block.** Ours receipts-then-auto-deliver; opencode's
+  foreground blocks and the background variant needs a no-poll instruction to
+  stop wasted loops — our "results arrive automatically" tool description does
+  the same thing natively. block variants pay latency, buy simplicity.
+- **What the child sees.** Everyone defaults fresh. dsh's `fork` (parent history
+  as seed) is the only in-history-inherited design — powerful for "continue in
+  the main context's condition", dangerous for either prosecution
+  side-venting or slow joins; ours rejects it by `"no more capabilities than
+  you"` + fresh-run rule.
+- **Isolation granularity.** worktree (omp isolated runs) is the strongest
+  world-isolation; ours ties isolation to account and run records instead. The
+  `tools` CSV narrowing idea maps to our `capabilities.intersect` — same
+  primitive, different vocabulary.
+- **Routing.** Description-based auto-pick (opencode, and claude-code's docs)
+  puts all selection power in the model's reading; ours requires named briefs
+  and a Directory when names exist, which matches the opaque-id
+  contract (no names in the harness; names arrive via Directory).
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| S1 | Inject capability-set summaries (slots "Current subagents") into the tool description **when names exist via Directory**, instead of static description | opencode context hook | tool provider building the spawn tool's description | T2 (only if app supplies names) |
+| S2 | Receipt text carries child tool limits next to the 24k cap (`reported()` already does this only implicitly; make the receipt self-describing) | ours (deficiency) | `spawnSubagent.ts` | T1 |

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

@@ -0,0 +1,75 @@
+# 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 |

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 |