@xingular/harness 1.2.0 → 1.3.1-unstable.1

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

@@ -59,8 +59,9 @@ mechanism below is **run execution**, which the harness owns.
 
 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,
+- `workSlice.enabled` true; `workSlice.maxToolCalls` 320, `workSlice.maxMinutes` 60,
+  `workSlice.maxNewTokens` 0, so no token cap by default (the values were raised by PROP-0044).
+  `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
@@ -120,20 +121,29 @@ A foundation extension (`src/sessions/workSlice.ts`), registered where the compa
 - 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.
+  - the same signature 3 times (`checkpoint_write` and `session_name` are handoff calls when a
+    checkpoint is available; `todo_write`, `wait_subagents` and `subagents.*` polling are exempt);
+  - the same Bash check failing twice;
+  - four successful native `edit`/`write` results on one path without an intervening passing check;
+    the next edit attempt is refused, and a further trigger ends the slice;
+  - context-compaction thrash at the third compaction.
+- Only a `tool_result` with `isError === false` and a path counts as a successful edit or write. A
+  failed or blocked attempt consumes no edit-churn allowance. A successful edit/write clears failed
+  check counts, exact-repeat counts for Bash check calls, and the pending nudge so that a fixed check
+  may run against changed code. It leaves per-file edit counts and exact-repeat counts for other
+  calls intact. A passing check clears edit churn and the reply's repetition state.
+- There is no general 25-call file-change/check no-progress trigger. The work-slice call/time budget
+  and the targeted repeated-call, repeated-failing-check, edit-churn and compaction-thrash protections
+  remain. `todo_write` is excluded from repeated-call detection and does not reset loop state, but it
+  remains subject to the tool-call budget. Counts and the nudge start fresh in each reply, because
+  each reply is one slice.
+- With `checkpoint_write`, the first targeted trigger is refused with a bounded nudge; repeating the
+  trigger ends the reply as `stalled` and the runner derives a checkpoint when the model wrote none.
+  A plan-research child keeps its frozen read-only capability set even though it lacks
+  `checkpoint_write`: it receives the same configured work-slice bound, is told to stop and return a
+  concise partial research report on its first budget or stall refusal, and a further tool call ends
+  the reply. The runner records an evidence-derived checkpoint; the child is not auto-continued and
+  receives no additional tool or connector permission.
 
 ### 5. Command budget
 
@@ -194,7 +204,7 @@ A foundation extension (`src/sessions/workSlice.ts`), registered where the compa
 ## 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
+  session and thread views group them; a person sees a checkpoint every ≤ 60 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
@@ -230,10 +240,11 @@ 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 slice guard (`src/sessions/workSlice.ts`): budget refusal, checkpoint-aware handoff, targeted
+  repeated-call and repeated-failure notes, success-only edit churn with progress-aware check retry
+  resets, compaction-thrash guard, and per-reply reset. The broad file/check no-progress trigger is
+  removed; plan-research children without `checkpoint_write` use the derived-checkpoint handoff and
+  the same configured bounds without gaining tools. 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,

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.

package/docs/architecture/proposals/PROP-0048-simple-annotate.md

@@ -0,0 +1,85 @@
+---
+id: PROP-0048
+title: One annotate page, two actions, and easy app attach
+status: Implemented
+created: 2026-10-27
+updated: 2026-10-27
+affects: [PROP-0018, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 13-world-tools.md, terminal-tui.md, parity.md]
+---
+
+# PROP-0048: One annotate page, two actions, and easy app attach
+
+## Problem
+
+People testing `/annotate:` found it hard to use:
+
+- `/annotate:annotate` duplicated `/annotate:` in every command list.
+- With no address, the page asked for one in a dialog that opened *behind* the full-screen page.
+  `PageOverlay` started its page in its constructor, before `dialogs.custom` mounted the overlay,
+  so any dialog the page opened as it started was stacked below it.
+- While that hidden dialog waited, the page's single-action guard dropped every key (`s`, `i`)
+  without a word: "send queue sometimes doesn't work".
+- A send held back while the agent was busy was tried once, 250 ms after the run ended. If the
+  terminal still reported its turn as active, the notes waited forever.
+- `/annotate:notes` was a separate centred dialog with its own capture flow.
+- The popover had three choices (save, ask the agent to fix, proceed now), the page had a queue, a
+  confirm step, an unqueue key and a "fixed" status reported by the agent's `page_notes_mark_fixed`.
+- Attaching an Electron app needed its DevTools address typed by hand.
+
+## Design
+
+**Delivery.** A note is either **pending** (shared with the session, unsent) or **sent**.
+`NoteDelivery.state` is `pending | sent`; records written before this read `queued` as `pending`
+and `fixed` as `sent`, without a migration write. Every annotation made in the inspector with a
+session is shared with it at once. The popover has two buttons: **Annotate** (`save`) and
+**Annotate & send** (`send`, also Cmd/Ctrl+Enter); `send` sends *all* the session's pending notes
+as one message. Any other action the page reports is a save. Page-origin notes (DevTools or
+bridge, untrusted) still wait for the person's confirmation; the terminal asks once for all of
+them, and an `empty` send reports how many still wait.
+
+`NoteDeliveries.runEnded` now tries a held-back send again (250 ms, 1 s, 3 s, 8 s) while the
+session answers `busy`, and starts over if another run ends meanwhile.
+
+`/annotate:submit <request>` sends the pending notes with the person's request after them
+(`compose(notes, prompt)`). With no pending notes it sends nothing. A request is not kept while
+the agent is busy; the notes stay pending and the person submits again. `/annotate:clear` resolves
+the session's pending notes and withdraws their grant to it; they can be reopened from
+`/annotate:notes`.
+
+`page_notes_mark_fixed` is removed; the agent's page-note tools are read-only again. Only the
+person resolves a note.
+
+**Commands.** A built-in command may be `rootOnly`: it is the namespace root (`/annotate:`) and has
+no named route, is not listed, and is not reachable as `/plugin:<name>`. The annotations plugin has
+`/annotate: [url | --app [port] | --bridge]`, `/annotate:notes`, `/annotate:submit` and
+`/annotate:clear`.
+
+**One page.** `AnnotatePage` is one full-screen page with an **Annotate** tab and an **All
+annotations** tab (`/annotate:notes` opens on the second). The Annotate tab takes the page address,
+a DevTools port or an app path in an inline field, never a dialog. `a` opens a list of the apps
+answering on a DevTools port on this computer, with *Start an app with a DevTools port*, *Type a
+DevTools port*, *Use the page bridge* and *Annotate a web page instead*. The notes are grouped
+**Unsent (n)** and **Sent**. A key pressed while the page is busy is answered with a notice.
+
+`PageOverlay` starts its page when the host reports it mounted (`mounted()`, called by
+`dialogs.custom` after `showOverlay`), or on the next turn for a host that does not. Dialogs a page
+opens as it starts now stack above it, on every page.
+
+**DevTools apps.** `AnnotationCapture.discover()` probes `127.0.0.1` on ports 9222–9230 and any port
+used before, reading `/json/version` and `/json/list` with a short timeout. A Node inspector
+(`node.js/…`) is skipped. `launchApp(key, path, args)` starts the program (the one inside a macOS
+`.app` bundle) with `--remote-debugging-port=<free loopback port>`, waits for its DevTools port, and
+attaches. The app keeps running after the capture ends. The loopback-only rule for `cdp` targets
+is unchanged.
+
+**Protocol.** Removed: `annotations.queue`, `annotations.dequeue`, `annotations.queued`. Added:
+`annotations.pending`, `annotations.markPending`, `annotations.confirmAll`, `annotations.clear`,
+`annotations.capture.discover`, `annotations.capture.launch`. `annotations.createAndAct` takes
+`save | send`; `annotations.compose` and `annotations.send` take an optional `prompt`. Terminal
+routes: `terminal.annotations.confirmAll|clear|discover|launch`; `queue` and `dequeue` are gone.
+
+## Consequences
+
+The App's Annotate panel used `queue`, `fixed` and `createAndAct('queue')` and follows in its own
+change. The prompt's Annotations group no longer names `page_notes_mark_fixed`, which changes the
+stable prefix once.