@xingular/harness 0.1.7 → 1.0.0

package/docs/study/arms/00-matrix.md

@@ -0,0 +1,20 @@
+# Wide comparison matrix
+
+One row per source per arm; ≤12 words per cell, verbs first. Detail and
+citations live in the arm docs; this page is an index, not the analysis.
+
+| Arm | this harness | opencode | omp (pi fork) | dsh | harness² | swe-agent | openhands SDK | kimi-cli | smolagents | claude-code |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 01 prompt | compile.ts only; stable prefix + hidden context updates | template + deltas appended to history | parallel compiler; two-block cache; static invariant | ordered per-step sections + user snapshot | tree IS prompt, capped always-on | yaml config templates | pending | pending | step-log replay | CLAUDE.md hierarchy (pending) |
+| 02 tools | providers + per-call gate; `{product}` | Effect plugins, codemode, MCP names | 30 rich builtin tools, tiers | defineTool registry, PTC mode | editable c4 guidance | YAML string bundles | pending | kosong abstract layer (archived) | code actions, @tool | descriptions answer how (pending) |
+| 03 subagents | fresh run children + delivery receipts | subagent tool, fresh sessions, description route | task tool, worktree isolation, speculative | spawn/fork service, continuable | c5 own-context text agents | runs only | per-container opens | pending | none in-source | agents files (pending) |
+| 04 skills | c6 tree skills, trust-gated loader | depth-6 scan, skill lazy-load | manage_skill; memory writes skills | durable capped catalog + skill tool | trigger lines validated | procedures via bundles | microagents (pending) | klips dir | prompt templates | SKILL.md (pending) |
+| 05 context | context message + budgets | compaction agent, fixed template, verbatim tail | method ladder, snapcompact deterministic | formula trigger, prune first, FTS5 query | replica-era limits, trim-to-pay | bounded single shots | condensers pending | pending | full replay memory | auto-compact (pending) |
+| 06 memory | wiki notes on file writes; guarded refine lane | none visible | 5 backends, two-phase consolidation, MEMORY.md | durability only: spill/todo/deliverables | per-domain experience library | none | pending | pending | step log | memory files (pending) |
+| 07 governance | gate last; standing + single-use | per-leaf asserts, always/deny/ask | tier×policy, fails closed | pre-execute pipeline + guard | substrate-dependent | curated blocklists | confirmation policy | archived | executor = gate | permission modes (pending) |
+| 08 execution | account-isolated sessions; host PTY | shell tool + separate pty daemon | in-process rust unix env | sandbox classes + single executor | substrate workspace | container env | workspace containers | kaos (archived) | intercepted exec | desktop app (pending) |
+| 09 observability | runStore-only validated events | bus + UsageRecorded | stats dashboard + ledgers | OTel transport only, FEEDBACK_ONLY | runmark + reports | trajectories + inspector | event stream | klips vis | monitor.py | sentry optional |
+| 10 refinement | ported harness² core (arm 10) | none | autoresearch hillclimb loop | none found | editor→probe→compose + reflector | IC design lessons | none found | archived | none | plan mode only |
+
+Fill rule for later passes: replace `pending` from each source note's audit;
+mark archived designs and reference the note.

package/docs/study/arms/01-system-prompt.md

