@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/proposals/PROP-0041-bounded-work-slices.md

@@ -0,0 +1,247 @@
+---
+id: PROP-0041
+title: Bounded work slices, a durable checkpoint, and a stall guard for long replies
+status: Implemented; terminal card, App presentation and /slices open
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-RUN-2, INV-RUN-3, INV-RUN-4, INV-RUN-12, INV-PRM-1, INV-PRM-2, INV-PRM-4, INV-PRM-5, INV-PRM-10, INV-GATE-2, INV-STO-3, INV-PAR-1, INV-PAR-2, 02-sessions-and-runs.md, 04-prompt.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity.md]
+---
+
+# PROP-0041: Bounded work slices, a durable checkpoint, and a stall guard
+
+## Problem
+
+A single reply can run for hours. Two measured sessions (STUDY-0003) ran 114 and 75 minutes in
+**one** reply: 448 and 274 tool calls, 5 and 2 context compactions at ~256k tokens, 42 repeated
+identical calls, and 41 minutes in three Playwright runs — 25 of them on two timeouts. The first had
+addressed the person with **no text at all** at 114 minutes when it was measured, and was still
+going; the second produced a single 2 028-character report at minute 74.9, and it said the release
+was still blocked.
+
+Nothing in the foundation bounds a reply. The only limiter is the opt-in `budget-guard` plugin
+(`src/plugins/firstParty.ts:31,105-140`), which is off by default and, when on, refuses tools and
+terminates the reply with no handoff. The post-compaction checkpoint (PROP-0033) restores only the
+goal and the checklist, returns `null` when no checklist was written (`src/prompt/compile.ts:196`),
+and carries no files, failing commands or decisions. Bash has no default timeout
+(`src/core/workspaceBashTool.ts:23`). There is no stall detection, no heartbeat, and dead-owner runs
+are only reconciled at startup (`src/sessions/runStore.ts:228`).
+
+The result is not a loop on one action; it is a reply with no boundary. Nothing the model learns
+becomes a checkpoint, a commit or a message, so the person cannot steer, review or stop it, and the
+model re-derives state by re-reading files after every compaction.
+
+Task and goal lifecycle stay in the application (`docs/study/feature-gap-review.md:7,35`). Every
+mechanism below is **run execution**, which the harness owns.
+
+## Affected rules
+
+- **INV-RUN-4** currently says continuing is "always a new run the application asks for". A slice
+  policy asks on the run's behalf. This proposal amends the asker, not the rule: continuation remains
+  a new run with the earlier run's pins, and the earlier record is never reopened.
+- **INV-RUN-12 / INV-PRM-10** define the post-compaction checkpoint as goal + checklist + plan. The
+  checkpoint becomes a bounded ledger assembled by the compiler and used at both compaction and slice
+  boundaries. It stays ephemeral, bounded, and free of hidden reasoning.
+- **INV-RUN-3** every event is validated before it is persisted or relayed; the new `checkpoint`,
+  `progress` and `heartbeat` events follow the same path.
+- **INV-RUN-2 / INV-PRM-5** a new foundation tool (`checkpoint_write`) joins the frozen capability
+  set and the compiled tool manifest. Runs pin it; nothing widens after launch.
+- **INV-GATE-2** the gate stays the last extension. The loop guard is a foundation extension loaded
+  before it, like the compaction checkpoint.
+- **INV-PRM-1/2/4** all checkpoint and guard text is assembled in `src/prompt/compile.ts`; the
+  stable system prompt does not change.
+- **INV-STO-3** no new file or folder: checkpoints are run events in `events.jsonl`.
+- **INV-PAR-1/2** the budget, checkpoint card, stall report and `/slices` control exist in the
+  terminal and are presented by the App; `parity.md` gains a row.
+
+## Proposal
+
+### 1. A reply budget, enforced at the tool boundary
+
+A foundation policy, on by default for every run (interactive, automatic, plan, probe, subagent):
+
+- `workSlice.enabled` true; `workSlice.maxToolCalls` 160, `workSlice.maxMinutes` 40,
+  `workSlice.maxNewTokens` 320 000. `enabled: false`, or `XINGULAR_WORK_SLICE=off` at launch,
+  removes the guard from a run: no budget, no stall notes, no continuation. Any
+  limit reached, or `0` to disable that one, ends the slice. A token cap counts new input, cache
+  writes and output; counting the cached prefix made one large read end a reply before any work
+  (measured on the "Confirm plan model support" thread: 76 807 counted tokens after four requests).
+- Counted by the runner from observed events: tool calls started, wall clock since the run started,
+  and the sum of `inputTokens + cacheReadTokens + outputTokens` per request.
+- Enforcement is a Pi `tool_call` hook, like `budget-guard`, but the exit is a checkpoint, not a
+  silent stop: the next tool call is refused once with a reason that names the spent budget and
+  instructs the model to call `checkpoint_write`; that tool (and `session_name`) remain callable.
+  After a valid checkpoint, the model gets one request to write the person-facing progress line, and
+  the run settles with terminal reason `slice_complete`.
+- A reply that finishes inside its budget is unaffected at runtime: no extra request and no extra
+  context. The only global cost is the new tool entry in the compiled manifest (Consequences).
+
+### 2. `checkpoint_write`: a bounded, evidence-linked ledger
+
+A foundation tool, always present beside `checklist_write`:
+
+```
+checkpoint_write {
+  summary: string            // ≤ 1 200 chars, what the person should know now
+  done: [{ item, evidence[] }]    // ≤ 20; evidence is a path, a check command, or a decision
+  next: string               // the single next step
+  blocked?: string           // what stops progress, if anything
+  files: [{ path, why }]     // ≤ 20
+  checks: [{ command, ok, detail }]  // ≤ 8; detail holds the failing line, ≤ 300 chars
+  decisions: [{ what, why }] // ≤ 8
+}
+```
+
+- The harness validates shape and bounds, then records one `checkpoint` run event (bounded 8 000
+  chars). The latest checkpoint is the run's resumable state; `runs.continuation` returns it next to
+  the checklist.
+- Evidence is checked against the run's own events since the previous checkpoint. A `done` item whose
+  evidence was not observed is kept but marked `unverified` in the record and told to the model; the
+  tool never refuses a checkpoint, because a checkpoint is better than a stall.
+- The prompt section that asks for a checkpoint is compiled, bounded, and states that the ledger is
+  read by the next slice, not shown as a plan.
+
+### 3. Continuation from the checkpoint
+
+- `continueFrom` already starts a new run with the earlier run's pins. A slice policy may perform
+  that continuation without an application request when the account's setting is on: same session,
+  same account, variant and capability set, `resumedFromRunId` set, earlier record untouched.
+- The new run's context begins with the compiled checkpoint (goal, ledger, plan instructions), so the
+  model resumes from state rather than from a summary. The normal PROP-0033 checkpoint continues to
+  cover mid-slice compactions.
+- Both surfaces offer the same control: `/slices on|off` in the terminal, the matching setting in the
+  App, and a per-run override on `sessions.run` (`workSlice: { maxToolCalls?, maxMinutes?, maxNewTokens?, continue? }`).
+- Off means the run still stops at the budget, writes the checkpoint, and returns to the person with
+  a "continue" affordance. Slices are a convenience; the checkpoint is the contract.
+
+### 4. Stall guard
+
+A foundation extension (`src/sessions/workSlice.ts`), registered where the compaction checkpoint is:
+
+- Signatures are `toolName + canonicalised args`, hashed, so every argument participates and a
+  changed argument (a checklist whose steps moved on, a different path) is a different call. Detect,
+  per reply:
+  - the same signature 3 times (`checkpoint_write`, `session_name`, `wait_subagents` and
+    `subagents.*` polling exempt);
+  - the same Bash command failing twice;
+  - 25 tool calls with no `file.changed` and no passing check;
+  - one file edited 4 times with no intervening passing check.
+- The counts and the nudge start fresh in each reply, because each reply is one slice: progress a
+  later reply reports cannot make an earlier reply's call look repeated. Reading a fixed handful of
+  field names instead of all arguments once made every `checklist_write` look identical, which is
+  how a reply that reported its progress was told it was repeating work.
+- First hit: block that call once and inject a compiler-rendered, bounded evidence note (the earlier
+  timestamps, exit codes and paths). This is the Manus "keep the failure visible" rule.
+- Second hit for the same signature, or any hit after one nudge in the same slice: force a
+  checkpoint, end the slice with `blocked`, and report the evidence instead of continuing. Never a
+  silent kill, never an unbounded retry.
+
+### 5. Command budget
+
+- `workspaceBashTool` gains a default `timeout` of 120 s and a hard ceiling of 300 s. A longer call is
+  allowed only with an explicit `reason`, is shown in the approval action, and is capped at 900 s.
+- A timed-out command returns its partial output plus "timed out after Ns; narrow the command (one
+  test file, `--grep`, a line range)". After two timeouts in a run, the guard's evidence note asks for
+  the narrow run first.
+- Browser suites and full CI are run as background work where the surface supports it; the slice
+  budget must not be spent blocking on them.
+
+### 6. Compaction discipline
+
+- Before Pi compacts, drop the oldest tool results beyond a character budget through the existing
+  `context` projection (the mechanism PROP-0033 already uses), keeping every path and command line.
+  This is the cheapest lever and the one these runs lacked with `output-trim` off.
+- Count compactions per run. At the third, do not compact again: force a checkpoint and end the slice,
+  naming the largest tool results as the cause (Claude Code's documented thrash guard).
+- Where Pi exposes its summariser prompt, the foundation sets the same requirements the checkpoint
+  has: paths with line ranges, failing command lines, and decisions survive.
+
+### 7. Liveness and progress
+
+- One new run event while a reply is active: `heartbeat` every 30 s `{ steps, elapsedMs, lastTool,
+  compactions, slice, maxToolCalls }`, relayed to every surface. `message.completed` already carries
+  every visible assistant text block, so no separate `progress` event is added (implemented this
+  way; the second copy bought nothing).
+- A stall watchdog settles what the process table cannot. The store reconciles on activity as well as
+  on the owner pid, and periodically rather than only at startup: no heartbeat for five minutes while
+  the host is alive marks the run `stalled` (a long command still heartbeats, so a 16-minute build is
+  not mistaken for a hang), and a `running` or `waiting_*` run whose owner process is gone becomes
+  `interrupted` with `terminalReason: "owner_gone"`. Model work is never restarted (INV-RUN-4).
+- `owner.json` records a process start marker next to the pid, so a recycled pid cannot make a dead
+  owner look alive.
+
+### 8. Defaults and the existing plugin
+
+- The slice policy, checkpoint tool, stall guard and heartbeat are foundation and on by default. The
+  `budget-guard` plugin stays for people who want a different cap; the Slice policy supersedes it, and
+  the plugin's page says so.
+- Until this lands, the quickest real relief is configuration: `output-trim` on (20 000 chars) and
+  `budget-guard` at 120 requests.
+
+## Alternatives
+
+- **Turn `budget-guard` on by default.** Rejected: it stops the reply with no state and no handoff,
+  which converts a long run into a lost run.
+- **Raise the context window or compact more often.** Rejected: latency and context rot both grow with
+  input; the two runs compacted five and two times and still re-read `host.rs` 11 times.
+- **Extend `checklist_write` instead of a new tool.** Rejected: the checklist is the person-visible
+  plan and is reworded as scope changes; the checkpoint is execution state with evidence. Mixing them
+  is what produced five reworded plans in one run.
+- **Let the App drive continuation.** Rejected: that is orchestration in the wrong layer, and the
+  terminal would lose parity (`INV-PAR-1`).
+- **Add a task/goal lifecycle.** Rejected here: it belongs to the application
+  (`feature-gap-review.md:7,35`) and is not needed to bound a reply.
+
+## Consequences
+
+- More runs per long task, each with its own record and pins. Continuation already supports this, so
+  session and thread views group them; a person sees a checkpoint every ≤ 40 minutes instead of
+  nothing.
+- Two new tools/events and two new settings, which the App must present for parity. The compiled tool
+  manifest gains one entry, which changes the provider-cache prefix once (INV-PRM-8: measure with real
+  requests, with the owner's permission).
+- A model can be stopped mid-slice. It is stopped with its own written state and a person-facing line,
+  never silently.
+- The context stops growing to 256k in a single reply, so per-step latency and compaction cost fall;
+  the exact gain is to be measured, not assumed.
+
+## Migration
+
+No format migration. Existing runs and native histories are readable; runs without a checkpoint
+continue to resume from the checklist. `terminalReason` gains `slice_complete`, `owner_gone` and
+`stalled`; readers that switch on unknown reasons keep their default. Record validators accept the
+new event types; older records stay valid. The App's event schemas accept the new types in the same
+change (its sidecar test parses every reply of this package).
+
+## Checks
+
+- Unit: budget counting and refusal, checkpoint validation and bounds, evidence marking, continuation
+  pins and `resumedFromRunId`, stall signatures and exemptions, Bash ceiling and partial output,
+  heartbeat cadence, owner-gone reconciliation, event validators.
+- Integration: a fake Pi session that makes 60 tool calls ends in one `checkpoint` event and a
+  `slice_complete` run, and the continuation starts with the rendered checkpoint; a duplicated call
+  is blocked once and then ends the slice; a dead owner is reconciled while the process is alive.
+- `npm run typecheck`, `npm test`, `npm run prove` here; the App's `npm run typecheck`, `npm test`,
+  `npm run check:layers`, `npm run check:ui` and `cargo test`; then compare the STUDY-0003 metrics on
+  the same two tasks with real runs.
+
+## Implementation status (2026-10-26)
+
+Implemented in this tree:
+
+- `checkpoint_write` (`src/tools/checkpoint.ts`) with its plugin descriptor, frozen capability entry,
+  prompt group and terminal socket bridge; the run records `checkpoint`.
+- The slice guard (`src/sessions/workSlice.ts`): budget refusal, checkpoint allowance (including the
+  first call past the limit), termination,
+  repeated-call, repeated-failure, edit-churn and no-progress notes, compaction-thrash guard, and
+  per-reply reset. Wired for structured and terminal replies.
+- The runner's `heartbeat`, derived fallback checkpoint, `slice_complete`/`stalled` terminal reasons
+  and the third `finish` argument.
+- Auto-continue with `maxSlices` 8, a fruitless-slice stop and a blocked stop, off for automatic,
+  plan, subagent, command and worktree runs; the continuation renders the checkpoint.
+- The command budget (120/300/900 s) on the Bash tool and both initial `!` paths.
+- The liveness watchdog (`reconcileStaleRuns`, 60 s timer) with heartbeat-age and legacy silence
+  rules.
+
+Open, tracked as `PAR-004` in [`docs/parity.md`](../../parity.md): the terminal's checkpoint card,
+`/slices`, and the App's event schemas, checkpoint card and slice line. Rerun of the STUDY-0003
+tasks with real requests is still to be done with the account owner's permission.

package/docs/architecture/proposals/PROP-0042-usage-and-provider-limits.md

@@ -0,0 +1,127 @@
+---
+id: PROP-0042
+title: Usage analytics and provider limits as a built-in capability
+status: Accepted
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-MEM-5, INV-MEM-6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 08-memory-and-history.md, 09-accounts-and-connectors.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity.md]
+---
+
+# PROP-0042: Usage analytics and provider limits as a built-in capability
+
+## Problem
+
+A run already records what each model request used: `usage.updated` carries per-request tokens,
+cost, provider, model, TTFT and duration (`src/sessions/contracts.ts`, emitted in
+`src/sessions/runner.ts`). Nothing aggregates it, and the SQLite `runs` table stores only ids,
+status and timestamps (`src/sessions/runIndex.ts`). A person cannot answer "what did this account
+spend this week, on which model?" without reading run folders.
+
+The account store already has the shape of provider limits — `Limit`, `AccountState.limits`, and
+health derived from `usedPercent`/`resetsAt` (`src/accounts/store.ts`) — and `account.status`
+carries a `limits` array (`src/sessions/contracts.ts`). No producer ever fills it: `Probe.limits`
+is never assigned in `Accounts.probe`, and `runner.ts` only classifies provider error text. A
+person cannot see how close a subscription plan, credit balance or rate window is.
+
+The capability is something a person uses, so it belongs in the Harness with a terminal surface
+before any host screen (`INV-PAR-1`).
+
+## Affected rules
+
+- **INV-MEM-5** Files are the source of truth. `index.sqlite` is derived and can be deleted and
+  rebuilt. The usage ledger is derived data inside that index; it adds no run file.
+- **INV-MEM-6** Index migrations are append-only. Migration 8 appends the usage tables.
+- **INV-STO-2** `index.sqlite` can be deleted and rebuilt; the ledger is rebuilt from run events.
+- **INV-SRV-1** A new `usage` method group is additive. Existing method names, params and result
+  shapes do not change.
+- **INV-PLG-10** The methods and commands are contributed by one built-in feature module, so the
+  public method table remains assembled by `server/methods.ts` and the plugin has one owner.
+- **INV-ACC-3** The harness never writes a secret to its own files. Provider limit reads use the
+  credential Pi already resolved through `Models.getAuth`, send it only to the provider, and store
+  no credential. A refreshed OAuth token is written only through the existing credential store.
+- **INV-RUN-7** The meaning of every usage field is unchanged. The ledger copies them; aggregates
+  are new derived data.
+
+## Proposal
+
+A built-in plugin `usage` owns a **read-only** capability with one full-screen terminal page and
+two commands:
+
+- `/usage:` and `/usage:analysis [today|7d|30d|all]` — token, cost and latency analytics from a
+  derived ledger.
+- `/usage:limit` — what each provider last reported about its plan windows, balances or rate
+  limits.
+
+**Ledger.** Migration 8 adds `usage_requests` (one row per model request) and `usage_indexed` to
+`index.sqlite`. A run's ledger rows are written from its `usage.updated` events when the run ends,
+and repaired by `open`, `rebuildIndex()` and the first analysis call when the ledger is empty. A
+per-request row is used when the event carries `request`; a provider that reported only cumulative
+totals contributes one row from its latest event. Cost uses the provider's own figure; a request
+with no cost may be priced at Pi's catalogue rates for display, and the estimate is marked
+separately, never presented as a provider figure. Aggregates are bounded: one scope, one period,
+top ten rows per breakdown, at most 400 days, with an unpriced-request count.
+
+**Limits.** Three sources, in this order:
+
+1. **Response headers**, captured by wrapping each account runtime's provider streams with
+   `onResponse`; a terminal session's runtime forwards only the limit-bearing headers over its
+   control-key-protected socket. Four families are understood: `anthropic-ratelimit-*`, Anthropic unified plan
+   windows, `x-codex-*` plan windows, and the common `x-ratelimit-*` headers. `Retry-After` on a
+   429 is kept as a reset hint. Raw headers are never stored.
+2. **The provider's own usage endpoint**, read with `Models.getAuth` and a bounded HTTPS GET that
+   refuses redirects and other hosts: OpenRouter `GET /api/v1/key`, DeepSeek
+   `GET /user/balance`, Anthropic's organization `rate_limits` (admin credential only; configured
+   limits, not usage), ChatGPT/Codex `GET /backend-api/wham/usage` (account id from the access
+   token), and OpenCode Go `GET /zen/go/v1/usage`.
+3. **Unavailable**, with a reason. No percentage is ever invented. A provider with no documented
+   endpoint, a custom base URL, an expired sign-in or no support shows local usage only.
+
+Undocumented plan endpoints stay behind the plugin setting `experimentalProbes` (off by
+default). A reading is cached per account and provider for `refreshMinutes` (default 10); a
+page open or `r` refreshes only what is due. Readings live in the account's existing state
+(`limits`, plus a new `providerLimits` readout list) and never create a new file.
+
+**Surfaces.** Public methods `usage.summary`, `usage.limits`, `usage.sync`; protected terminal
+routes `terminal.usage.summary` and `terminal.usage.limits` for the page, all through the same
+service. The App screen is a later host task, tracked as `PAR-016`.
+
+## Alternatives
+
+- **Read every run's `events.jsonl` on demand.** Correct but unbounded: a year of runs is many
+  megabytes per page open. A derived table is what the index is for.
+- **Store analytics in a new data folder.** Violates `INV-STO-3` and duplicates derived data the
+  index can rebuild.
+- **Scrape provider dashboards.** Not stable, not authenticated, and not a provider API.
+- **Show a percentage for every provider by assuming a cap.** Fabrication; rejected.
+- **Make limit reads automatic in the background.** Surprise egress with a person's credential;
+  rejected in favour of page-open and explicit refresh.
+- **Do nothing.** Leaves usage and limits unanswerable in both surfaces.
+
+## Consequences
+
+- Two additive method routes and two terminal commands; no protocol version change.
+- `index.sqlite` gains two tables (migration 8), rebuilt from run files.
+- `AccountState` gains an optional `providerLimits` readout list and `Limit` gains optional
+  absolute fields and `remainingPercent`; old state files load with defaults, and old readers
+  ignore the additions.
+- A page open may make one small read-only request per due provider, using the account's existing
+  credential. No model request, no token spend, no secret written.
+- The harness remains the only writer of the ledger and of limit snapshots.
+
+## Migration
+
+No data rewrite. The index migrates in one transaction with the existing backup/restore path; an
+old index simply indexes existing runs on the next `open` or `usage.sync`. Account state files
+without `providerLimits` read as an empty list. Reverting removes the plugin module and commands;
+the extra index tables are inert.
+
+## Checks
+
+- `npm run typecheck`, `npm test` (`src/usage/*.test.ts`, `src/plugins/usage.test.ts`).
+- `npm run prove` with an injected reader: `usage.summary` after a fake recorded run and
+  `usage.limits` returning an explicit unavailable reason, with no network.
+- Terminal verification of `/usage:`, `/usage:analysis`, `/usage:limit` and the two tabs.
+- App checks (`npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`,
+  `cargo test`) after the Harness change.
+- Real provider header names are confirmed only by a separate owner-authorized request per
+  provider; fixtures keep only redacted header values.

