@xingular/harness 2.0.0 → 2.0.1-unstable

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/PROP-0044-work-slice-defaults.md

@@ -0,0 +1,93 @@
+---
+id: PROP-0044
+title: Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap
+status: Accepted
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-RUN-13, 02-sessions-and-runs.md, 10-server-protocol.md, 11-terminal.md, PROP-0041]
+---
+
+# PROP-0044: Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap
+
+## Problem
+
+`DEFAULT_SLICE_POLICY` (`src/sessions/workSlice.ts`) and `INV-RUN-13` set 160 tool calls, 40 minutes
+and 320 000 new tokens, whichever comes first. Two of those defaults are wrong for ordinary work.
+
+- **The token cap is the earliest limit, and it is not the bound it claims to be.** Its own comment
+  called 320 000 "a safety net, not the bound", yet it counts new input, cache writes and output, so a
+  few large reads in a big context cross it before the work is done. The "Confirm plan model support"
+  thread counted 76 807 new tokens after four requests, and `workSlice.test.ts` still carried a case
+  asserting a 320k stop. A cap that fires on reading is a false stop, and the stall rules — not the
+  token count — are what detect an unbounded reply.
+- **40 minutes is tighter than the field and tighter than the evidence.** The measured failure in
+  STUDY-0003 was a reply that ran 114 minutes with no text and 448 calls, not one that ran 40 minutes.
+  OpenHands allows 500 agent steps per run by default; Claude's Agent SDK has no default `maxTurns`;
+  Cursor documents no tool-call limit; SWE-agent's caps are benchmark stops ($3, 1800 s) that
+  auto-submit and exit. A checkpoint every 40 minutes turns one healthy task into a series of runs
+  without a measured benefit.
+
+The rule stays: a reply is bounded and hands off. What changes is where the boundary sits.
+
+## Affected rules
+
+- **INV-RUN-13** says: "The foundation defaults are 160 tool calls, 40 minutes and 320 000 new tokens,
+  whichever comes first." The invariant's requirement — a bounded reply, a handoff at the limit and a
+  continuation — is unchanged; its stated numbers and the default token cap change.
+- **PROP-0041** §1 states the same numbers and §Consequences says "a checkpoint every ≤ 40 minutes";
+  both are corrected to point here.
+
+## Proposal
+
+`DEFAULT_SLICE_POLICY` becomes:
+
+| Setting | Was | Now |
+|---|---|---|
+| `maxToolCalls` | 160 | **320** |
+| `maxMinutes` | 40 | **60** |
+| `maxNewTokens` | 320 000 | **0** (no cap) |
+| `maxSlices` | 8 | 8 (unchanged) |
+| `continue` | true | true (unchanged) |
+
+- Calls and the clock are the bound, whichever comes first: about 80 minutes of ordinary work at 15 s a
+  call, with 60 minutes as the ceiling.
+- A token cap stays available to whoever wants a cost ceiling: `workSlice.maxNewTokens` per run, still
+  counted on new input, cache writes and output and never on the cached prefix.
+- Nothing else changes: the refusal and `checkpoint_write`, the exemption for a handoff call, the
+  stall rules and their per-reply reset, the terminal's behaviour, and automatic continuation.
+
+## Alternatives
+
+- **Do nothing.** Rejected: the token cap was the first limit a large read crossed, and its stop is
+  visible to the person as an arbitrary end of a useful reply.
+- **Keep a 320 000 safety net and raise only the calls and the clock.** Rejected: the same false stop
+  stays, and two limits that are never reached in ordinary work are enough.
+- **Turn the guard off by default.** Rejected for now: the stall rules are the evidence-backed part
+  (repeated identical calls, repeated failures, edit churn, compaction thrash), and the budget itself
+  is what bounds a reply. Only its size changes.
+- **Bound cost in dollars instead of tokens.** Not adopted here: the harness records cost per request,
+  but a dollar ceiling belongs with the account's usage limits (`usage/limits`, PROP-0042), not with a
+  reply's work slice.
+
+## Consequences
+
+- A healthy task reaches its first checkpoint after roughly 80 minutes of ordinary work instead of 40,
+  and no token count ends a reply on its own. The longest a task runs unattended is still eight slices,
+  so the slice cap now allows up to about eight hours instead of about five.
+- With no token cap, only calls and time bound an expensive reply; a person who wants a token ceiling
+  sets one, and the heartbeat still reports `steps` against `maxToolCalls`.
+- No stored-data, protocol or event change: an absent `workSlice` simply resolves to the new defaults,
+  and a run already recorded keeps the policy it ran under.
+
+## Migration
+
+None. Undo by restoring the three values in `DEFAULT_SLICE_POLICY`, or by passing `workSlice` on
+`sessions.run`. A continuation inherits the policy as it always did.
+
+## Checks
+
+- `npx vitest run src/sessions/workSlice.test.ts src/sessions/sessions.test.ts` (the defaults
+  assertion and the limit-selection test change with the values; the token-cap test keeps an explicit
+  override)
+- `npm run typecheck`, `npm test`, `npm run prove`
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `cd src-tauri && cargo test`