@@ -0,0 +1,211 @@
+# Arm 01 — System prompt / context assembly
+
+Status: **core four audited** (opencode, omp, dsh, harness²); swe-agent,
+openhands, kimi-cli, smolagents, claude-code pending.
+Sources audited by explorer agents with citations; my own spot-checks marked.
+
+Shape: design space → per-source comparison → trade-offs → adoption candidates.
+
+## 1. Design space
+
+Where the model's instructions come from when a session starts, and how they
+evolve mid-session. Sub-decisions:
+
+1. **Assembly location** — one compiler, a grid-like assembler, or a template
+   engine? Who is *allowed* to contribute (core only, plugins, file discovery)?
+2. **Static vs dynamic** — what is identical across calls of a session (or across
+   sessions, for cross-session cache) vs what must be refreshed; and *where* each
+   is injected (system message at node 0, later system messages, user messages
+   after history, synthetic messages inside history).
+3. **Reach of instructions** — always-on prose vs skills vs hooks vs scripts;
+   caps and budget language.
+4. **Cache discipline** — prefix stability, cache breakpoints, proactive
+   warming, append-only updates.
+5. **Editability/versioning** — how the tree of instruction files is versioned
+   or validated (this harness: never edit, only supersede).
+
+## 2. Comparison
+
+### this harness (reference point)
+
+- The prompt is assembled only in `src/prompt/compile.ts`; sessions launch with a
+  stable system prefix plus a hidden `xingular-context` message appended to
+  native history for changing state (repo rules; `AGENTS.md`). Tree sections
+  c1–c8 are versioned; c1–c4 always-on and capped/validated (`tree/tree.ts`);
+  a version is never edited, only superseded (`tree/store.ts`).
+
+### opencode — compiler + instruction deltas
+
+- Small text template with a tool-guidance placeholder, rendered per tool list
+  (`external/opencode/packages/core/src/session/system-prompt.ts:9-27`; the
+  template is `session/runner/prompt/system.txt`).
+- Per-step transcript: system = agent template **plus an instruction baseline as
+  a second system part**; messages = history (`.../session/model-request.ts:99-119`).
+- Instruction sources composed in a fixed order (codemode catalog, MCP,
+  references, skills, AGENTS.md discovery, builtins, API entries) with a comment
+  stating the order keeps "a reusable prompt-cache prefix"
+  (`.../session/context.ts:137-166`, comment at 152-154).
+- Dynamic updates are **appended as system messages after history, before the
+  new user prompt**: AGENTS.md changes render as a unidiff patch or a full
+  rewrite; date/env/codeMode changes likewise (`.../session/generate.ts:53-57`,
+  `.../session/instruction-discovery.ts:127-149`, `.../session/builtins.ts:30-52`).
+- Discovery: global file, ancestor walk, configured globs/URLs, watcher-driven
+  reload; **no size caps found** in the discovered files (auditor: unverified
+  beyond those files) (`.../config/plugin/instruction.ts:51-62,143-225`).
+- On-demand AGENTS.md: the `read` tool injects ancestors as synthetic history
+  messages deduped by metadata (`.../tool/plugin/read.ts:82-104` →
+  `.../session/instructions.ts:74-79`).
+- Cache hygiene: stable `promptCacheKey` from session affinity
+  (`.../model-request.ts:294-295`), tool definitions kept on the final step to
+  preserve the prefix (`.../runner/llm.ts:237`), prefix-stable image elision
+  (`.../model-request.ts:199-207`).
+- Plugins get a per-request hook over `system`, `messages`, `tools`, `options`,
+  with tool-identity matching to prevent hook-invented tools
+  (`.../model-request.ts:236-320`, `packages/plugin/src/effect/session.ts:25-36`).
+
+### omp (oh-my-pi) — parallel compiler with deadlines, two-block cache
+
+- `buildSystemPrompt` fans out **timed, parallel** preparation (project context
+  files, skills, workspace tree, active-repo context, personality; each with a
+  deadline fallback) (`external/omp/packages/coding-agent/src/system-prompt.ts:630,723-848,954-1009`).
+- All prompt text lives in `.md` Handlebars templates, imported `{type:"text"}` —
+  repo rule "Prompts never in code"
+  (`.../system-prompt.ts:24-31`, `.../prompts/system/system-prompt.md`).
+- **Stable prefix is a separate entry**: the default body renders as block 0;
+  `<project-context>` is appended as a *second prompt entry* so the static
+  prefix is shared across directories — with the comment that the Anthropic head
+  cache breakpoint lands right before it (`.../system-prompt.ts:1026-1036`).
+- **Volatile content (date/cwd) was deliberately moved out of the system
+  prompt** because it "invalidated the whole tool array"; now injected onto the
+  first user turn per request, append-only, with a synthetic developer turn when
+  no new user turn exists (`.../session/date-cwd-reminder.ts:1-11,50-129`;
+  wired at `.../sdk.ts:4333-4340`).
+  **Verified in person**: `.../date-cwd-reminder.ts:1-12` — header comment states
+  the reason (open-weight chat templates render tool schemas *after* system
+  content, so a volatile tail invalidates the whole tool array), and lines 44-48
+  guarantee append-only injection: changed values attach to a newly appended
+  user turn, leaving every earlier message byte-identical.
+- Instructions arrive via a **capability API**, not hard-coding:
+  `contextFileCapability` (project AGENTS.md family with dedupe), `systemPromptCapability`
+  (SYSTEM.md override), `instructionCapability` — extensions add content through
+  named slots (`.../capability/context-file.ts:26-56`,
+  `.../capability/system-prompt.ts:31`).
+- Cache: `CacheWarmer` replays requests at ~90% of cache lifetime when savings
+  clear a floor (`.../session/cache-warmer.ts:1-17`); per-component token
+  usage breakdown (`systemPromptTokens`, `skillsTokens`, …,
+  `.../session/agent-session-types.ts:529-535`); truncating MCP server
+  instructions invalidates the tools cache breakpoint (`.../sdk.ts:1374-1375`).
+- `metaharness` is **not** runtime prompt machinery: it is their benchmark
+  manager (Harbor/SnapCompact experiments over one SQLite store; runner note at
+  `.../packages/metaharness/src/runner.ts:1257-1258`). Their word "harness" in
+  `metaharness` = a harness around the harness, for measurement.
+
+### deepseek-harness (dsh) — ordered sections, snapshot-as-user-message
+
+- Own package `packages/core/system-prompt`; assembled **per step** via an
+  ordered "waterfall" of sections/context entries
+  (`external/deepseek-harness/packages/core/system-prompt/src/index.ts:429,677-680`,
+  `.../agent-loop/src/agent.ts:272,407`).
+- **Plugin contribution contract**: `ctx.systemPrompt.section()`, `.context()`,
+  `.tools(provider)`, `.variable(name, provider)` — sections are sorted by
+  numeric `order` then name, duplicates throw, scoped entries shadow globals,
+  and a `complete: true` section replaces everything else
+  (`.../system-prompt/src/index.ts:53-76,131-179,478-570,653-686`; shadowing
+  tested in `.../system-prompt/tests/scoped.spec.ts:33`).
+- Static = section text at node 0 (identity fixed in code, `index.ts:449-466`);
+  dynamic facts (cwd, sandbox policy, time, plan) are `PromptContext` entries,
+  re-resolved per request and appended as a **durable user-role message**
+  headed "Current runtime context. This snapshot supersedes earlier…"
+  (`.../index.ts:314-318,582-602`, `.../agent-loop/src/agent.ts:411,429-440`).
+- Workspace instructions also inject into history as sourced `user/message`
+  events, not system text (`.../packages/context/agent-instructions/README.md:88-103,158-186`).
+- Tool ordering is part of prompt assembly: providers' tools are `structuredClone`d
+  and ordered by configured `toolOrder` with an `<unlisted-tools>` rest marker
+  (`.../system-prompt/src/index.ts:208-240,633-651,674`).
+- Token metering as a service with fixed-density estimates
+  (`.../packages/llm/token-meter/src/index.ts:4-35`, `estimate.ts:16-27`).
+
+### harness² — the tree is the prompt; caps and economics
+
+- Their editable tree per substrate (here for opencode): `systemprompt.md` (c1),
+  always-on files with caps, skills loaded on demand, subagents in own context,
+  scripts, and a plugin acting inside the tool loop
+  (`external/harness2/harness2/core/prompts.py:424-453`).
+- Always-on prose is framed as an **output-budget** cost: "ALWAYS-ON PROSE IS THE
+  EXPENSIVE OPTION… the most costly failure on this work is a run that reasons
+  until the budget is gone and produces nothing" (`.../prompts.py:129-146,455-458`).
+- Validation discards a whole harness for: a skill without a trigger line naming
+  it in always-on text; template braces in always-on text (Jinja StrictUndefined);
+  a named script that is missing (`.../prompts.py:148-167`,
+  `.../core/tree.py:15-21` — caps, frontmatter rules per `SurfaceSpec`).
+- Notably, their opencode-surface table labels components **c1–c8** — the same
+  eight-component numbering this harness uses (`.../prompts.py:424-431`). Both
+  projects have converged on the same tree taxonomy; treat as confirmation of
+  shape, not shared code.
+- Instruction-bearing text is data, not branches: "Benchmark text arrives as
+  values, never as branches" (`.../prompts.py:15-20`) — prompt templates are
+  parameterized by a `BenchPrompts` value, and each new benchmark gets slots,
+  not edits. Answer-free framing is literally part of the prompt
+  (`ANSWER_FREE`, `.../prompts.py:38-44`).
+
+### claude-code (from public material, no clone) — pending
+
+CLAUDE.md hierarchy + `@` imports + `#` quick-memory; tool descriptions as the
+home of usage guidance. To be filled with dated citations.
+
+### swe-agent / openhands / kimi-cli / smolagents — pending
+
+## 3. Trade-offs
+
+- **Stable prefix vs fresh state.** Everyone converges on stable static +
+  appended dynamic. Two designs for the dynamic: (a) appended *system* messages
+  rendering deltas (opencode), (b) appended *user-role* context snapshot whose
+  text supersedes earlier ones (dsh). (a) is precise (a unidiff names what
+  changed); (b) is simpler and carries whole state per turn, at the cost of
+  re-sending unchanged facts.
+- **Where volatile values live.** omp's lesson is the strongest: even one line
+  of date/cwd inside the system prompt invalidates far more than itself (it
+  invalidated the whole tool-array cache). Moving it into the user turn costs a
+  message but saves the prefix. dsh's snapshot approach (user message) has the
+  same property w.r.t. the system node.
+- **Who may contribute.** Ordered, deterministic contribution with declared
+  order + name ties (dsh) vs deployment-order composition with a cache comment
+  (opencode) vs capability slots with dedupe (omp). The deterministic-order end
+  is friendlier to caching and to reasoning about plugins; the discovery end is
+  friendlier to "just drop a file in the repo" workflows but needs watcher-driven
+  reload and dedupe, and risks unbounded size (opencode has no caps).
+- **Economics of always-on text.** harness² puts the sharpest numbers-language on
+  it: always-on prose competes with output budget; prefer on-demand forms. This
+  matches this harness's capped c1–c4, with the difference that harness² enforces
+  the "cut to pay" rule by validation and this harness by editor review.
+- **Templates in code vs files.** omp keeps every word of prompt text in `.md`
+  templates; harness² inlines exact prompts as Python constants but keeps
+  benchmark text as values; dsh fixes identity prose in the constructor. Pure
+  style until a person wants to review/audit prompt diffs — then files win
+  (reviewable without code knowledge).
+
+## 4. Adoption candidates (Tier 1 unless noted)
+
+| # | Idea | From | Land as | Notes |
+|---|---|---|---|---|
+| A1 | Move volatile date/cwd out of the stable prefix into the first user turn (or the appended context message) | omp `date-cwd-reminder.ts` | prompt sections change in `src/prompt/compile.ts` | **verify our current placement first**; high cache value if our prefix carries date |
+| A2 | Named, ordered prompt sections with deterministic order-name ties and duplicate-name rejection; scoped shadowing | dsh `system-prompt` contract | a rule inside plugin prompt sections (existing surface) | makes section ordering a contract instead of an implementation detail |
+| A3 | Render instruction deltas as unidiff-style "what changed" text in the appended context message | opencode `instruction-state.ts` | the `xingular-context` hidden message mechanism | our channel exists; this is a rendering upgrade |
+| A4 | Proactive cache warming near the provider's cache TTL | omp `cache-warmer.ts` | *not* a harness surface — host/app concern | Tier 2; needs measurement harness first (`probe-chat-cache-app.py` in the App) |
+| A5 | Memory/prompts in reviewable template files rather than inline strings | omp rule | none now — style guidance for future prompt text | Tier 2, low cost, no behavior change |
+
+Carry later: opencode's "no caps on discovered instructions" as an anti-pattern to
+contrast with c1–c4 caps; harness²'s three discard rules (trigger line, no
+template braces, shipped scripts) when tree validation is next touched (arm 04).
+Also carry:
+- **Model-conditioned policy as data.** omp forbids model-conditional branching in
+  code entirely — no `id.includes("claude")`; all model/provider policy lives in a
+  declarative KDL rule tree compiled to `rules.json`
+  (`external/omp/AGENTS.md` — "Model/Provider Policy Lives in KDL"). opencode
+  instead ships per-model prompt adjustments as *plugins*
+  (`external/opencode/packages/plugin/plugin/optimize.ts:16-86` — confirmed by
+  explorer audit). Same problem (per-model prompt/policy deltas), two answers:
+  data tables vs evaluated plugins.
+- omp's **judge-questions convention** — per-feature JSON mapping question ids →
+  `{instructions, criteria?}` — is source material for arm 10 (refinement) and
+  its answer-free selector.

