@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,56 @@
+# Source: Claude Code (Anthropic) — v2.1.88 source, leaked
+
+- Origin: [Anthropic Claude Code](https://www.anthropic.com/claude-code). Not open source. On
+  2026-03-31 the npm package `@anthropic-ai/claude-code` 2.1.88 shipped `cli.js.map`, whose
+  `sourcesContent` is the complete TypeScript source; the package was pulled within hours and the
+  source was widely mirrored. Anthropic's own toolchain is the suspected cause (a Bun issue about
+  source maps served in production builds, [oven-sh/bun#28001](https://github.com/oven-sh/bun/issues/28001)).
+- Local code: `external/claude-code-src` (clean `src/` tree, 1,884 `.ts`/`.tsx` files) and
+  `external/claude-code-sourcemap` (the original npm tarball, unpacked `package/`
+  with `cli.js` + the 57 MB map, and `restored-src/src`, 512,664 lines). Both are gitignored.
+- Licence: the leaked code carries no grant ("SEE LICENSE IN README.md"). Read it for study; do not
+  vendor or reuse it.
+- Why studied: the de-facto reference for UX-shaped harness conventions — CLAUDE.md hierarchy,
+  skills, subagents as first-class configs, hook events, plan mode, permission modes. Every other
+  harness in this study copies it knowingly or not.
+
+## What the source now answers
+
+- Prompt assembly: `src/constants/prompts.ts` — `getSystemPrompt` returns an array of strings with
+  `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` (`:114`) splitting globally cacheable text from per-session text;
+  a section registry (`constants/systemPromptSections.ts`) holds cached and `DANGEROUS_uncached`
+  entries. Measured in [STUDY-0007](../STUDY-0007-claude-code-prompt.md).
+- Subagent prompt: the parent prompt plus `enhanceSystemPromptWithEnvDetails` (`prompts.ts:760`),
+  and per-agent text in `src/tools/AgentTool/built-in/*`.
+- Memory: `src/memdir/` — `MEMORY.md` entrypoint capped at 200 lines / 25 KB (`memdir.ts:35`),
+  typed-memory sections, and a KAIROS daily-log mode.
+- Compaction: `src/services/compact/` — auto-compact with a 3-failure cap (`autoCompact.ts:70`),
+  function-result clearing, cached micro-compact.
+- Tools: one `prompt.ts` per tool under `src/tools/*/`, which is where most tool instruction lives
+  rather than in the system prompt.
+- Final-reply text: `# Output efficiency` (`prompts.ts:416`), `# Tone and style` (`:430`), the
+  ant-only `# Communicating with the user` (`:405`), faithful reporting (`:240`), the subagent report
+  sentence and notes (`:758`, `:765-768`) and the away-summary prompt (`services/awaySummary.ts:22`).
+  Measured in [STUDY-0009](../STUDY-0009-claude-code-reporting.md).
+
+## Map to arms
+
+- Arm 01 (prompt): static/dynamic split for the cache, per-section registry, `# Environment`,
+  output styles, language section.
+- Arm 02 (tools): rich per-tool `prompt.ts` files ("use when…" lives there, not in the prompt).
+- Arm 03 (subagents): built-in explore/plan/verification agents, `subagent_type`, fork mode.
+- Arm 04 (skills): `/<skill-name>` shorthand, Skill tool, experimental discover-skills.
+- Arm 05 (context): compaction thresholds, `--continue/--resume`, tool-result clearing.
+- Arm 06 (memory): CLAUDE.md hierarchy plus auto-memory with line and byte caps.
+- Arm 07 (governance): permission modes, allow/deny rules, hooks (PreToolUse/PostToolUse),
+  `# Executing actions with care` (`prompts.ts:256`), native client attestation (`constants/system.ts`).
+- Arm 08 (execution): bash with working-dir constraints, scratchpad directory, worktree sessions.
+
+## Open questions
+
+1. Hooks: which events exist, and do they mutate tool input (`PreToolUse` update semantics) —
+   contrast with the here-rule "a hook is told, never asked".
+2. Plan mode mechanics (bilateral approval) — how its gate differs from our refinement probes
+   (answer-free, no world effect).
+3. Undercover mode and anti-distillation (`utils/undercover.ts`, `services/api/claude.ts`) — what a
+   product prompt is allowed to hide, and what this harness's `INV-BND-2` says instead.

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

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

package/docs/study/sources/harness2.md

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

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

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

package/docs/study/sources/omp.md

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

package/docs/study/sources/opencode.md

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

package/docs/study/sources/openhands.md

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

package/docs/study/sources/smolagents.md

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

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

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

package/docs/study/tui-resource-browser.md

@@ -0,0 +1,78 @@
+# TUI resource browser study
+
+Status: source study completed, 2026-10-22. Runtime acceptance is recorded separately.
+
+## Current gaps
+
+`/components` browses registry resources and compares them with the latest variant head;
+it does not enumerate the session loader. `/plugins` controls attachments and trust while
+`/hub` installs into separate destinations. The OpenTUI palette accepts slash commands only;
+`skillCompletions` exists but has no OpenTUI caller. `$name` expansion works on submission.
+
+## Local reference evidence
+
+| Reference | Inspected source | Adopted pattern | Harness adaptation |
+|---|---|---|---|
+| OMP | `external/omp/packages/tui/src/overlays/extensions/extension-dashboard.ts`, `inspector-model.ts` | Inventory, owner/provider and inspector in one browser | Inspect before changing state; existing loader and gate remain authoritative |
+| OpenCode | `external/opencode/packages/tui/src/component/dialog-skill.tsx`, `dialog-mcp.tsx`, `command-palette.tsx` | Searchable skills, explicit loading/errors, actionable MCP states | Use inserts a draft; cached MCP checks are labelled with dates |
+| Kimi CLI | `external/kimi-cli/src/kimi_cli/ui/shell/slash.py`, `mcp_status.py` | Skills in help and server/tool relationships | Link relationships inside the browser rather than requiring a second command |
+| OpenHands | `external/openhands/src/components/features/plugins/build-plugins-view-model.ts`, `routes/skills-plugins.tsx` | Reconcile catalog, installed and ambient resources | Preserve distinct owners/paths for duplicate names; runtime proves availability |
+| DeepSeek | `external/deepseek-harness/apps/web/tests/expected/plugin-manager/manager.expected.md` | Descriptive built-in settings and explicit plugin details | Foundation descriptions and configuration links; no web card layout in the terminal |
+| Harness² | `external/harness2/harness2/core/tree.py` | Explicit editable surface and eight components | Read-only c1–c8 inspection with pinned/latest versions |
+
+These are bounded source observations, not claims of runtime visual equivalence.
+The other checkouts (Orca, OpenHands SDK, smolagents, SWE-agent) are not primary terminal
+layout references for this change. No reference implementation is copied into the runtime.
+
+Inspected checkout revisions (source observations above):
+
+- OMP: `63a7ba5dcc74cca2cb0ecb710770eb756102035d`
+- OpenCode: `94bc5662c4ad3b983276021ce9df7f0bc1b11d5c`
+- Kimi CLI: `9ab1286b8fe4e6bcd116949a27ce5e0ac3389c82`
+- OpenHands: `9057a57f4a7b5a74e93989090edaffc21e3554ff`
+- DeepSeek Harness: `687f282e8625c6b8d11ff58211a90524be2e4317`
+- Harness²: `1cfe254e8d25b15f37048c3730134686abe60335`
+
+## Navigation decision
+
+`/harness` is the main browser. `/skills`, `/plugins`, `/connections` (`/mcp`) and `/tools`
+are direct section shortcuts; `/hub` selects Discover, `/components` selects Library.
+Installed includes locally present resources and labels their effective state. Discover uses
+the existing Hub with All/Community/Official filters. Built-in and foundation are different axes:
+foundation is a runtime ownership boundary; built-in is provenance.
+
+## Responsive wireframes
+
+Wide (inner width >=88):
+
+```text
+Harness > Skills       Installed | Discover       All | Community | Official
+Overview        Search skills...             | Selected skill
+Foundation      Review        Available now  | Description, owner, origin
+Variant         Review        Library only   | Availability, path, scope
+Skills          Another       Disabled       | Inspect / Use / Manage
+Plugins                                      |
+Connections                                  |
+Tools                                        |
+Library                                      |
+```
+
+Compact (80-column terminal):
+
+```text
+Harness > Skills [choose section]
+Installed | Discover
+Search skills...
+Review                    Available now
+Another                   Library only
+Enter details; Tab controls; Ctrl+F search
+```
+
+At 40 columns, controls truncate or wrap into the bounded frame. Detail replaces the list;
+Escape returns without losing query/selection. Wide and compact modes share the same state.
+
+## Acceptance journeys
+
+Find and invoke a skill; import a local bundle; install a Hub skill and add it to a future
+variant; review/trust a local plugin; configure local/remote MCP; inspect web_fetch ownership;
+compare pinned/latest variant files; recover from offline/empty discovery and failed sign-in.