package/docs/architecture/proposals/PROP-0043-read-only-plan-bash.md

@@ -0,0 +1,74 @@
+---
+id: PROP-0043
+title: Read-only Bash in plan mode, enforced by the OS sandbox
+status: Accepted; implemented
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-RUN-8, INV-GATE-3, INV-GATE-8, 02-sessions-and-runs.md, 07-tools-and-gate.md, 11-terminal.md, terminal-tui.md, parity.md, ADR-0038]
+---
+
+# PROP-0043: Read-only Bash in plan mode, enforced by the OS sandbox
+
+## Problem
+
+Plan mode refuses Bash entirely: `planRefusal` (`src/sessions/planMode.ts`) did not list `bash`,
+the terminal dropped it from the plan's active set (`planModeTools`), and a test pinned the refusal.
+A plan therefore could not check its claims with read-only commands such as `git log`, `git diff`,
+`rg` or `node --version`, although the plan instructions ask for evidence-grounded findings.
+
+## Affected rules
+
+- `INV-RUN-8`: "… it has no connectors, user questions, writes, commands or nested subagents." (about
+  plan research children; unchanged) and the plan instruction "Do not change files or remote data, run
+  commands, …".
+- `INV-GATE-3` / `INV-GATE-8`: default Bash writes inside the workspace; `outside` scope and Full
+  Permission can widen it.
+
+## Proposal
+
+A plan run (SDK sessions and the terminal) may call the model's `bash` tool. Every such call runs in
+a new **read-only scope** of the existing workspace sandbox (`core/workspaceSandbox.ts`):
+
+- Reads are as broad as default Bash. Writes are denied everywhere except `/dev/null`, `/dev/tty`,
+  and a private temp folder made for the call; `TMPDIR` points to it and it is removed afterwards.
+- No network. No signals outside the sandbox. On macOS no mach services at all, so a command cannot
+  act through system daemons (preferences, Apple Events, Launch Services). On Linux, `bwrap` adds
+  `--unshare-net --unshare-ipc` and a tmpfs over `/run`.
+- Nothing widens the scope: the Full Permission bypass and `workspaceWriteScope: 'outside'` are never
+  consulted. The gate refuses an `outside` request before approvals. The hard-link scan is skipped,
+  because the scope permits no workspace writes.
+- A missing sandbox fails closed, as for default Bash.
+- As defence in depth, the gate also refuses a short list of system-acting commands
+  (`PLAN_BASH_DENIED`: `sudo`, `osascript`, `open`, `launchctl`, `defaults`, `kill`, `ssh`, …) in any
+  segment of the command. The OS sandbox is the boundary; the list is not.
+
+The plan instruction says read-only shell inspection is allowed, writes and network fail, and the
+model must not work around a failed write. Unchanged: plan research children still have no Bash, a
+user `!` command still exits plan mode, and `!` is still refused while a plan request runs.
+
+## Alternatives
+
+- **Do nothing.** Plans stay unable to verify claims with commands.
+- **A command allowlist without the sandbox.** Easy to get around (`find -exec`, `rg --pre`,
+  `git -c core.pager=…`, `$(…)`, aliases), and every new tool needs a review. Rejected as the
+  boundary; kept only as a small denylist.
+- **Default workspace-scoped Bash in plan mode.** Would let a plan change the workspace.
+
+## Consequences
+
+Hosts need no change; plan mode reaches the runner through `Sessions`. The terminal keeps `bash` in
+its plan active set. No protocol, stored data or prompt prefix changes: the SDK tool list is
+unchanged and the instruction is the dynamic plan section. Builds and tests that write fail in plan
+mode, which is intended.
+
+## Migration
+
+None. It can be undone by removing `bash` from the plan gate.
+
+## Checks
+
+`src/core/workspaceSandbox.test.ts` (real sandbox: reads succeed; workspace, home and link writes
+fail; the temp folder works and is removed; a local TCP connection fails; widening callbacks are
+never called; win32 fails closed), `src/sessions/planMode.test.ts`, `src/sessions/sessions.test.ts`,
+`src/terminal/piExtension.lifecycle.test.ts`, `npm run prove`, and the App's checks. The Linux `bwrap`
+path needs an Ubuntu CI run.

