@xingular/harness 0.1.7 → 1.0.0

package/docs/study/roadmap.md

@@ -0,0 +1,72 @@
+# Adoption roadmap — implementing these findings in this harness
+
+Derived from `arms/01–10` and `insights.md`. Tiering: **T1** = landed patterns
+from battle-tested open harnesses, adopt now; **T2** = adopt after a check or a
+measurement; **T3** = park. Every item lands through one of the seven surfaces
+(prompt sections, tool providers, `ToolPolicy`, `SecretStore`, `Directory`,
+plugin descriptions, `RefineHost`) or the tree/refine machinery already in
+`src/`, never by naming an application concept. Check plan: `npm run typecheck`,
+`npm test`; `npm run prove` when the server/CLI/startup changes.
+
+## Tier 1 — adopt now
+
+| # | What | Where it lands | Why & source | Verification |
+|---|---|---|---|---|
+| 1 | **Prompt-section ordering contract**: contributors declare a numeric order; compilation sorts (order, then name), rejects duplicate ids, scoped entries shadow globals | prompt compilation in `src/prompt/compile.ts` + plugin descriptor (`src/plugins/builtin.ts`) | dsh's section contract — deterministic ordering is a *cache* and *reasoning* asset (arm 01, insight 3) | unit tests incl. duplicate-order throws and shadowing either-order |
+| 2 | **Tool approval tiers**: every ToolSpec declares `read\|write\|exec`; standing-approval policy wording derives from tiers | `ToolPolicy` + `src/tools/types.ts` (+ tool providers' default rows) | omp's tier×policy legibility (arm 02/07) | the tier is mandatory in the gate path; docs |
+| 3 | **Policy-missing ⇒ ask** invariant with tests | gate in `src/` (`ToolPolicy` evaluation) | omp fails closed; dsh bundle default (arm 07) | a gate test per missing-policy shape |
+| 4 | **Tool descriptions as template files**: description text lives in `.md` (interpolating `{product}`), imported `type:"text"` — no inline instruction literals in tool definitions | `src/tools/*` | omp's "prompts never in code"; reviewability (arm 02) | build renders identical output; no behavior change |
+| 5 | **Subagent receipts self-describe limits** (24k cap, delivery semantics) inside the receipt text | `src/tools/spawnSubagent.ts` | ours — the cap exists but is implicit (arm 03, S2) | receipt content test |
+| 6 | **Tree validation adopts harness²'s discard rules** where missing: skill trigger-line presence in always-on text; braces checking; script-existence (re-verify which already hold in `validate()`) | `src/tree/tree.ts` + tests | harness² turns prompt conventions into machine gates (arms 04/10, K2/K3) | a failing-tree test per rule |
+| 7 | **Sync refinement prompts with upstream drift**: pull changed sentences from harness² `adapt` pack (pool-anonymity, deliverable-shape rule) into `src/refine/prompts.ts` | `src/refine/prompts.ts` | upstream evolved past our port snapshot (arm 10, R1) | existing refine tests stay green; wording-insensitive assertions |
+| 8 | **`<notes>` decision-audit format** added to compose/selection stages (kept\|revised\|dropped → edit → evidence) | `src/refine/prompts.ts` | tts pack's auditability upgrade (arm 10, R2) | schema on notes parse |
+| 9 | **Volatile-value placement rule**: no date/cwd/env in the stable prefix ever; supply via `xingular-context` channel or a user-turn injection | `src/prompt/compile.ts` (nothing, if currently absent — confirm) | omp's invalidation lesson (arm 01, A1; **verified**: our compiler injects none today) | a lint-style test asserting the prefix has no volatile lines |
+| 10 | **Normative docs**: one-subprocess-service norm and identity-blind transport commitment for any future telemetry-like export | repo README / docs | dsh (arms 08/09, E2/O1) | ADR text only |
+
+## Tier 2 — adopt after a check or measurement
+
+| # | What | Precondition | Landing surface |
+|---|---|---|---|
+| 11 | Compaction shapes: fixed named-template summary + verbatim tail checkpoint + prune-first ordering | inventory our current compaction behavior first (Pi-native history; no `src/` compaction found) | `RefineHost`/session docs, then prompt sections for restoration text (arm 05, C1–C3) |
+| 12 | `toolOrder` validation for pinned tool sets (unknown/rejected/marker rules) | confirm our capability freezing can't already be ordered inconsistently | `sessions.run` freeze path (arm 02, A4) |
+| 13 | Restriction masks equivalent to dsh `ctx.tools.restrict` — check whether `capabilities.intersect` already covers scoped narrow-and-lift before adding anything | read `src/capabilities/` | none if covered (arm 02) |
+| 14 | Skill-catalog deltas in `xingular-context` when tree versions change mid-run | assess token cost of name+description deltas vs tree sections | context update contents (arm 04, K1) |
+| 15 | Substrate-parity test R5: an upstream harness² candidate tree validates under `PI_SURFACE` without edit | none — test only | `src/tree/` tests (arm 10, R5) |
+| 16 | **Cache warming** near TTL (omp `cache-warmer.ts`) and the cache-*stable-prefix* probe protocol: engineering lives app-side; the harness may only need to expose request timing in run events | measure with `probe-chat-cache-app.py` from the App repo, with the account owner's permission | nothing harness-side unless events lack durations (arm 01, A5) |
+| 17 | Sandbox classes offered as `ToolPolicy` options (read-only/workspace-write) | app-level sandbox plumbing exists | ToolPolicy (arm 08, E1) |
+
+## Evaluation of the harness — suite and sweep items
+
+How the harness itself gets measured over time (STUDY-0001; the mechanism is
+`src/refine/`, with frozen tasks and sweeps owned by the Evaluation repo).
+
+| # | What | Where it lives | Status |
+|---|---|---|---|
+| E1 | **Evaluation matrix** (`runMatrix`): tree × task deliverability records with comparability keys (task-hash, executor, package version, fingerprint); `refine matrix` CLI taking tree dirs or committed scope versions; records beside refinements (`refine/<id>/matrix.json`) | `src/refine/suite.ts`, `refine/cli.ts` | **landed** (05/12 pages updated) |
+| E2 | No-model CI lane: the matrix through the demo executor, proved standalone | `scripts/prove-standalone.mjs` | **landed** |
+| E3 | Tree-lineage sweep: matrix across every adopted version of a scope | suite `{scope, version}` entries; a driver later | capability landed |
+| E4 | Frozen task library: answer-stripped `RefineTask` records + source fixtures + leak globs | Evaluation repo | pending |
+| E5 | Commit-range sweep: per commit, git worktree → `refine matrix` → matrix rows | Evaluation repo (drives production code; never fakes a session) | pending |
+| E6 | Regression report: flip table (delivered⇄empty), cost-per-delivered between two matrices | Evaluation repo dashboard | pending |
+| E7 | Suite-based adoption gate: `adopt` only when the chosen tree wins the frozen suite, else `keep_base` | `refine/service.ts` policy; suite data from Evaluation | pending |
+| E8 | Real PiExecutor lane with cost/wall budget stops | Evaluation repo + App; needs the account owner's approval | parked until approved |
+
+## Parked / anti-candidates (recorded, do not build)
+
+- `memory://` protocol over wiki tools (omp mnemopi) — caps/budgets suffice for now (arm 06, M2).
+- `fork`-style history-seeded children (dsh) — breaks the fresh-child accounting model (arm 03).
+- Free code-as-action for model tools (smolagents) — the per-call gate is a load-bearing contract; revisit only behind a RefineHost-scope opt-in (arm 02).
+- In-harness judge module — requires the family-layering decision (Evaluation owns measurement) before any port; if ever ported, port the *decoupling shape* verbatim (arm 10, R4).
+- omp's in-process coretools shell environment — an execution detail of
+  omp/pi-shell, host-supervised here; not adoptable machinery (arm 08).
+
+## Sequencing
+
+1. Items 1–4 (contract tier: prompt ordering, tiers, fail-closed, template descriptions) — one focused change each, with tests; land first because later items build on the vocabulary.
+2. Items 5–9 (mechanical: receipts, validation, prompt sync/notes, placement rule).
+3. Item 10 + Tier-2 checks (12–15) as a small batch.
+4. Measurement-gated items (11, 16) last, through the App scripts where indicated.
+
+Every landed item updates the relevant arm doc's "adoption candidates" row to
+`landed: <path>` and adds an ADR when the change alters a contract (server
+methods, tool gate semantics, tree validation).

package/docs/study/sources/claude-code.md

@@ -0,0 +1,44 @@
+# Source: Claude Code (Anthropic) — no local code
+
+- Origin: [Anthropic Claude Code](https://www.anthropic.com/claude-code). Not open
+  source: no clone. Material to audit: the npm package (`@anthropic-ai/claude-code`,
+  bundled JS — inspect for system prompt and tool descriptions), Anthropic's
+  engineering blog posts on Claude Code (agent loop, harness internals, sub-agent
+  guidance, compaction), the skills spec (agent skills API), and observed CLI
+  behavior (`/hooks`, `Permission` modes, CLAUDE.md hierarchy, memory
+  instructions).
+- Why studied: the de-facto reference for UX-shaped harness conventions — CLAUDE.md
+  hierarchy, skills, subagents as first-class configs, hook events, plan mode,
+  permission modes. Every other harness in this study copies it knowingly or not.
+
+## Map to arms (from public, verifiable material — no code claims)
+
+- Arm 01 (prompt): CLAUDE.md hierarchy (enterprise/user/project/local), `@file`
+  imports, `#` quick-memory, output styles forcing; the leak-history repo
+  (community) documents the shipped system prompt — cite carefully, it changes.
+- Arm 02 (tools): bundled tools w/ rich descriptions ("use when…" instructions
+  live in tool descriptions, not the prompt); MCP support.
+- Arm 03 (subagents): `.claude/agents/*.md` subagent files w/ own name/description/
+  toolset/model; auto-delegation by description matching.
+- Arm 04 (skills): SKILL.md progressive disclosure (name+description only loaded;
+  body read on demand), script support.
+- Arm 05 (context): compaction thresholds, `--continue/--resume`, context restore
+  via note files.
+- Arm 06 (memory): `CLAUDE.local.md`, `#` memory notes, user memory file.
+- Arm 07 (governance): permission modes (default/acceptEdits/plan/
+  bypassPermissions), allow/deny rules patterns, hooks (PreToolUse/PostToolUse)
+  as policy handlers, sandboxed bash per platform.
+- Arm 08 (execution): bash w/ working-dir constraints; desktop app tooling.
+
+## Open questions for the audit (each needs its citation landing)
+
+1. SKILL.md spec: exact progressive-disclosure contract; compare against this
+   harness's skill loader c7/c8 + trust requirements.
+2. Hooks: which events exist, do they mutate tool input (``PreToolUse`` update
+   semantics) — contrast with the here-rule "a hook is told, never asked".
+3. Subagent file spec: fields, tool inheritance, model pinning; our extension
+   point answer.
+4. Plan mode mechanics (bilateral approval) — how does its gate differ from our
+   refinement probes (answer-free, no world effect).
+5. Verbatim from a recent npm bundle: capture current system prompt + tool
+   descriptions and date-stamp them.

package/docs/study/sources/deepseek-harness.md

@@ -0,0 +1,102 @@
+# Source: deepseek-harness (dsh)
+
+- Origin: [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness),
+  released Aug 2026, MIT, developer preview (compatibility-breaking expected).
+  Built on the Cordis meta-framework ("spatiotemporal composability"); one radical
+  claim: **everything is a plugin** — model adapters, tool registry, session log,
+  sandboxes, and the agent loop itself have no privileged core.
+- Local clone: `external/deepseek-harness` (205 MB).
+- Status: **arm-01 audited; arms 02–06 audited** (explorer report; verified spot
+  checks pending — treat claims below as explorer-verified until I re-read).
+
+## Verified layout
+
+`packages/` (arm-shaped): `acp`, `api`, `attachment`, `boot`, `browser-use`,
+`bundle`, `client`, `compaction`, `computer-use`, `context`, `core` (with
+`packages/core/tools`, `packages/core/system-prompt`, `packages/core/agent-loop`),
+`credentials`, `deliverables`, `fs`, `guard`, `host`, `identity`, `interaction`,
+`jobs`, `llm`, `lsp`, `mcp`, `plan`, `preset`, `ptc-runtime`, `sandbox`,
+`schedule`, `session`, `session-query`, `settings`, `shell`, `skill`, `spill`,
+`ssh`, `storage`, `subagent`, `subprocess`, `telemetry`, `terminal`, `todo`,
+`util`, `web`, `workflow`, `workspace`.
+
+## Core facts per arm (audited)
+
+**02 tools.** Canonical registry is `ctx.tools` (dsh-tools), not the loop:
+declaring a tool via `defineTool` makes it visible, and ToolRuntime feeds the
+system prompt automatically (`packages/core/tools/README.md:30,34-62`;
+`packages/core/tools/src/index.ts:857`). Two presentation modes: `native`
+(all schemas) vs `ptc` (models see only `run_code` + generated SDK — programmatic
+tool calling), with per-agent `presentAs` override
+(`packages/core/tools/README.md:68-81`). Plain restriction API:
+`ctx.tools.restrict(filter)` allow/deny masks that intersect and lift on dispose
+(`README.md:85`). **The gate is inside dsh-tools**, a fixed pipeline:
+`tools/pre-execute` (allow/deny/ask) → monotonic `ctx.tools.guard()` reasons →
+`tools/execute` → `tools/post-execute` → observe-only `tools/result`
+(`README.md:89,109`; ask at `packages/core/tools/src/index.ts:608-612,1513-1527`).
+`packages/guard` is *not* the gate — it is loop hygiene (repeat-tool reminder,
+timeout policy). `toolOrder` is validated config: explicit model-facing order,
+exactly one `<unlisted-tools>` rest entry, unknown names fail assembly
+(`packages/core/system-prompt/README.md:50-52,179`). Bundle = profile patch
+layer stacked over `dsh-base`, which ships a default wallet policy confining
+file writes and asking before risky actions
+(`packages/bundle/README.md:12`, `packages/bundle/base/README.md:50`).
+
+**03 subagents.** `ctx.subagents` + provider backends + tool plugins
+(`packages/subagent/README.md:27-35`). Spawn returns immediately with
+`started subagent <childId>`; completion notice delivered later
+(`tool-subagent/README.md:59`). Two kinds: fresh child (`spawn`) vs `fork`
+seeded from the parent's completed history (`README.md:28-29`); local children
+are continuable; external backends (ACP/Codex/Claude Code) "execute once"
+(`README.md:12,61`). Capacity defaults: 8 active, depth 1
+(`subagent/src/README.md:53,49`). **No description-based auto-routing** in dsh —
+the model names a preset from an enum allowlist (`tool-subagent/README.md:52,68`).
+
+**04 skills.** Progressive disclosure: before the first request the model gets a
+durable catalog of names + capped descriptions (default cap 500 chars), and
+loads full body via the `skill` tool; `/name` invocation injects the same
+instructions (`packages/skill/tool-skill/README.md:12,54-56`); catalog changes
+append a complete replacement; empty catalog retires names
+(`:57`).
+
+**05 context.** `compaction-basic` triggers at
+`floor(min(W×0.8, W−O−headroom))` with 65_536 headroom, keeps the newest 16%,
+one extra model request, only the summary retained
+(`packages/compaction/compaction-basic/README.md:12,32,62-68`; `config.ts:75-78`);
+oversized tool outputs pruned first, image placeholders swapped for offloaded
+images (`packages/compaction/README.md:31-32`). `session-query` = SQLite FTS5
+search over the durable log, independent of compaction
+(`packages/session-query/README.md:12,30`).
+
+**06 memory.** No memory package by design. Durables: immutable canonical JSONL
+sessions with checkpoint policy (`packages/session/README.md:38-39`), todo lists
+persisting across sessions (owned by the session, whole-list replace,
+`packages/todo/README.md:12`), `spill` = full text stored outside context with
+locator + retrieval guidance (`packages/spill/README.md:12,30-31`),
+`storage` = non-session app data, never model-visible
+(`packages/storage/README.md:12,27-30`), `deliverables` = per-turn outputs as
+client-only session events with `workspace/changes` derived from git snapshots
+(`packages/deliverables/README.md:12,27-28`). Cross-session agent memory:
+unaddressed.
+
+**07–09 briefs.** Sandbox = file-effect policy classes
+(read-only/workspace-write/danger-full-access) with Landlock/Seatbelt/Windows
+backends and one-time approved escalation (`packages/sandbox/README.md:12,30`);
+one shell executor per composition (`packages/shell/README.md:12,38`); one
+`ctx.subprocess` service with bounded output and scrubbed env
+(`packages/subprocess/README.md:12,27`); telemetry is an OTel transport with
+`FEEDBACK_ONLY` default (`packages/telemetry/README.md:12,25`,
+`packages/bundle/base/README.md:50`).
+
+## Open questions, answered
+
+1. Tool plugin interface → `defineTool` + `ctx.tools` registry; schemas flow to
+   the prompt via ToolRuntime's self-registration.
+2. `guard` → not the approval mechanism; gate = `tools/pre-execute` pipeline in
+   dsh-tools.
+3. `ptc-runtime` → programmatic tool calling: models get exactly `run_code` plus
+   a generated SDK; executionInstructions carry syntax/state guidance.
+4. `spill` → out-of-context storage returning locators; feeds compaction policy.
+5. `acp` → Agent Client Protocol islands (one of several subagent backends).
+6. Plugin prompt contributions → ordered sections incl. `.tools()` providers;
+   ordering is a validated contract (see arm 01).

package/docs/study/sources/harness2.md

@@ -0,0 +1,50 @@
+# Source: harness² (Google Research)
+
+- Origin: [google-research/harness2](https://github.com/google-research/harness2)
+  (Apache 2.0) and the paper *Harness²: Recursive Agent Harnessing for an Open
+  World* — Xu et al., 2026, [arXiv:2610.14224](https://arxiv.org/abs/2610.14224)
+  (PDF saved at `external/harness2/harness2-arxiv-2610.14224.pdf`). Project page:
+  [harness2.github.io](https://harness2.github.io/). Site: 11.5 pts WorkBuddy-Bench
+  etc. — verify exact numbers from the paper before citing.
+- Local clone: `external/harness2` (Python). Note: substrate adapters include
+  `opencode.py` and `codex.py` — harness² wraps other harnesses.
+- Why studied: the conceptual core of this study. A harness = everything around a
+  frozen model (prompts, tools, memory, skills, orchestration); harnessing =
+  optimizing that system recursively, at task level (edit → probe → compose) and
+  harness level (experience reflector → improvement harness).
+
+## Verified layout
+
+`harness2/core/`: `prompts.py`, `proposer.py`, `recursion.py`, `selection.py`,
+`judge.py`, `library.py`, `ledger.py`, `tree.py`, `context.py`, `spec.py`,
+`schedule.py`, `runmark.py`, `report.py`.
+
+`harness2/substrate/`: `base.py`, `codex.py`, `opencode.py`.
+
+`harness2/cli/`: `bridge.py`, `judge.py`, `run_sweep.py`, `check.py`, `report.py`,
+`setup.py`, `demo.py`.
+
+Docs: `docs/BENCHMARKS.md`, `docs/EXPERIMENTS.md`, `docs/SETUP.md`.
+
+## Map to arms
+
+- Arm 10 (refinement ⭐ — primary): `proposer` (harness editor: invariant vs domain
+  edits), probes/executor for candidates, `selection` (composer choosing among
+  candidates), `recursion` (two levels), `judge` (answer-free self-labelling of
+  rollouts), `library` (experience library), `ledger` — compare against this
+  harness's Propose–Probe–Compose, answer-free selection, experience library,
+  refine/ledger identity, and `RefineHost` isolation.
+- Arm 01 (prompt): `tree.py` + `context.py` — what their harness tree/editable
+  files look like vs this harness's versions never, only superseded.
+- Arm 06 (memory): `library.py` — cross-task experience write-back policy.
+
+## Open questions for the audit
+
+1. What is editable in their harness tree, what is invariant, and how does
+   "invariant" map to this harness's capped/validated c1–c4?
+2. How does their self-judge stay answer-free — is its label visible to proposer
+   and composer, and does its error bar matter?
+3. How are candidate probes isolated (workspace, approvals refused)?
+4. What does the experience reflector write back, with what schema and trigger?
+5. Which substrate contract does `substrate/opencode.py` actually need — is one
+   substrate adapter for this harness feasible via `RefineHost`?

package/docs/study/sources/kimi-cli.md

@@ -0,0 +1,42 @@
+# Source: Kimi CLI (Moonshot)
+
+- Origin: [MoonshotAI/Kimi-CLI](https://github.com/MoonshotAI/Kimi-CLI) — Moonshot's
+  coding agent CLI for Kimi models; also source for the K2 agent-harness lessons in
+  [the Kimi K2 technical report](https://github.com/MoonshotAI/Kimi-K2/blob/main/tech_report.md)
+  (agent-related: tool design, agentic data pipeline, prompt formats — offline read).
+- Local clone: `external/kimi-cli` (30 MB, Python + Bun packages). **Note: neuron
+  shipped archived** — `packages/kosong/README.md:3-5` states the package (and the
+  Kimi CLI monorepo) is no longer maintained; PyPI versions remain. Treat as a
+  historical design point, not a living one.
+- Why studied: they report agent-capability numbers from harness choices
+  (tool-call reliability, cross-platform behavior), and their harness is young —
+  a good contrast to opencode/dsh maturity.
+
+## Verified layout
+
+**Archived, no longer maintained** — `external/kimi-cli/packages/kosong/README.md:3-5`
+states the Kimi CLI monorepo is archived; kosong itself ("LLM abstraction layer:
+unified messages, async tool orchestration, pluggable providers", `README.md:9-10`)
+remains published on PyPI.
+- `packages/`: `kaos`, `kimi-code`, `kosong` — names suggest an OS-abstraction
+  layer (kaos), the coding product (kimi-code), and a core/primitive crate
+  (kosong). Verify.
+- `klips/`, `sdks/`, `examples/`, `docs/`.
+
+## Map to arms (pending verification per claim)
+
+- Arm 02 (tools): kosong primitives (tool call protocol), shell/file tools.
+- Arm 08 (execution): kaos (platform abstraction — include zsh/POSIX-specific
+  behavior matrices from their reports).
+- Arm 01 (prompt): kimi-code's prompt assembly; system prompt size/variants.
+- Arm 03 (subagents): verify — does kimi-cli have subagents or just parallel
+  tools?
+- Arm 09 (observability): `klips`/vis.
+
+## Open questions for the audit
+
+1. What is kosong's tool interface, and does it version tool schemas?
+2. kaos: which OS differences do they encode (Windows/macOS sandbox quirks)?
+3. How does the CLI do cost/usage accounting and context tracking?
+4. Tech report: what harness decisions do they credit for SWE-bench/ToolBench
+   deltas —tool granularity, prompting, or sandboxing?

package/docs/study/sources/omp.md

@@ -0,0 +1,93 @@
+# Source: oh-my-pi (omp) — the open tuning of pi
+
+- Origin: [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi); a fork of
+  [badlogic/pi-mono](https://github.com/badlogic/pi-mono) by @mariozechner. This
+  harness family's Pi session runtime is upstream pi; omp is the sharpened sibling.
+- Local clone: `external/omp` (907 MB incl. assets/Bazel).
+- Status: **arm-01 verified in person; arms 02–06 audited** (explorer report;
+  my spot-check of `date-cwd-reminder.ts` done).
+
+## Verified layout
+
+Rust crates (`crates/`): `pi-ast`, `pi-builtins`, `pi-diff`, `pi-edit`, `pi-iso`,
+`pi-natives`, `pi-predict`, `pi-shell`, `pi-vcs`, `pi-vfs`, `pi-voice`,
+`pi-walker`. Bun/TS packages: `coding-agent` (the surface), `metaharness`,
+`mnemopi`, `snapcompact`, `agent`, `stats`, `tui`, `wire`, `catalog`.
+
+## Core facts per arm (audited)
+
+**02 tools.** 30 built-in tool names as a const list
+(`packages/coding-agent/src/tools/builtin-names.ts:1-32`) + 3 hidden
+(`think/yield/goal`, `:36`; root README's "31" claim disagrees — unverified).
+`createTools` resolves/constructs/registers into `session.toolRegistry`
+(`.../tools/index.ts:554-591,831-861`); settings gate each tool
+(`:96-105`). Tool definition is rich: `AgentTool` extends `Tool` with label,
+TypeBox parameters, execute, renderCall/renderResult hooks, an **approval tier
+declaration** (read|write|exec, exec default), `loadMode` essential/discoverable,
+`docTopics` (`xd://` links), per-call concurrency (shared/exclusive), and
+speculation policy (`packages/agent/src/types.ts:1129-1243`). Descriptions are
+rendered from static `.md` templates via a dynamic getter (`.../tools/read.ts:975-996`).
+Tool prompts never inline (`AGENTS.md` "Prompts never in code"). Rust side:
+`pi-natives` = PTY/grep/diff/EditStore/snapcompact.rs bindings;
+`pi-edit` = patch engine; `pi-shell` = in-process bash host **with vendored
+uutils coretools (`pi-builtins`) — a real Unix environment**; `pi-edit`+`pi-shell`
+compose the editing/shell backbone
+(`crates/pi-shell/Cargo.toml:18`; `crates/pi-builtins/src/`). MCP: `mcp__<server>_<tool>`
+names, 64-char cap, deduped transforms before registry reconciliation
+(`.../mcp/tool-bridge.ts:428,468-491`; `session/session-tools.ts:2231-2264`).
+
+**Gate (02/07).** Tier × policy per tool: user-overridable `allow|deny|prompt`
+per tool; modes `always-ask | write | yolo`; missing context **fails closed**
+to always-ask (`.../tools/approval.ts:17-18,53-84,100`). Extension hooks wrap
+every call (`extensibility/hooks/tool-wrapper.ts`).
+
+**03 subagents.** The `task` tool; agent definitions discovered from bundled +
+`~/.omp/agent/agents/*.md` + `.omp/agents/*.md` (`.../task/index.ts:4-10`,
+`task/discovery.ts`). `SpawnRun` holds a semaphore permit, streams progress,
+adopted by the owner on abort/binding (`task/spawn-run.ts:1-9,47-88`);
+**speculative launch** starts children while the `tasks[]` arguments are still
+streaming (`task/speculative-launch.ts`). Isolation: pinned child settings,
+advisor forced off, **mid-turn compaction forced on** (whole assignment = one
+turn), isolated runs get their own **worktree** and may not expose roots outside
+it (`task/executor.ts:1132,4033-4055,4339`; `docs/compaction.md:76`). Structured
+children always get `yield`; depth-limited recursion (`task/index.ts:45`).
+`autoresearch` is a hillclimb/eval loop with dashboard + own git branch — no
+spawn refs found (**unverified** whether it uses task).
+
+**05 context.** Compaction triggers post-turn above
+`resolveThresholdTokens`, mid-turn before requests, idle, and on
+overflow-recovery (`.../session/session-maintenance.ts:626,2147,2246,2412`).
+`compaction.methodOrder` strategy ladder: LLM summarize (regular/handoff), `shake`
+(local mechanical elision to `artifact://` refs), `snapcompact`
+(`docs/compaction.md:202-215`). **Snapcompact = deterministic, no LLM**:
+discarded history serialized with caps into provider-aware PNG bitmaps
+(fonts per provider family), persisted and re-attached each rebuild
+(`packages/snapcompact/README.md:3-29,44-68`). Sizing: archive gets half the
+headroom; kept context ≤ 60% of threshold, target ≤ 80%
+(`docs/compaction.md:217,221`). Cache care: pruned outputs blanked only within
+the model's `prompt-cache-lookback` bound (`docs/compaction.md:248`); summary
+drops whole call/result pairs (`:250`); **byte-stable system prompt between
+turns is a session invariant** (`session/agent-session.ts:2607`).
+`compress/` is unrelated — a separate "dense prompt register" rewriter
+(`compress/index.ts:2-11`).
+
+**06 memory.** Five `memory.backend` modes: off | local | hindsight | mnemopi |
+sharpshooter (`docs/memory.md:3-11`). Injection = Memory Guidance block at
+session start from a project summary; outputs are per-project `MEMORY.md` +
+lessons + `skills/` on disk. Pipeline: startup background job, two phases
+(per-session extraction → global consolidation with lease+heartbeat; skipped
+for subagents), SQLite job queues (`memories/index.ts:29-67`; `docs/memory.md:74-89`).
+Injection budget shares 5000 tokens (summary+lessons, `docs/memory.md:132`);
+`learn` lessons capped 100 × 2000 chars and redacted (`docs/memory.md:70`).
+`hindsight` = remote vector service; recall on first turn, auto-retain every N
+turns (`hindsight/state.ts:385-388`). `mnemopi` = local SQLite working/episodic
+engine + `memory://` read protocol; user-facing tools `recall/retain/reflect/
+memory_edit` (`packages/mnemopi/README.md:5-8`; `docs/memory.md:34-46`).
+Written on minutes/days cadence — not immediately at task end.
+
+**07–09 briefs.** `judgment/` resolves a Judge model role for typed judgments
+(`judgment/index.ts:1-10`); `capability/` is the provider/extension loading
+registry. Execution: inside-process unix env via pi-shell, always
+non-interactive env (pagers off, TERM=dumb) (`exec/non-interactive-env.ts:6-25`);
+no OS-level sandbox located (**unverified**). `omp stats` = local usage
+dashboard, live ingest, port 3847 (`packages/stats/README.md:3,9,31-35`).

package/docs/study/sources/opencode.md

@@ -0,0 +1,43 @@
+# Source: opencode
+
+- Origin: [sst/opencode](https://github.com/sst/opencode), the coding agent this
+  harness family uses day-to-day. TypeScript/Bun monorepo.
+- Local clone: `external/opencode` (shallow, cloned 2026-10-21).
+- Why studied as an anchor: battle-tested open harness; this harness already borrows
+  its mental model of sessions/agents/tools, so deltas are cheap to evaluate.
+
+## Verified layout
+
+- `packages/core/src/` — the harness core. Observed top-level: `agent.ts`,
+  `permission.ts`, `mcp.ts`, `filesystem.ts`, `instructions` dir,
+  `instruction-discovery.ts`, `compaction`? (not yet verified below alphabet
+  cut), `codemode/`, `config/`, `event-logger.ts`, `persistent-pty.ts`,
+  `models-dev/`, `job.ts`, `kv.ts`.
+- `packages/` of interest beyond core: `agent`, `cli`, `plugin`,
+  `plugin-browser`, `plugins`, `server`, `session-ui`, `tui`, `codemode`,
+  `httpapi-codegen`, `protocol`, `sdk`.
+- AGENTS.md at repo root states their engineering expectations.
+
+## Map to arms (pending verification per claim)
+
+- Arm 01 (prompt): `instructions/`, `instruction-discovery` — AGENTS.md-style
+  instruction discovery; ayurveda of stable/dynamic sections unknown.
+- Arm 02 (tools): built-in tool set + MCP (`mcp.ts`) + tool providers via plugins.
+- Arm 03 (subagents): `agent.ts` — primary/secondary agents by description.
+- Arm 04 (skills): plugins and community plugins; the `plugins/` package.
+- Arm 05 (context): compaction (verify location), message queueing.
+- Arm 06 (memory): no first-class memory beyond instructions; community plugins.
+- Arm 07 (governance): `permission.ts` — permission model, per-tool approval modes.
+- Arm 08 (execution): `persistent-pty.ts`, `terminal/` package, containers package.
+- Arm 09 (observability): `event-logger.ts`, events bus (`bus.ts`), TUI
+  trajectories.
+
+## Open questions for the audit
+
+1. Where is the session system prompt assembled, and is any of it cache-stable?
+2. How do tool descriptions reach the model: generated, hardcoded, or provider
+   overridable?
+3. What compaction exists in core, and is it triggered in-band?
+4. How does the permission model express "always/deny/ask" per tool and per
+   pattern?
+5. What do plugin tool providers get access to (context object shape)?

package/docs/study/sources/openhands.md

@@ -0,0 +1,46 @@
+# Source: OpenHands (All Hands AI)
+
+- Origin: [All-Hands-AI/OpenHands](https://github.com/All-Hands-AI/OpenHands) is now
+  the **Agent Canvas frontend** (TypeScript UI + backend orchestration); the agent
+  runtime itself lives in the [OpenHands/software-agent-sdk](https://github.com/OpenHands/software-agent-sdk)
+  (`openhands-sdk`, `openhands-agent-server`, `openhands-tools`,
+  `openhands-workspace`). README: each conversation runs in its own Docker
+  container with its own Agent Server and tools; Agent Server is a REST API on a
+  host/port.
+- Local clones: `external/openhands` (41 MB UI/orchestration) and
+  `external/openhands-agent-sdk` (runtime).
+- Why studied: the most productized open harness — UI, server, containers,
+  scheduling, and a clean agent/skill/microagent story in Python.
+
+## Verified layout
+
+- `external/openhands-agent-sdk/`: `openhands-sdk/` (agent, tools, llm, events),
+  `openhands-agent-server/`, `openhands-tools/`, `openhands-workspace/`,
+  `clients/`. (Deeper inventory pending.)
+- `external/openhands/src/`: React app (`routes`, `stores`, `services`,
+  `extensions`, `hooks`).
+
+## Map to arms (pending verification per claim)
+
+- Arm 03 (subagents): SDK agents + Agent Server's conversation-per-container
+  isolation; scheduling via the separate `automation` repo.
+- Arm 04 (skills): SDK's skill/microagent model (condenser? verify) — historically
+  "microagents" from `.openhands/` folders.
+- Arm 05 (context): SDK condensation pipeline (researched: LLM-based
+  condensers) — worth auditing closely; this harness has explicit opinions here.
+- Arm 06 (memory): microagents + per-agent state in SDK; frontend `library/`?
+- Arm 07 (governance): server-side confirmation policy, sandboxed exec, security
+  modes.
+- Arm 08 (execution): workspace containers, per-conversation isolation.
+- Arm 09 (observability): event stream persisted per conversation; frontend
+  trajectory UI.
+
+## Open questions for the audit
+
+1. SDK `openhands-sdk/`: how are tools, skills, agents wired — what is the
+   `llm.py` ↔ tool schema path?
+2. Condensers: which ones exist, when triggered, how events are rewritten — does
+   it preserve caching/prefix stability?
+3. What does the Agent Server persist per conversation (format, retention).
+4. How do microagents differ from skills (trigger on file/mention vs on-demand)?
+5. Where does the UI fit in governance (approval UI) vs server-side `ToolPolicy`.

package/docs/study/sources/smolagents.md

@@ -0,0 +1,40 @@
+# Source: smolagents (HF CodeAct)
+
+- Origin: [huggingface/smolagents](https://github.com/huggingface/smolagents) —
+  the CodeAct lineage: the model writes Python action code instead of JSON tool
+  calls ("simple = true"). Paper: *CodeAct* (arXiv:2402.01030, executable-code
+  actions outperform JSON); smolagents docs echo it.
+- Local clone: `external/smolagents` (4.3 MB, Python; smallest source here).
+- Why studied: the sharpest *alternative* to JSON tool calls — code-as-action
+  changes every arm at once (tools, context, memory, governance).
+
+## Verified layout
+
+`src/smolagents/`: `agents.py`, `memory.py`, `tools.py`, `default_tools.py`,
+`prompts/`, `local_python_executor.py`, `models.py`, `mcp_client.py`,
+`tool_validation.py`, `_function_type_hints_utils.py`, `serialization.py`,
+`monitoring.py`, `gradio_ui.py`, `vision_web_browser.py`, `remote_executors.py`.
+
+## Map to arms (pending verification per claim)
+
+- Arm 02 (tools): `tools.py` + `@tool` decorator + `tool_validation.py` — tool =
+  Python function w/ schema from type hints; `default_tools.py` set.
+- Arm 08+02 (code-as-action): `local_python_executor.py`, `remote_executors.py`
+  (sandbox: local interception vs E2B etc.), `sandbox resolution`.
+- Arm 05 (context): `memory.py` — the agent's step memory structure (planning
+  steps, tool logs); re-writable by design.
+- Arm 01 (prompt): `prompts/` templates incl. system prompt for CodeAct loops,
+  planning prompts.
+- Arm 09 (observability): `monitoring.py`, `gradio_ui.py`.
+- Arm 02-interop: `mcp_client.py` — MCP tools bridged into code actions.
+
+## Open questions for the audit
+
+1. How is memory.py structured (system prompt + zipped action log) and what does
+   the model re-see each step?
+2. What does the local executor intercept (imports? outputs?) and how does the
+   sandbox story compare with `RefineHost` probe isolation?
+3. How do MCP tools become callable from generated code — namespace injection?
+4. What is definitely not adoptable here (this harness has a strict tool-gate model;
+   free code execution is anathema), yet may translate as *internal* code actions
+   (cf. opencode codemode, dsh ptc-runtime)?

package/docs/study/sources/swe-agent.md

@@ -0,0 +1,34 @@
+# Source: SWE-agent
+
+- Origin: [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) (formerly
+  princeton-nlp), research framework whose thesis is that *the environment
+  interface is the model's feature surface*: IC = Agent–Computer Interface design.
+- Local clone: `external/swe-agent` (65 MB, Python).
+- Why studied: the clearest published statement of "tools + interface shape
+  agent success" (arXiv:2405.15793); benchmark-native harness (SWE-bench).
+
+## Verified layout
+
+- `sweagent/`: `agent/`, `environment/`, `run/`, `tools/`, `inspector/`,
+  `exceptions.py`, `types.py`, `utils/`.
+- `tools/` at repo root: tool bundles (separate package). `config/`: agent configs
+  (YAML per model). `trajectories/`: run artifacts in-tree. `mkdocs.yml` + `docs/`.
+
+## Map to arms (pending verification per claim)
+
+- Arm 02 (tools): tool bundles (`tools/`), command-parsing interface state
+  (`agent/`), explicit "no dangerous commands" curation lists.
+- Arm 01 (prompt): `config/` YAML templates + `sweagent/agent/` template
+  variables.
+- Arm 08 (execution): `sweagent/environment/` — containerized bash sandboxes.
+- Arm 09 (observability): `trajectories/` + `inspector/` — offline trajectory
+  viewer.
+
+## Open questions for the audit
+
+1. How much of their gain came from interface design (evidence in paper §)?
+2. How are tool bundles declared/loaded, and what is their gate story?
+3. Is there anything analogous to compaction (their runs are bounded) — or do they
+   rely on truncation and restarts?
+4. What is worth copying given they optimize for single-shot benchmark runs, not
+   interactive use?