package/docs/architecture/proposals/PROP-0045-rename-checklist-to-todo.md

@@ -0,0 +1,132 @@
+---
+id: PROP-0045
+title: Rename the run checklist to todo and add the /todo command
+status: Accepted; implemented
+created: 2026-10-26
+updated: 2026-10-26
+affects: [02-sessions-and-runs.md, 04-prompt.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, parity.md, terminal-tui.md, README.md, PROP-0006]
+---
+
+# PROP-0045: Rename the run checklist to todo and add the /todo command
+
+## Problem
+
+One run concept is named "checklist": the `checklist_write` tool, its `checklist.updated` event,
+`ChecklistItem`, `checklistOf`, the `todo` list's `runs.checklist` method, the `checklist` field of
+`runs.continuation`, the `checklist` plugin, and the terminal's checklist block and `checklist`
+telemetry. Every agent framework a person meets elsewhere calls the same idea a todo list, and
+Claude Code's `/todos` made the word familiar: `todo`, `todo_write`, `/todo`. PROP-0006 chose
+"checklist" explicitly to avoid an application concept (`PROP-0006-run-checklist.md:28`), but
+"todo" is generic vocabulary, not a product name, and the current name makes the tool harder to
+recognise for both the model and the person.
+
+The list is also only visible where the model last wrote it: the terminal transcript and (nowhere) in
+the App. A person who scrolled past a write, resumed a session, or is watching a long reply has no
+way to ask for the current list. The terminal already has a slash-command surface for this kind of
+read (`/help`, `/subagents`, `/trajectory`); there is no `/todo`.
+
+## Affected rules
+
+- **02-sessions-and-runs.md, Data** defines `checklist.updated` and `checklistOf(events)`.
+- **04-prompt.md** defines the Progress paragraph that names `checklist_write`.
+- **07-tools-and-gate.md** defines `checklistTool` and its event.
+- **10-server-protocol.md** defines `runs.checklist`.
+- **11-terminal.md** defines the checklist block, the telemetry call and the terminal's tool.
+- **14-surfaces-and-parity.md** and **parity.md** (PAR-001) define the terminal and App surfaces.
+- No invariant's rule changes: the tool remains read-only and plan-safe, the event remains a
+  whole-list replacement, and the list remains one bounded run event. Only the names and one added
+  read command change.
+
+## Proposal
+
+### 1. The concept is named todo
+
+| Was | Becomes |
+|---|---|
+| tool `checklist_write` | `todo_write` |
+| event `checklist.updated` | `todo.updated` |
+| `ChecklistItem`, `checklistItemSchema`, `MAX_CHECKLIST_ITEMS` | `TodoItem`, `todoItemSchema`, `MAX_TODO_ITEMS` |
+| `checklistOf`, `describeChecklist`, `checklistTool` | `todoOf`, `describeTodo`, `todoTool` |
+| plugin id `checklist`, title "Checklist" | plugin id `todo`, title "Todo" |
+| method `runs.checklist { runId }` | `runs.todo { runId }` |
+| `Continuation.checklist` | `Continuation.todo` |
+| terminal telemetry `checklist` | `terminal.todo` |
+| transcript kind `checklist`, header "Checklist" | kind `todo`, header "Todo" |
+| `TerminalSubagentActivity.checklist` | `.todo` |
+
+The tool keeps its behaviour: the model sends the whole list, the latest event replaces every
+earlier one, at most 50 items, `pending`, `in_progress` and `completed`, read-only for the gate and
+allowed in plan mode. The prompt's Progress paragraph asks for a todo list in the same places.
+
+### 2. `/todo` shows the current list
+
+`/todo` is a core command (`src/commands/registry.ts`), `group: 'Inspect'`, `kind: 'session'`,
+`methods: ['runs.todo']`, with `/checklist` as a compatibility alias for one release.
+
+- It reads the latest non-side-question run of the current native session and returns that run's
+  latest todo. It makes no model request, asks for no approval, and is available in plan mode.
+- The terminal appends a snapshot card to the transcript: `Todo · n of m done`, then one row per
+  item with the existing glyphs and colours (`✓` completed, `●` in progress, `○` pending). An empty
+  list is a one-line notice, not an empty card.
+- The App offers the same read through `runs.todo` as a read-only picker with the same marks. It does
+  not render each `todo_write` in its transcript; that presentation difference is recorded in
+  PAR-001.
+
+### 3. Compatibility
+
+Stored run events are never rewritten. For one minor release:
+
+- `runEventTypeSchema` accepts `checklist.updated` beside `todo.updated`, both with the same payload;
+  `todoOf` reads both. New events are written only as `todo.updated`.
+- A replayed native history whose tool call is `checklist_write` still renders the todo card.
+- `runs.checklist` remains as a deprecated alias returning the same list as `runs.todo`.
+- `runs.continuation` returns `todo` and keeps `checklist` as a deprecated mirror field.
+- A pinned capability set containing `checklist_write` is read as `todo_write`, so an interrupted
+  run recorded before the rename can still continue with a todo tool.
+- The exported `checklistOf` and `CHECKLIST_WRITE` names stay as deprecated aliases for embedders.
+
+The aliases and the legacy event type can be removed in the next major release.
+
+## Alternatives
+
+- **Rename only the labels the person sees.** Rejected: the tool name the model sees, the event, the
+  method and the docs would disagree, which is the drift the specification exists to prevent.
+- **Keep both names indefinitely.** Rejected: two names for one concept in the prompt and the
+  protocol, and a permanent compatibility branch. One release is enough for stored data that is
+  never rewritten.
+- **Rewrite stored events to the new type.** Rejected: `events.jsonl` is append-only evidence; a
+  read alias is enough and cannot corrupt a run.
+- **Make `/todo` a live panel or a full-screen page.** Rejected for this change: a transcript
+  snapshot matches `/help`, reuses the existing block, and leaves the person's scrollback intact.
+  A live panel can be a later presentation change; it is not needed to show the list.
+- **Do nothing.** Rejected by the owner's request and by the missing read surface.
+
+## Consequences
+
+- One tool name and one prompt paragraph change, so the compiled tool manifest and the provider
+  cache prefix change once. The cost is measurable only with real requests (`INV-PRM-8`), and the
+  change does not alter any model-visible behaviour besides the name.
+- Applications built on the harness keep working through the method, field and capability aliases;
+  they should move to the new names. The App's event schema accepts both event types, so old run logs
+  keep displaying.
+- Runs created before the rename keep their recorded events. `todoOf` and the terminal renderer read
+  them without a rewrite.
+- PAR-001 narrows: both surfaces can now show the current todo; the App still does not draw an inline
+  block for each write.
+
+## Migration
+
+No data migration and no file rewrite. Old events, old pinned capability sets and old native
+histories are read through the aliases above. Rolling back is reverting the commit; new
+`todo.updated` events would then need a reverse alias if they were already written, so the rollback
+is safe only before new runs write the event.
+
+## Checks
+
+- `npm run typecheck`, `npm test`, `npm run prove`.
+- New tests: the todo tool, a legacy `checklist.updated` read, a legacy pinned capability, the
+  `runs.todo` method and its alias, the terminal `/todo` card, and a replayed `checklist_write` call.
+- `python3 scripts/verify-terminal.py --todo-only` at 80x24 and 100x30: the card, the alignment of
+  wrapped rows, and no model request for `/todo`.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`,
+  `cd src-tauri && cargo test`.

package/docs/architecture/proposals/PROP-0046-progress-aware-stall-guards.md

@@ -0,0 +1,82 @@
+---
+id: PROP-0046
+title: Progress-aware stall guards and bounded plan research children
+status: Implemented
+created: 2026-10-27
+updated: 2026-10-27
+affects: [INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039]
+---
+
+# PROP-0046: Progress-aware stall guards and bounded plan research children
+
+## Problem
+
+The stall guard currently has a broad 25-call rule: it nudges after substantive calls without a file change or passing check. It is disabled for plan-mode research, but remains active for ordinary runs. A long, legitimate sequence of reads can be stopped in normal mode but not plan mode; the rule imposes a mode-specific file/check-progress boundary rather than detecting a loop.
+
+Two targeted rules also ignore successful code changes. Failed-check counts and identical Bash-check calls can persist after an edit, so a fixed test command may be blocked even though its input code has changed. The per-file edit-churn count is incremented in `tool_call`, before the edit runs, so a denied or failed attempt can count as an edit.
+
+Finally, plan-research children receive only the explicit read-only research tool intersection, which excludes `checkpoint_write` (`src/agents/planResearch.ts`). `Sessions` installs the work-slice guard only when that tool is in the frozen capability set (`src/sessions/sessions.ts`). These children consequently lack the call/time boundary that the work-slice proposal says applies to subagent runs. The terminal guide also says plan-mode shell commands are unavailable even though the parent may run OS-sandboxed read-only Bash (`docs/terminal-tui.md`; PROP-0043).
+
+## Affected rules
+
+- **INV-RUN-13** currently says: “The file-change/check-based no-progress detector does not apply to plan-mode read-only research.” This proposal removes the detector for all runs, rather than preserving a mode-specific exception. It also clarifies how successful edits affect the remaining stall counters and how a bounded child without `checkpoint_write` hands back.
+- **PROP-0041, §4 Stall guard** currently includes “25 non-bookkeeping tool calls without a file change or passing check,” counts edit attempts before execution, and describes repeated Bash failures without resetting for a changed code state. Its stall-guard description must match the new rule.
+- **INV-RUN-8** remains unchanged: plan-research children keep their existing frozen, read-only capability intersection, with no connectors, questions, writes, commands or nested subagents. The child work-slice bound does not add a tool or widen that set.
+- **`docs/terminal-tui.md`** must distinguish the parent's sandboxed read-only Bash from the child's no-command restriction.
+
+## Proposal
+
+### 1. Remove the broad no-progress trigger
+
+Remove the 25-call file-change/check detector from every run. Remove its counter and plan-mode exception; do not replace it with another general “no file change” threshold. The tool-call/time work-slice budget remains.
+
+Keep the targeted stall protections: the same exact call signature still receives one nudge at its existing threshold and ends the reply on a subsequent trigger; the same Bash check failing twice remains a trigger; per-file edit churn remains limited to four successful edits without a passing check; and the existing third-compaction thrash guard remains. Todo bookkeeping remains exempt from repeated-call detection and remains counted toward the work-slice tool-call budget.
+
+### 2. Tie check retries and edit churn to observed results
+
+Use the post-execution `tool_result` for native `edit` and `write` tools. A result with `isError === false` and a path is a successful edit for this rule; a blocked or failed call does not count. After four successful edits to one path without a passing check, the next edit attempt for that path receives the existing nudge/block, and a further trigger ends the slice. A passing check continues to clear the per-file edit counts.
+
+A successful native edit/write starts a fresh check-retry episode: clear failed-check counts, the exact-repeat count for Bash check calls, and the pending one-shot nudge so the same check can run against changed code. Exact-repeat protection remains active for unchanged code and for other calls. The successful-edit counts used by the per-file churn rule are not cleared by this reset; only a passing check clears them. Failed or denied edits reset none of these counters.
+
+The cross-surface success signal is the tool result, not a byte-level file comparison. The guard must count only a confirmed non-error result and use its path; no filesystem watcher or new event schema is introduced.
+
+### 3. Bound read-only plan-research children
+
+When work-slice policy is enabled, attach the existing guard to plan-research child runs even when their frozen capabilities omit `checkpoint_write`. Use the existing policy/defaults (320 calls and 60 minutes, no token cap); inherit an explicit parent policy override. Plan and subagent runs still do not auto-continue.
+
+A child without `checkpoint_write` must not be told to call an unavailable tool. The first budget or stall refusal tells it to stop using tools and return a concise partial research report; if it attempts another tool, the existing termination rule applies. The runner's existing evidence-derived checkpoint records the handoff when the model did not write one. The child receives no additional tool or connector permissions. This proposal bounds each child, not the aggregate number of siblings; the existing parent-controlled fan-out is unchanged. The time limit remains checked at tool-call boundaries and is not a cancellation timer for an in-flight tool.
+
+### 4. Keep plan-mode action restrictions
+
+Do not enable generic browser clicks or `mcp_call_tool` in plan mode. Existing per-call safety classifications and read-only restrictions remain unchanged. A future need for connected-app research must add server-validated read-only classification rather than admitting the generic broker call.
+
+Clarify `docs/terminal-tui.md`: an interactive plan parent may run Bash in the OS-enforced read-only sandbox (PROP-0043); plan-research children still cannot run commands. Writes, network access and generic connected-app actions remain unavailable in plan mode.
+
+## Alternatives
+
+- **Keep the 25-call trigger outside plan mode.** Rejected: it still mistakes legitimate read/research sequences for lack of progress and preserves an arbitrary mode distinction.
+- **Remove all stall protections.** Rejected: exact repeated calls, repeated failing checks, edit churn, compaction thrash detection and the independent work-slice budget remain useful, targeted bounds.
+- **Give plan-research children `checkpoint_write` or broader tools.** Rejected: the existing derived-checkpoint path is sufficient and preserves the frozen read-only capability intersection.
+- **Add a tighter child-only budget or sibling concurrency cap.** Deferred: this change applies the established work-slice policy per child; aggregate fan-out remains a separate decision.
+- **Detect byte-level file changes.** Rejected for this change: the post-execution native tool result is the consistent signal available to the shared guard across surfaces.
+
+## Consequences
+
+A run may make any number of distinct reads without hitting a file/check-based no-progress stall, subject to the work-slice budget and the retained targeted loop protections. After a successful edit, the same Bash check can be retried against the changed code; unsuccessful edit attempts do not consume the four-edit churn allowance.
+
+Plan-research children can stop at the same call/time boundary without receiving a new capability. A child that reaches the bound is recorded as an interrupted slice with the runner-derived checkpoint and can return partial findings; it is not automatically restarted. No server method, run-event schema, stored-data layout or App presentation changes are required. Existing plan-mode browser and connector restrictions remain in force.
+
+This lasting foundation guardrail decision is recorded in [ADR-0039](../../decisions/ADR-0039-progress-aware-stall-guards.md).
+
+## Migration
+
+None. Existing run records and checkpoints remain readable. The proposal changes only future run behavior; no event or capability snapshot is rewritten. A child stopped at its slice boundary uses the existing `checkpoint` event and terminal reason contracts.
+
+## Checks
+
+After acceptance:
+
+- Focused Harness tests: `npx vitest run src/sessions/workSlice.test.ts src/sessions/sessions.test.ts src/sessions/subagentService.test.ts src/sessions/planMode.test.ts`.
+- Add regressions for more than 25 distinct reads in normal and plan runs; unchanged exact repeats; failures followed by a successful edit and a retry of the same Bash check; failed/blocked edits not counting; four successful edits to one path; and a plan child receiving a work-slice bound without gaining `checkpoint_write` or other tools, using a derived checkpoint and no auto-continuation.
+- Run Harness `npm run typecheck`, `npm test`, `npm run prove`, and `git diff --check`.
+- Run Xingular Agent `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.

