@xingular/harness 0.1.6 → 1.0.0

package/docs/releases/1.0.0.md

@@ -0,0 +1,40 @@
+# Xingular Harness 1.0.0
+
+This release establishes @xingular/harness@1.0.0 as the stable baseline and retains the xharness
+command. It intentionally resets the earlier development numbering; historical tags and published
+versions remain unchanged. This document describes the candidate until registry publication is
+verified.
+
+## Included
+
+- Pi execution with isolated accounts, pinned models/capabilities, gated tools and recorded usage.
+- Foundation/variant architecture, validated c1–c8 variants, version history, continuation,
+  answer-free refinement and opt-in lessons.
+- Wiki notes, history/trajectory tools, MCP connectors, plugins, Hub installation and terminal UI.
+- Generic web search/fetch and isolated browser tools, plus account and backend diagnostics in
+  /doctor. Local inspection is the default; selected live probes require consent.
+- Compiled Node ESM SDK and TypeScript declarations, including supported subpath imports.
+- Apache-2.0 for original project code, with retained upstream attribution and license texts.
+
+## Installation and requirements
+
+Use `npm install --global @xingular/harness@1.0.0`, then `xharness`. Node 22.19 or later is required.
+The terminal additionally requires Bun; release CI uses Node 22.19.0 and Bun 1.4.2. Browser operation
+requires an installed compatible browser or a deliberately configured endpoint. Model credentials
+are configured inside an isolated Harness account.
+
+## Migration
+
+- SDK tree symbols/paths become variant symbols/paths: VariantChoice, seedVariant, variant/*.
+- Server harnesses.* methods become variants.*. Session/context inputs use variant; variant
+  snapshots use variant and materialisation returns files. Old method aliases are not provided.
+- Existing stored data is migrated without overwriting; historical run records remain readable.
+- Versions numerically above 1.0.0 will not receive this release through higher-major semver ranges.
+  Install the exact version or latest tag deliberately.
+
+## Diagnostics limitations
+
+Local readiness is not live connectivity. Doctor never signs in, switches accounts or repairs
+settings. Provider probes may incur charges. Computer input remains blocked when the embedding
+host cannot provide an isolated diagnostic surface. Runtime execution and compiled artifacts are
+validated independently from publication; see the release checklist for actual gate results.

package/docs/releases/README.md

@@ -0,0 +1,36 @@
+# Release procedure
+
+1. Review and commit completed Harness changes on release/1.0.0. Review App compatibility changes
+   separately. Preserve old tags and exclude outputs, external references and caches.
+2. Run npm run ci and the required App checks on unrestricted macOS/Linux runners. Install Bun
+   1.4.2 and use Node 22.19.0 for the release build. Do not waive failing checks.
+3. Run npm run release:pack. The unique output folder contains the candidate tarball, inventory,
+   SHA-256 checksum and npm integrity. Run npm run release:smoke -- <tarball> --terminal for a fresh
+   dependency installation and packaged SDK/server/terminal checks. --offline reuses the checkout's
+   installed dependency tree and is only a local smoke check, not fresh-install acceptance.
+4. Run npm run release:preflight. Verify npm scope ownership and trusted-publisher settings for
+   tanntnny/xingular-harness, workflow release.yml, direct publishing enabled. No login is started
+   automatically. Existing 1.0.0 or an unreachable registry blocks publication.
+5. Present the exact commit, candidate inventory/hash, notes and check results for approval. Pushing
+   v1.0.0 triggers publication; do not push the tag before this approval. Preserve historical tags.
+6. After approval, push the reviewed commits and tag. The workflow runs both OS checks, packages
+   and tests one candidate, then publishes that same tarball with OIDC provenance and --tag latest.
+   No local publishing token is needed. It verifies registry integrity/provenance and creates a
+   GitHub release. Inspect registry state before retrying any failed publication.
+
+A published version cannot be replaced. Corrections require a later version. This package's
+intentional 1.0.0 reset does not rewrite historical decisions or claim an ordering above older
+2.x–5.x development versions. Publication status and local evidence belong in the candidate report.
+
+## Current preparation evidence
+
+Local package inspection and the offline-dependency consumer smoke check pass. App compatibility
+checks pass (592 renderer tests, 40 sidecar tests, 240 Rust tests with one ignored, and type/layer/UI
+checks). A focused Harness run has 100 passing tests and the standalone proof passes. The full
+Harness run is blocked by sandbox IPC and native HEIC encoding restrictions. The public GitHub
+repository and absence of a remote v1.0.0 tag were verified through the connected GitHub service.
+The npm registry and trusted-publisher settings could not be verified from this environment.
+
+The release branch must run unrestricted CI and a fresh-install smoke check before a release-tag
+approval is requested. Branch upload itself is a separate approval because it shares the source
+with GitHub and starts CI; it does not publish npm. No local test failure is waived by this note.

package/docs/study/00-index.md

@@ -0,0 +1,78 @@
+# Harness arm study — index
+
+An audit of agent-harness designs, arm by arm: where each studied harness puts its
+prompt assembly, tools, memory, subagents, skills, context management, refinement,
+governance, execution and observability, and what to adopt into this harness.
+
+Positioning: this is analysis, not checked source behavior. Living contract docs and
+decisions stay in `docs/`; when a study produces an actual change here, an ADR is
+written and the claim moves to checked behavior. Cite material as
+`external/<name>/<path>:<line>` — never second-hand summaries.
+
+## Focused notes
+
+- [`/btw` side-question comparison](btw-comparison.md) — this terminal, the App-owned
+  side question, and checked-out external implementations.
+- [Harness feature-gap review](feature-gap-review.md) — task/goal management, long-running work,
+  memory, execution isolation, verification, and observability gaps against the studied peers.
+
+## Sources
+
+Clones live in `external/` (this repo). Field notes in `sources/`.
+
+| Source | Origin | Note | Stage |
+|---|---|---|---|
+| opencode | [sst/opencode](https://github.com/sst/opencode) — TypeScript, the tool this harness family runs sessions in | [opencode.md](sources/opencode.md) | arm-01 audited |
+| pi / omp | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) — tuned fork of [pi-mono](https://github.com/badlogic/pi-mono), the session runtime underneath this harness | [omp.md](sources/omp.md) | arm-01 audited |
+| deepseek-harness (`dsh`) | [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — MIT, Cordis, "everything is a plugin" | [deepseek-harness.md](sources/deepseek-harness.md) | arm-01 audited |
+| harness2 | [google-research/harness2](https://github.com/google-research/harness2) + paper *Harness²: Recursive Agent Harnessing for an Open World* (arXiv:2610.14224, PDF in the clone) | [harness2.md](sources/harness2.md) | arm-01 audited |
+| swe-agent | [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) | [swe-agent.md](sources/swe-agent.md) | inventory |
+| openhands | [All-Hands-AI/OpenHands](https://github.com/All-Hands-AI/OpenHands) (UI) + [OpenHands/software-agent-sdk](https://github.com/OpenHands/software-agent-sdk) (agent server runtime) | [openhands.md](sources/openhands.md) | inventory |
+| kimi-cli | [MoonshotAI/Kimi-CLI](https://github.com/MoonshotAI/Kimi-CLI) | [kimi-cli.md](sources/kimi-cli.md) | inventory |
+| smolagents | [huggingface/smolagents](https://github.com/huggingface/smolagents) — CodeAct | [smolagents.md](sources/smolagents.md) | inventory |
+| claude-code | [Anthropic Claude Code](https://www.anthropic.com/claude-code) — not open source; audit npm bundle, published prompts, observed behavior | [claude-code.md](sources/claude-code.md) | no clone |
+
+## Arms
+
+One doc per arm: *design space → per-source comparison → trade-offs → adoption
+candidates*. Adoption candidates feed a two-tier roadmap: Tier 1 = patterns already
+battle-tested in open harnesses (OpenCode / pi / dsh); Tier 2 = research-backed ideas
+(harness² and the literature) attempted after Tier 1.
+
+| # | Arm | Doc | Stage |
+|---|---|---|---|
+| 1 | System prompt / context assembly | [arms/01-system-prompt.md](arms/01-system-prompt.md) | core four audited (opencode, omp, dsh, harness²); 5 sources pending |
+| 2 | Tools | [arms/02-tools.md](arms/02-tools.md) | core four audited (opencode, omp, dsh + harness²/swe-agent/smolagents in person); partial |
+| 4 | Subagents | [arms/03-subagents.md](arms/03-subagents.md) | core four audited; openhands/claude-code pending |
+| 5 | Skills & loading | [arms/04-skills.md](arms/04-skills.md) | three sources audited (dsh, opencode, harness²) + our tree; omp partial |
+| 6 | Context management | [arms/05-context-management.md](arms/05-context-management.md) | core three audited; ours needs inventory |
+| 3 | Memory | [arms/06-memory.md](arms/06-memory.md) | core four audited + our Wiki |
+| 8 | Governance | [arms/07-governance.md](arms/07-governance.md) | core three audited; claude-code/openhands pending |
+| 9 | Execution | [arms/08-execution.md](arms/08-execution.md) | core three audited; hands pending |
+| 10 | Observability | [arms/09-observability.md](arms/09-observability.md) | core three audited; hands pending |
+| 7 | Refinement / self-improvement | [arms/10-refinement.md](arms/10-refinement.md) | **done in person — port confirmed**; judge delta + drift sync open |
+
+Wide comparison: [arms/00-matrix.md](arms/00-matrix.md). Standing conclusions:
+[insights.md](insights.md). Roadmap: [roadmap.md](roadmap.md).
+
+## Work order
+
+1. `sources/` inventories (all nine), then arms 01–02 (prompt, tools)
+2. Arms 03–06 (subagents, skills, context management, memory)
+3. Arms 07–09 (governance, execution, observability)
+4. Arm 10 (refinement ⭐ — the merge study against harness²) + `roadmap.md`
+5. `arms/00-matrix.md` last, from the finished arm docs
+
+## Method rules
+
+- **Ground truth first.** Read the code before forming a position; every claim in an
+  arm doc needs at least one `path:line` citation per source, or an explicit
+  "unverified".
+- **Describe, then judge.** The comparison table states what each harness does; the
+  trade-off section says why; only `adoption candidates` mentions this harness.
+- **Respect the boundary.** Nothing here changes `src/`; study docs name no product
+  concept that the harness would learn. Adoption goes through the extension-point
+  flow later.
+- **The anchor arms are the seven surfaces.** Prompt sections, tool providers,
+  `ToolPolicy`, `SecretStore`, `Directory`, plugin descriptions, `RefineHost` — map
+  foreign mechanisms onto these without inventing application concepts.

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 |