package/docs/study/arms/02-tools.md

@@ -0,0 +1,79 @@
+# Arm 02 — Tools
+
+Status: **core four audited** (opencode, omp, dsh + harness²/tree, smolagents,
+swe-agent in person); kimi-cli archived; claude-code openhands pending.
+
+## Design space
+
+How tools are declared (interface & schema origin), described (who writes the
+model-facing guidance), provided (core vs provider vs plugin vs MCP), named and
+ordered (namespacing, `toolOrder`), gated (tier/policy/event pipeline), and
+whether tools are JSON calls at all — or the model writes code that calls them
+(codemode / PTC / CodeAct).
+
+## 1. Comparison
+
+| Source | Declaration | Gating | Calls |
+|---|---|---|---|
+| this harness | provider extension points; `describeTool` fills `{product}`; definitions in `src/tools/definitions.ts`, dispatch in `src/tools/dispatch.ts` | per-call gate, last extension to see a call | JSON + limited code tool |
+| opencode | internal Effect plugins registering via `ctx.tool.transform(editor.add)`; `Tool.Info{input,execute,output,options{namespace,permission,codemode,pinned}}` | per-leaf `Permission.assert` (`allow\|deny\|ask`, `findLast` wildcard match, default ask; agent rules∪session; missing agent denies) | JSON by default, `codemode:true` folds tools into a code catalog |
+| omp | 30 builtins; rich `AgentTool` (approval tier read\|write\|exec, loadMode, docTopics, per-call concurrency, speculation) | tier × per-tool policy `allow\|deny\|prompt`, modes `always-ask\|write\|yolo`; **fails closed** | JSON; speculative pre-dispatch |
+| dsh | `defineTool` into `ctx.tools`; ToolRuntime self-feeds the system prompt via `.tools(provider)` | fixed pipeline `pre-execute(allow/deny/ask) → ctx.tools.guard() → execute → post-execute → result` | `mode: native` (all schemas) vs `ptc` (model sees only `run_code` + SDK) |
+| harness² | tools = part of the editable tree, c4 tool guidance prose | whatever the agent's substrate does | JSON (substrate tools) |
+| swe-agent | YAML bundles: `signature`/`docstring`/arguments; string parsing; `state_command` for interface state | curated blocklists in bundles | text commands into a stateful shell |
+| smolagents | `@tool` decorated functions, schema from type hints, validated at init | none in-source (executor sandbox is the gate) | **code actions**; MCP tools bridged into code |
+| kimi-cli | kosong async tool-orchestration abstraction (archived) | — | JSON |
+
+Citations: opencode `external/opencode/packages/core/src/tool/plugin/subagent.ts:100-107`,
+`.../tool.ts:161-291,233,293-296`, `.../permission.ts:87-97,158-172`,
+`.../tool/runtime.ts:276-281`, `.../tool/mcp.ts:20-21,52-75`;
+omp `external/omp/packages/agent/src/types.ts:1129-1243`,
+`.../tools/approval.ts:17-18,53-84,100`, `.../tools/builtin-names.ts:1-36`;
+dsh `external/deepseek-harness/packages/core/tools/README.md:30-109`,
+`.../core/tools/src/index.ts:608-612,857,1513-1527`,
+`.../core/system-prompt/README.md:50-52`; swe-agent
+`external/swe-agent/tools/windowed/config.yaml:1-40`; smolagents
+`external/smolagents/src/smolagents/tools.py` (init validation),
+`.../tool_validation.py`.
+
+Instruction-bearing descriptions: opencode embeds whole prose instructions in
+tool descriptions, e.g. the never-poll rule for subagents
+(`.../tool/plugin/subagent.ts:44-47`) and todo's full-file description imported
+verbatim (`.../tool/todowrite.txt`, `.../tool/plugin/todo.ts:12`) — matching
+the claude-code school. omp instead renders descriptions from static `.md`
+templates (`.../tools/read.ts:975-996`; "prompts never in code"). dsh's `ptc`
+moves *all* tool knowledge out of schemas into a generated SDK plus
+`executionInstructions` (`.../core/tools/README.md:68-81`).
+
+## 2. Trade-offs
+
+- **Tool descriptions = prime instruction real estate.** Every source pushes how-to
+  into descriptions; the divergence is *where the text lives*: inline strings
+  (opencode), md templates (omp, self-documenting diffs), schema-erased SDKs (dsh
+  ptc). md templates are cheapest to audit; inline is cheapest to write.
+- **Gate taxonomies.** omp's declared tier × policy is the most legible to users;
+  opencode's per-leaf asserts are the most composable (plugins wrap calls);
+  dsh's pipeline events generalize hooks at the cost of indirection. All three
+  (and ours) converge on `ask` as a first-class outcome that surfaces to a person.
+- **`toolOrder`/namespacing.** dsh validates order config at assembly with a
+  reserved rest margin; opencode mints `server_tool` names with dotted→underscore
+  namespaces; omp caps length at 64. Namespacing rules should be one place; ours
+  has MCP namespaces via the harness's own MCP integration — worth a contract
+  test, not new machinery.
+- **Code-as-action in three strengths.** Full CodeAct (smolagents), opt-out
+  codemode (opencode), mode-switched PTC with SDK (dsh). All reduce schema token
+  cost and multi-call latency, all concentrate risk into the executor. For this
+  harness the gate is per-call and synchronous — free-form code actions are a
+  deliberate non-goal, but `codemode`-style *internal* catalogs remain open
+  behind existing tool providers.
+
+## 3. Adoption candidates
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| A1 | Per-tool **approval tier declaration** (read/write/exec) on the harness ToolSpec; gate consults it when policy is silent | omp `AgentTool.approval` | `ToolPolicy` surface + `src/tools/types.ts` | T1 |
+| A2 | Tool **descriptions from template files** rendered per `{product}` (`.md` in repo, imported `type:"text"`) instead of inline string literals in tool definitions | omp | tool definitions (`src/tools/*`) | T1 |
+| A3 | `toolOrder`-style validated ordering when a caller pins an explicit tool set (fail loudly on unknowns/missing rest-marker) | dsh | capability freezing at `sessions.run` | T2 |
+| A4 | Restrict allow/deny masks scoped to a subexpression that intersect and lift on dispose | dsh `ctx.tools.restrict` | child-run capability narrowing (`capabilities.intersect` already does this — verify equivalence before adding) | T2 verify-first |
+
+Anti-candidates: open-ended code-as-action for model-driven tools (gate model);
+moving gating into per-tool hooks (gate stays the final authority layer).

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 |