@xingular/harness 0.1.7 → 1.1.1

package/docs/parity.md

@@ -0,0 +1,78 @@
+# Capability parity register
+
+**Status:** descriptive register, as of 2026-10-24. The binding rules are
+[14 Surfaces and parity](architecture/14-surfaces-and-parity.md) (`INV-PAR-1`–`INV-PAR-4`).
+
+Every capability a person can use is a Harness capability. The standalone terminal (`xagent`)
+is the reference front end; a host such as the App presents the same capabilities with a richer
+UI. This page lists each capability, where the Harness owns it, how each front end shows it, and
+whether both pass. A gap has an ID (`PAR-NNN`) until it is closed.
+
+Host-only surfaces (presentation a terminal cannot show, `INV-PAR-4`) are not listed here; each
+host keeps its own register. The App's is
+[`App/docs/architecture/app-only-surfaces.md`](../../App/docs/architecture/app-only-surfaces.md).
+
+Status: **parity** (both surfaces pass), **terminal only**, **host only** (a gap), **planned**,
+**host-backed** (needs a host object; terminal fallback named).
+
+## Register
+
+| Capability | Harness owner | Method or tool | Terminal surface | App surface | Status | Gap |
+|---|---|---|---|---|---|---|
+| Sessions and turns | `sessions/` | `sessions.run`, `terminal.*` | the terminal itself | Solo chat | parity | — |
+| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card | plan request, PlanCard | parity | — |
+| Bash command mode | `sessions/sessions.ts` | `initialBashCommand` | `!command` | `!command` in the composer | parity | — |
+| Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock with scroll and copy | side-question dock through the shared service | parity | — |
+| Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
+| Questions (`ask_user`) | `tools/askUser.ts` | `ask_user`; terminal `ask_user_question` | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | parity; terminal projection verified in isolated fixtures | — |
+| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030), `subagents.*` | `/subagents` page and live rows under the status line (mark, profile, parent-set title, `n of m tasks`) | reply trajectory | parity | — |
+| Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete | not shown; `RunRecord.profile` available | terminal done; App planned | PAR-010 |
+| Run checklist | `tools/checklist.ts` | `checklist_write`, `runs.checklist`; terminal `checklist` telemetry | registered in terminal sessions and their subagents; each write shows as a checklist block in the transcript; a subagent row shows its `n of m tasks` | not shown | terminal done; App planned | PAR-001 |
+| Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
+| Accounts | `accounts/` | `accounts.*` | `/accounts` | Accounts | parity | — |
+| Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
+| Skills | `plugins/`, `tools/dispatch.ts` | `skill_load` | `$name`, `/skill:name`, browser Skills tab | Capability, composer | parity | — |
+| Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | resource browser | Capability | parity | — |
+| Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
+| Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
+| Isolated browser | `browser/` | `browser_*` | world tools, headed on request, `/settings` Browser tab | App WebKit tabs (host-backed) | host-backed | — |
+| Page annotations | `annotations/` (PROP-0017, PROP-0018) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/plugin:annotate` pane (inspector, queue, app windows over DevTools or the page bridge), `/plugin:notes` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | parity in the working tree; native WKWebView gestures unaccepted | PAR-011 |
+| Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | working group **Create worktree** (`worktrees.create`) | partial | PAR-012 |
+| Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `xagent-wiki` shell command only | tools | host only | PAR-002 |
+| History and trajectory (model tools) | `history/` | `history_*`, `trajectory_*` | shell command, `/trajectory` page | tools, trajectory views | host only | PAR-002 |
+| Wiki browsing | `wiki/` | `wiki.*` | none | Wiki | host only | PAR-005 |
+| Variants and refinement | `variant/`, `refine/` | `harnesses.*`, `refine.*` | browser Variant tab (read-only), `xagent refine` | Harness screen | host only | PAR-004 |
+| Output trim and budget guard plugins | `plugins/firstParty.ts` | — | not loaded in terminals | loaded | host only | PAR-006 |
+| Doctor | `doctor/` | `doctor.*` | `/doctor` | diagnostics | parity | — |
+| Run inspection | `sessions/runStore.ts` | `runs.*` | `/trajectory`, `/log` | run views, analytics | parity | — |
+| Session catalog (sessions per folder) | — | — | per-folder history | Solo thread list | planned | PAR-008 |
+| Folder choice and recent folders | `core/projects.ts` | — | launch folder only | working groups | planned | PAR-009 |
+| Computer control | — | `computer_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
+| Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
+
+The terminal-only display amendments [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md)
+and [PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) permit connected
+structural glyphs, frame-attached standalone dividers, and high-confidence boundary normalization
+through whitespace while retaining literal ASCII persistence and unchanged answers. The App may
+keep its literal preview. This does not reopen the expanded metadata contract verified under
+PAR-013. Isolated production PTY evidence verifies bounded fixture topology, not every emulator/font
+or live-model sketch quality.
+
+## Gaps
+
+| ID | Gap | Planned change |
+|---|---|---|
+| PAR-001 | Checklist absent from the App | The terminal registers the tool and renders a checklist block; the App renders it too. |
+| PAR-002 | Wiki, history and trajectory reach terminal models only through a shell command | Register the harness tools in terminal sessions; retire the shell commands (drift D-4). |
+| PAR-003 | Continuation unused | `/resume` lists interrupted runs and continues one with `continueFrom`; the App offers Continue. |
+| PAR-004 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
+| PAR-005 | Wiki browsing only in the App | A `/wiki` page over `wiki.*`. |
+| PAR-006 | First-party hook plugins not loaded in terminals | Load them through the terminal's trusted selection. |
+| PAR-007 | Host tools without a Harness owner | Decide each: computer control stays host-backed (terminal shows unavailable); the files vault becomes a Harness capability or is dropped. |
+| PAR-008 | Separate session catalogs | A Harness session catalog per folder, read by both front ends (needs a proposal). |
+| PAR-009 | Folder choice | Built on PAR-008: recent folders in both front ends. |
+| PAR-010 | Agent profiles absent from the App | An Agents screen over `agents.*`, and the profile name and colour on subagent rows (PROP-0029). |
+| PAR-011 | Page annotations | Harness, terminal and App source done (PROP-0017, PROP-0018, 2026-10-24): the App calls `annotations.*`, imports its old notes once, uses the `page_notes_*` tools, and has the Annotate panel. Open: acceptance of the inspector and selection gestures in the running App's WKWebView. |
+| PAR-012 | Managed worktrees | Harness and terminal done (PROP-0016). The App creates through `worktrees.create`; its groups do not yet offer hand off, prune, restore or managed worktrees per thread. |
+| PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |
+| PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |

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. The npm registry published 1.0.0 as the stable baseline; this file
+remains its release notes.
+
+## 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/4.0.0.md