package/docs/architecture/proposals/README.md

@@ -35,6 +35,45 @@ proposal is `Accepted`.
 
 | [PROP-0012](PROP-0012-release-baseline.md) | Public 1.0.0 distribution and generic browser ownership | Accepted; candidate implementation | INV-BND-2, 00, 07, 11, 13 | 2026-10-22 |
 
+| [PROP-0013](PROP-0013-resource-browser.md) | Unified terminal resource browser | Implemented; working tree verified | 03, 06, 09, 11 | 2026-10-22 |
+
+| [PROP-0014](PROP-0014-fullscreen-browser-tabs.md) | Full-screen browser with persistent section tabs | Implemented; working tree verified | 11, terminal-tui.md | 2026-10-23 |
+
+| [PROP-0015](PROP-0015-one-capability-surface.md) | One capability surface: the terminal and every host offer the same capabilities | Accepted | INV-BND-2, new INV-PAR, 00, 11, 14, AGENTS.md | 2026-10-23 |
+
+| [PROP-0016](PROP-0016-managed-worktrees.md) | Managed git worktrees in the terminal and every host | Harness/terminal in 4.0.0 candidate; App create integration, remaining actions PAR-012 | INV-BND-2, D-5, INV-STO-3, INV-SRV-1, 00, 02, 10, 11, 12, 14 | 2026-10-23 |
+
+| [PROP-0017](PROP-0017-page-annotations.md) | Page annotations captured in the headed browser or a host's web view | Harness/terminal in 4.0.0 candidate; App source pending native-gesture acceptance | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+
+| [PROP-0018](PROP-0018-annotation-queue-and-app-targets.md) | Inspector-style page notes, a fix queue to the agent, and app windows as capture targets | Harness/terminal in 4.0.0 candidate; App source present, native WKWebView acceptance pending | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+| [PROP-0019](PROP-0019-contextual-side-questions.md) | Harness-owned contextual side questions across surfaces | Implemented; working tree verified | INV-RUN-1/3/5, INV-GATE-1, INV-PLG-1/5, INV-CAP-1, INV-SRV-1/2, INV-PAR-1/2, 02, 04, 06, 07, 10, 11, 12, 14, ADR-0023 | 2026-10-24 |
+| [PROP-0020](PROP-0020-builtin-feature-plugins.md) | Built-in feature modules and namespaced plugin commands | Implemented; included in 4.0.0 candidate | INV-PLG-5/6, INV-TUI-2/7, INV-SRV-1, 06, 11, 13, 14 | 2026-10-24 |
+| [PROP-0021](PROP-0021-command-namespaces-and-duplicates.md) | Required built-in commands and duplicate command suppression | Implemented | INV-TUI-7, INV-PAR-1, 11, 14, ADR-0021 | 2026-10-24 |
+| [PROP-0022](PROP-0022-plan-only-questions.md) | Keep question tools available only in interactive plan mode | Implemented | INV-RUN-8, 02, 04, 06, 07, 11, 14, parity, ADR-0022 | 2026-10-24 |
+| [PROP-0023](PROP-0023-xagent-cli-name.md) | Rename the published CLI command to xagent | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0024 | 2026-10-24 |
+| [PROP-0024](PROP-0024-question-sketch-previews.md) | Add bounded ASCII sketch previews to question choices | Implemented; working tree verified | INV-RUN-3, INV-PAR-1/2, 02, 10, 11, 14, parity, App question contract and plan-mode docs, ADR-0025 | 2026-10-24 |
+| [PROP-0025](PROP-0025-contextual-question-wireframes.md) | Strict question columns and contextual ASCII wireframes | Implemented; working tree and isolated fixtures verified | INV-RUN-3, INV-PAR-1/2, 02, 11, 14, terminal-tui.md, parity, ADR-0026 | 2026-10-24 |
+
+| [PROP-0026](PROP-0026-connected-sketch-display.md) | Connect structural sketch lines in the terminal display | Implemented; working tree and isolated fixtures verified | 11, 14, terminal-tui.md, parity, ADR-0027 | 2026-10-24 |
+| [PROP-0027](PROP-0027-xingular-agent-product-identity.md) | Use Xingular Agent as the default Harness product identity | Accepted; implemented and verified | INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md, terminal-tui.md, ADR-0028 | 2026-10-24 |
+| [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
+| [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
+| [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+| [PROP-0031](PROP-0031-plugin-command-owner-namespaces.md) | Namespace plugin commands by owner | Implemented; Harness and App checks passed | INV-TUI-7, 06, 11, 14, terminal-tui.md, README.md, ADR-0021, ADR-0031 | 2026-10-25 |
+| [PROP-0032](PROP-0032-planning-quality.md) | Evidence-grounded planning with read-only research delegation | Implemented; live model pilot pending authorization | INV-RUN-8, INV-GATE-3, INV-CAP-1, 02, 06, 07, 14, parity, ADR-0033 | 2026-10-25 |
+| [PROP-0033](PROP-0033-compaction-plan-checkpoints.md) | Rehydrate bounded run checkpoints after compaction | Accepted; implemented | INV-PRM-1/4/10, INV-RUN-8/12, 02, 04, 11, 14, ADR-0032 | 2026-10-25 |
+| [PROP-0034](PROP-0034-conversation-fast-mode.md) | Conversation-scoped provider fast mode | Proposed | INV-RUN-1/3, INV-PAR-1/2, 02, 09, 10, 11, 12, 14, parity, App thread runtime settings | 2026-10-25 |
+| [PROP-0035](PROP-0035-retain-subagent-status.md) | Retain terminal subagent status until the next run | Implemented; initial PTY failure resolved; full verifier passed at three sizes (2026-11-19) | 11-terminal.md, terminal-tui.md | 2026-10-25 |
+| [PROP-0036](PROP-0036-first-class-harness-commands.md) | First-class Harness terminal commands | Implemented | INV-PLG-10, INV-TUI-7, 06, 11, 14, terminal-tui.md, parity, ADR-0034 | 2026-10-25 |
+| [PROP-0037](PROP-0037-workspace-write-boundary.md) | Default filesystem writes to the active project workspace | Implemented | INV-GATE-1/3/8, INV-RUN-1, INV-TUI-8, 02, 04, 07, 10, 11, 12, 14, parity | 2026-11-19 |
+| [PROP-0038](PROP-0038-annotate-open-shadow-roots.md) | Annotate inside open shadow roots | Implemented | 13-world-tools.md, note target, PROP-0017, PROP-0018, parity | 2026-10-25 |
+| [PROP-0039](PROP-0039-workspace-boundary-hardening.md) | Harden workspace writes against inode escapes and unverified retries | Accepted; implementation validated on macOS, Linux validation pending | INV-GATE-3/8, INV-TUI-8, 02, 07, 11, 14, parity | 2026-10-26 |
+
+| [PROP-0040](PROP-0040-one-launch-path.md) | One launch path and command contract across front ends | Accepted; implementation in progress | 01–04, 06–07, 10–14, parity | 2026-11-19 |
+| [PROP-0041](PROP-0041-bounded-work-slices.md) | Bounded work slices, a durable checkpoint, and a stall guard for long replies | Implemented; terminal card, App presentation and /slices open (PAR-004) | INV-RUN-2/3/4/12, INV-PRM-1/2/4/5/10, INV-GATE-2, INV-STO-3, INV-PAR-1/2, 02, 04, 07, 10–12, 14, parity | 2026-10-26 |
+| [PROP-0042](PROP-0042-usage-and-provider-limits.md) | Usage analytics and provider limits as a built-in capability | Accepted; implemented | INV-MEM-5/6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02, 06, 08–12, 14, parity, ADR-0037 | 2026-10-26 |
+| [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
+
 Numbers are four digits, start at `0001`, and are never reused.
 
 ## Template

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -34,7 +34,7 @@ Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatibl
 socket/controller bridge and its final gate. Keep the private control claim in process memory
 across native session replacement, revalidate prepared resource trust before every load, and
 scope native resume/import to the terminal's original working folder. Put unavoidable Pi
-implementation imports in one adapter checked against the pinned 1.2.0 version.
+implementation imports in one adapter checked against the pinned Pi version.
 
 Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
 commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and

package/docs/decisions/ADR-0009-xharness-command.md

@@ -1,15 +1,15 @@
 ---
 id: ADR-0009
 title: Publish the Harness CLI as xharness
-status: accepted
+status: superseded
 created: 2026-10-22
-updated: 2026-10-22
+updated: 2026-10-24
 related: [PROP-0005]
 supersedes: null
-superseded_by: null
+superseded_by: ADR-0024
 ---
 
-# ADR-0009 — Publish the Harness CLI as xharness
+# ADR-0009 — Publish the Harness CLI as xharness (superseded)
 
 ## Context and decision drivers
 
@@ -35,4 +35,5 @@ subcommands, data/state directory names, and `XINGULAR_HARNESS_*` environment va
 
 - The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
 - CI, the packed-tarball smoke test and the npm publication blocker are recorded in
-  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md).
+  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md). The executable-name decision
+  is superseded by [ADR-0024](ADR-0024-xagent-command.md).

package/docs/decisions/ADR-0014-public-release-baseline.md

@@ -9,8 +9,9 @@ updated: 2026-10-22
 # ADR-0014 — A compiled public SDK and explicit 1.0.0 baseline
 
 The user approved [PROP-0012](../architecture/proposals/PROP-0012-release-baseline.md) through the
-release implementation plan. Keep @xingular/harness and xharness, use Apache-2.0 for original
-code, publish compiled ESM/declarations, and preserve upstream notices and historical releases.
+release implementation plan. Keep @xingular/harness and the then-current `xharness` executable, use
+Apache-2.0 for original code, publish compiled ESM/declarations, and preserve upstream notices and
+historical releases. The executable-name portion was superseded by [ADR-0024](ADR-0024-xagent-command.md); the other release-baseline decisions remain.
 
 Generic isolated browser execution belongs in the foundation; App browser presentation, tab
 sharing and OS/computer integration remain with the host. No application concept or object is

package/docs/decisions/ADR-0015-resource-browser.md

@@ -0,0 +1,28 @@
+# ADR-0015 — One terminal browser for resources and discovery
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-22).
+Related: [PROP-0013](../architecture/proposals/PROP-0013-resource-browser.md),
+[source study](../study/tui-resource-browser.md).
+
+## Context
+
+Skills, plugins, Hub items and variant additions have different entry points and misleading
+availability labels. Users need to identify what exists, what this session can use, and what changes later.
+
+## Decision
+
+Use a shared responsive browser with section shortcuts, Installed/Discover views, provenance and
+inspection before management. Join saved configuration with actual runtime resources; never infer
+loaded state from attachment settings or the latest variant head. Keep the loader, gate and service
+ownership intact. Show foundation and variant as different ownership layers.
+
+## Alternatives
+
+Separate pages retain navigation fragmentation. A single combined remote/local list confuses
+installation with availability. A full editor expands the task beyond browse/manage.
+
+## Consequences
+
+The browser adds a protected service adapter and focused navigation state. Resource reads are bounded,
+credentials stay masked, and installing does not activate resources. Existing commands remain shortcuts.
+Implementation and verification evidence belong in the terminal guide, not in this decision record.

package/docs/decisions/ADR-0016-fullscreen-browser-tabs.md

@@ -0,0 +1,31 @@
+# ADR-0016 — Full-screen browser with persistent resource tabs
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-23).
+Related: [PROP-0014](../architecture/proposals/PROP-0014-fullscreen-browser-tabs.md),
+[ADR-0015](ADR-0015-resource-browser.md).
+
+## Context
+
+The unified browser's centered layout and nested section/detail navigation leave little space
+for inventory and inspection. The user wants one full-page workspace with resource-section tabs.
+
+## Decision
+
+Resource-browser commands use a full-screen surface with persistent section tabs. Wide terminals
+show inventory beside an inspector containing metadata, actions and content. Compact terminals
+show inline detail views under the same tab strip. Tab moves focus, arrows change a focused tab,
+and mouse tab selection targets the section directly.
+
+TerminalPage declares its presentation and optionally supports direct tab selection. Centered
+presentation remains the default for other pages. Resource services keep their existing ownership.
+
+## Alternatives
+
+Keeping the centered panel restricts working space. Replacing the list with details at all widths
+loses inventory context. Variant c1–c8 tabs do not match the selected resource-navigation intent.
+
+## Consequences
+
+The browser owns responsive inventory/inspector focus and preserves section search and selection.
+Small terminals use compact tab navigation. There are no storage or protocol changes.
+Verification belongs in the terminal guide and its automated page and PTY checks.