package/docs/architecture/proposals/PROP-0047-plugins-hub-separation.md

@@ -0,0 +1,122 @@
+---
+id: PROP-0047
+title: Separate local plugin management from Community Hub discovery
+status: Implemented
+created: 2026-10-27
+updated: 2026-10-27
+affects: [INV-MCP-4, INV-TUI-2, INV-TUI-4, INV-PAR-1/2, 06-plugins-and-capabilities.md, 09-accounts-and-connectors.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity.md]
+---
+
+# PROP-0047: Separate local plugin management from Community Hub discovery
+
+## Problem
+
+`/plugins` and `/hub` currently open the same `BrowserPage` (`src/terminal/tui/commandPages.ts`),
+with different initial filters. That page combines local plugin controls with public catalog
+browsing. Separate `PluginsPage` and `HubPage` implementations already exist but are not routed by
+the commands. The App similarly presents local plugins and the public catalog in one Capability
+Hub view.
+
+The distinction matters operationally: direct plugin operations use `plugins.install`,
+`plugins.update` and `plugins.remove`; catalog installs use exact Hub versions and create receipts
+through `Hub.install`. A direct `plugins.remove` currently removes the package without updating a
+Hub receipt (`src/server/methods.ts`, `src/plugins/install.ts`), whereas `Hub.uninstall` owns both
+package removal and receipt cleanup (`src/hub/hub.ts`). Pi packages also have no JSON payload to
+preview (`Hub.preview` rejects them), and a failed remote refresh must not make cached catalog data
+look current or successful.
+
+The requested product behavior is: `/plugins` manages local installed plugins and their package
+lifecycle; `/hub` is a separate public-catalog page showing Community entries across supported
+catalog types. Hub's Installed view retains receipts from every channel, labeled by channel. Opening
+Hub first shows cached/bundled entries and then refreshes remotely, retaining visible origin and
+stale/error status.
+
+## Affected rules
+
+The current terminal-page contract says that `/plugins` and `/hub` are shortcuts into the unified
+resource browser (`docs/architecture/11-terminal.md`, “Resource browser”):
+
+> `/skills`, `/plugins`, `/connections` (`/mcp`), `/tools`, `/hub` and `/components` are shortcuts into that browser.
+
+The terminal guide also says the resource sections share Installed/Discover and source filters, and
+that `/hub` selects Discover (`docs/terminal-tui.md`, “The Harness resource browser”). This proposal
+replaces those two route-specific statements; the broad `/harness` browser remains available.
+
+Receipt handling must continue to obey **INV-MCP-4**:
+
+> Hub installation grants no attachment, trust, credential or permission. Writes are serialized;
+> existing registry files are never overwritten; uninstall removes only the exact receipt's
+> resources and revokes its attachment choices.
+
+The proposal does not weaken **INV-PLG-3**: package installation runs no code and grants no
+attachment, trust, credential or permission. Nor does it change **INV-TUI-4**: terminal mutations
+continue through the control-key-protected routes. **INV-PAR-1/2** continue to require the same
+capabilities and acceptance on terminal and host surfaces.
+
+## Proposal
+
+1. Route the direct terminal commands to distinct pages: `/plugins` to the local plugin manager and
+   `/hub` to the public Hub catalog. Keep `/harness` as the broader resource browser. The pages are
+   distinct presentations, not new capabilities or loaders.
+2. The Plugins page manages local installed packages and their contributions: inventory, switching,
+   code trust, settings, direct package installation, update and removal. Public catalog discovery
+   is not part of this page. Ordinary local packages use the existing `plugins.*` services.
+3. A package recorded in a Hub receipt is owned for removal by Hub: a `plugins.remove` request for
+   that package must go through Hub's receipt-aware uninstall path so the package and its exact
+   receipt cannot diverge. Do not use a floating `plugins.update` for a Hub-managed package. Its
+   replacement must be an explicit operation against an exact catalog version and must retain
+   receipt ownership; if no safe replacement operation exists, require uninstall then install of the
+   selected exact version.
+4. The Hub page's Catalog view contains Community entries only, across catalog types supported by
+   the active product. This does not restore the deprecated agent-template application flow. The
+   Installed view contains receipts from all channels with the entry's channel visible; existing
+   Official receipts therefore remain reviewable and uninstallable. The underlying catalog and
+   `hub.list` contract remain unfiltered for other callers.
+5. On Hub entry, load cached/bundled content first, then request a remote refresh. Keep the last
+   known entries and show whether they are remote, cached or bundled, when they were refreshed, and
+   any refresh error. An explicit refresh remains available. Keep bounded payload Preview for
+   registry/document entries, but do not expose Preview for Pi packages; install and uninstall
+   remain pinned to the selected receipt/catalog version.
+6. Host surfaces use the same catalog filtering, receipt, refresh and lifecycle semantics in their
+   own page layouts. No host-only surface, new loader, data store or server response schema is added.
+
+## Alternatives
+
+- **Keep the shared browser for both commands.** Rejected: it leaves local management and public
+  discovery coupled, contrary to the requested ownership and page distinction.
+- **Make `/hub` Community-only but keep `/plugins` as the browser's Installed/Discover shortcut.**
+  Rejected: public discovery would remain inside the command meant for local plugin management.
+- **Hide non-Community receipts in Installed.** Rejected: it would strand existing Official Hub
+  installations from the dedicated management view.
+- **Do nothing.** Rejected: it retains the current refresh-status and package-lifecycle gaps.
+
+## Consequences
+
+- The terminal and host frontends need separate Plugins and Hub presentations, but continue to call
+  the same Harness-owned services. Their layouts need not match.
+- `plugins.remove` behavior changes only for a package owned by a Hub receipt: Hub remains the sole
+  writer that removes that receipt. Its method shape and response schema need not change.
+- Community filtering is a presentation rule. Catalog metadata, receipts, and the unfiltered Hub
+  service remain unchanged. Existing official receipts require no migration.
+- The public catalog currently has a Community skill but no Community Pi-package entry. This change
+  does not publish or invent a package; the Community plugin list stays empty until a publisher adds
+  a valid entry.
+
+## Migration
+
+No data migration. Existing receipts from all channels remain in storage and appear in Installed with
+their channel label. Existing plugin trust, attachment, settings and package data remain unchanged.
+The command names and protected service routes remain stable; only the direct-page routing and
+receipt-aware removal behavior change. `/harness` retains its broad browser.
+
+## Checks
+
+- Harness route and page tests: distinct command destinations; Community-only catalog results;
+  all-channel Installed receipts; cache-first refresh and visible fallback status; bounded
+  registry/document Preview with no Pi-package Preview; and receipt-aware removal/update behavior.
+- Harness: `npm run typecheck`, `npm test`, and `npm run prove` after changing the server method.
+- Host/App tests: matching route, filtering, refresh and receipt behavior; then App
+  `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`, and
+  `cd src-tauri && cargo test`.
+- Inspect isolated terminal and host screens at compact and wide sizes. Tests use fixtures; do not
+  install a real package or make a model request for verification.