@@ -0,0 +1,46 @@
+# Xingular Harness 4.0.0
+
+This major release builds on the published 1.0.0 baseline. It extends Harness-owned terminal
+surfaces and adds generic worktree and page-annotation capabilities; it also changes the built-in
+terminal command namespace, documented below. Earlier published versions remain available.
+
+## Included
+
+- Managed Git worktrees for sessions and the terminal, with leases, guarded setup scripts, handoff,
+  pruning, restoration, and bounded snapshots that preserve uncommitted work.
+- Page annotations and queued notes, including capture, review, resolution, sharing, and delivery
+  through Harness methods and terminal `/plugin:annotate` and `/plugin:notes` pages.
+- A unified terminal resource browser with persistent full-screen sections for browser tabs,
+  plugins, skills, connectors, variants, and other Harness resources.
+- A full-screen `/trajectory` Runs/Events browser with searchable event details, selected-event
+  JSON, and a responsive split-pane layout.
+- Additional terminal controls for browser settings, plugin settings, and subagent activity.
+- Fix Node 22 SQLite parameter binding in recall and run indexes, and guard worktree Git calls
+  against early child-process exits while writing input.
+- Updated architecture and parity documentation for Harness capabilities and their terminal and
+  host surfaces.
+
+## Installation and requirements
+
+Use `npm install --global @xingular/harness@4.0.0`, then `xagent`. Node 22.19 or later is required.
+The interactive terminal also 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.
+
+## Compatibility
+
+The new server methods are additive. The published executable is `xagent`, replacing the earlier
+`xharness` candidate command without a compatibility alias; scripts using that candidate name must
+be updated. Required built-in plugin commands use unprefixed names:
+`/subagents`, `/trajectory`, `/doctor`, and `/worktree`. Optional built-in and third-party extension
+commands use `/plugin:<command>`; the optional page-annotation commands remain `/plugin:notes` and
+`/plugin:annotate`. Update scripts and keybindings that used the earlier candidate's prefixed forms
+for required commands. Existing session, variant, account, plugin, and browser contracts remain in
+place. Install this exact version or use the `latest` tag; historical versions remain available.
+
+## Verification scope
+
+The Harness CI suite, standalone proof, App typecheck/tests/layer check/Rust tests, and App UI
+consistency check must pass for the reviewed release candidate. The release tag workflow separately
+builds and smoke-tests the exact tarball on its supported operating systems before publishing it
+with npm provenance.

package/docs/releases/README.md

@@ -0,0 +1,41 @@
+# Release procedure
+
+1. Review and commit completed Harness changes on the active release branch. 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 and workflow release.yml, with direct publishing enabled. No login is
+   started automatically. An already-used target version or unreachable registry blocks publication.
+5. Present the exact commit, candidate inventory/hash, notes and check results for approval. Pushing
+   the matching v<version> tag triggers publication; do not push it 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.
+
+## 4.0.0 candidate preparation
+
+Local checks on the candidate source passed: Harness `npm run ci` (typecheck, 134 test files with
+1,004 passing tests and 3 skipped, plus the standalone proof); App typecheck, `npm test` (566 renderer
+tests, 47 sidecar tests, and 7 dev-signing tests passed with 1 skipped), layer check, and Rust tests
+(168 passed, 1 ignored); and App UI consistency. The registry lists 1.0.0 as `latest` and 4.0.0 as
+unused. The clean-tree release preflight passed. Exact-tarball packaging and a fresh-install smoke
+test passed, including the packaged SDK, types, CLI, server and isolated terminal. The tagged
+preflight, two-OS CI, and exact-tarball smoke are enforced by the release workflow. The npm
+trusted-publisher configuration for `tanntnny/xingular-harness` and `release.yml` requires
+package-owner verification; `npm login` does not verify that setting.
+
+The release workflow runs its full CI and exact-tarball smoke test on both Ubuntu and macOS before
+publishing. Branch upload and the matching release-tag push are separate GitHub side effects; only
+the tag triggers publication. No local test failure is waived by this note.

package/docs/study/00-index.md

@@ -0,0 +1,83 @@
+# 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
+
+- [Proactive autonomy and three feature directions](proactive-autonomy.md) — scheduled initiative,
+  a human-readable agenda, UI repair, cleanup and product experiments; fresh
+  [proactive-system evidence](autonomy-sources.md) and
+  [autonomous-engineering evidence](autonomous-engineering-sources.md). Research hypotheses,
+  not an accepted architecture change.
+- [`/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).