package/docs/decisions/ADR-0017-one-capability-surface.md

@@ -0,0 +1,34 @@
+# ADR-0017 — One capability surface for the terminal and every host
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0015](../architecture/proposals/PROP-0015-one-capability-surface.md),
+[PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[PROP-0017](../architecture/proposals/PROP-0017-page-annotations.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Capabilities grew in the App alone, so the Harness terminal could not do what the App did, and
+ownership between the repositories was unclear. The owner wants the App to be a richer
+presentation of the Harness, with the same capabilities as the terminal, and room for future
+host-only surfaces such as interactive agent output.
+
+## Decision
+
+Every user capability is a Harness capability with a terminal surface (INV-PAR-1, INV-PAR-2).
+Capabilities that need an operating-system object only a host has define a generic contract and a
+terminal fallback (INV-PAR-3). Host-only surfaces own no capability and are registered by the host
+with an owner decision (INV-PAR-4). Managed worktrees and page annotations move into the Harness
+under PROP-0016 and PROP-0017. Orchestration across agents (organizations, routed chats, group
+chats, delegated work queues) is not a Harness capability; the App removes it and keeps it only in
+an archived version.
+
+## Alternatives
+
+Keeping the App as the full product leaves two products. Identical front ends cannot accommodate
+presentation a terminal cannot show. Doing nothing lets the gap grow.
+
+## Consequences
+
+New user features start in the Harness with a terminal surface. The register `docs/parity.md`
+tracks gaps until both surfaces pass. Hosts keep native bridges, windows and presentation.