@xingular/harness 1.1.1 → 1.2.0

package/docs/architecture/proposals/PROP-0038-annotate-open-shadow-roots.md

@@ -0,0 +1,73 @@
+---
+id: PROP-0038
+title: Annotate inside open shadow roots
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [13-world-tools.md, 12-storage.md (note target), PROP-0017, PROP-0018, parity]
+---
+
+# PROP-0038: Annotate inside open shadow roots
+
+Requested by the owner on 2026-10-25 after the inspector did nothing on reddit.com; they approved
+this design in the same session.
+
+## Problem
+
+Sites built from web components keep their content in shadow roots. Reddit's posts, comments and
+feed are `shreddit-*` elements with open shadow roots. The page helper (`annotations/pageScript.ts`)
+refused anything whose root node is not `document`, anything under an element with a shadow root, and
+any custom-element tag (PROP-0017, PROP-0018: "frames, shadow roots and custom elements are never
+picked"). Its text stream (`TreeWalker` over `document.body`) and element lookup
+(`document.getElementsByTagName`) never entered a shadow root. On such sites the inspector drew no
+outline, ignored clicks and said nothing. In WebKit, `getRangeAt` reports a selection inside a shadow
+root as a collapsed point on its host, so text capture could not work there either.
+
+## Proposal
+
+1. **Walk the composed tree.** New helper primitives walk open shadow roots and slotted content in
+   rendered order (`composedParent`, `flatChildren`, a bounded composed text stream). Visibility and
+   the excluded-content rules are checked on composed ancestors, and `aria-labelledby` ids are looked up
+   in the element's own root. Closed shadow roots stay unreadable, and light text a closed component
+   does not render is left out. Frames are never entered.
+2. **Version the target.** Text and element targets captured this way carry `tree: 'composed'`. A
+   target without it (every note saved before) is captured, stored and resolved by the document-only
+   rules exactly as before, so a saved note never changes what it points at, and a composed note can
+   never match a light-DOM node through the old path. The store accepts only the literal `'composed'`
+   and never on a page target.
+3. **Selections across trees.** Selections are read with `Selection.getComposedRanges` (dictionary
+   form, then variadic). Boundary points map to stream positions through the composed walk, so a
+   selection may start in the page and end inside a component. A selection that spans a visible form
+   field or private content is refused. A selection that grows over such content no longer leaves the
+   last acceptable selection behind; this also fixes the document-only path. Without
+   `getComposedRanges` the helper keeps the document-only capture.
+4. **Matches and marks.** A composed text match is a list of per-text-node ranges, since a `Range`
+   cannot span trees. Element candidates come from the document and every open shadow root, with the
+   same 2 000-candidate cap and equality rules. Context at the top of a shadow root is the component
+   that holds it. Marks clip to scrollports inside components and follow their scrolls and mutations.
+5. **Inspector.** The inspector picks the nearest annotatable element on the event's composed path, so
+   an icon gives way to its button, and content inside open components is reachable. A custom element
+   is pickable when it carries readable text or a label. It says why when it refuses, in a muted chip
+   and a toast on click: form fields and private content, embedded frames, or a component whose
+   contents are private.
+6. **Agents.** `page_notes_read` adds that a composed target lies inside a page component, where a
+   document-wide selector will not reach it.
+
+## Out of scope
+
+Iframes (cross-origin frames are unreachable by page script) and closed shadow roots.
+
+## Migration
+
+None. Existing notes have no `tree` and keep the old behaviour. Hosts that validate targets strictly
+accept the optional field (the App's `shared/browserAnnotations.ts`).
+
+## Checks
+
+`src/annotations/pageScript.test.ts` (headless Chromium) adds a web-component fixture: picks inside
+open roots, slotted and nested content, duplicate controls told apart by context, text inside and
+across roots, refusal over a field, hints for fields and a closed component, and identical
+legacy/composed captures on a page without components. `store.test.ts` covers the marker. In the App's
+isolated probe instance (real WKWebView), text inside a component and text crossing into one were
+captured, saved, resolved and revealed. Inspector clicks in WKWebView need real pointer input and were
+not exercised there.

package/docs/architecture/proposals/PROP-0039-workspace-boundary-hardening.md

@@ -0,0 +1,139 @@
+---
+id: PROP-0039
+title: Harden workspace writes against inode escapes and unverified retries
+status: Accepted
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-GATE-3, INV-GATE-8, INV-TUI-8, 02-sessions-and-runs.md, 07-tools-and-gate.md, 11-terminal.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0039: Harden workspace writes against inode escapes and unverified retries
+
+## Problem
+
+PROP-0037 promises that model-controlled writes stay inside the pinned workspace unless a person
+approves an escape. The current implementation checks canonical pathnames, but Pi performs native
+`write` and `edit` operations afterward using ordinary filesystem calls. A hard link keeps an
+in-workspace pathname while sharing an outside inode, and a parent symlink can change after the
+check. Source review found both cases can bypass the intended approval boundary.
+
+The Bash sandbox also exposes the live workspace as a writable path. A macOS integration
+reproduction created a hard link from a file outside the workspace to a name inside it, then ran a
+sandboxed Bash write through the in-workspace name. The command succeeded and the outside alias
+contained the new content. Linux behavior has not yet been reproduced locally.
+
+Finally, `workspaceSandbox.ts` infers a sandbox denial from matching text anywhere in captured
+stdout/stderr. A command controls that output; the text can prompt for an unconfined retry even when
+no sandbox denial occurred. Approval is still required, but the prompt's reason is not verified and
+approval replays the entire command.
+
+A separate launcher-selection issue was fixed in the 1.2.0 working tree: the sandbox launcher now
+comes only from fixed system paths, with a fake-PATH regression test. This does not resolve the
+remaining findings. No candidate, tag, or publication has been created.
+
+## Affected rules
+
+- **INV-GATE-3**, as it stands: “Bash first passes the gate's scope and authorization, then executes
+  only inside the OS sandbox; a detected write denial may enter a separate one-shot approval before
+  retry. The policy may tighten or deny a call, but cannot waive the boundary. Outside file writes
+  and sandbox-denied Bash retries cannot use remembered per-tool approval; only the eligible Full
+  Permission switch can answer automatically.” The output-triggered retry is replaced by an
+  explicit pre-execution scope request.
+- **INV-GATE-8**, as it stands: “Native reads are bounded by process and operating-system
+  permissions, not by the workspace root; absolute and `~` paths are valid. Every run pins its
+  canonical `workspaceRoot`. Native `edit` and `write` targets must resolve inside it by default,
+  with symlink escapes refused; outside targets require one-call approval and cannot use remembered
+  tool grants. Bash, including the initial `!` command, is OS-sandboxed to write only inside that
+  root while retaining broad reads. Sandbox denial permits at most one retry after explicit
+  approval. Full Permission is the only standing boundary bypass and remains subject to host
+  policy, authorization, and read-only, plan, unattended, probe, improver and reflection
+  restrictions. Missing enforcement fails closed.” The rule must define containment by the actual
+  filesystem effect, not just the path string.
+- **INV-TUI-8**: the terminal must present the same safe write and pre-execution approval behavior
+  as SDK sessions.
+
+## Proposal
+
+1. **Keep workspace-only as the default.** Each run continues to pin its canonical workspace root.
+   Reads remain broad as today.
+2. **Enforce native writes at the operation.** Harness supplies the `write` and `edit` tools with
+   safe filesystem operations instead of delegating their mutations to Pi's default in-place
+   `fsWriteFile`. The operation revalidates the pinned target and performs an atomic replacement
+   under the OS-enforced workspace boundary. Replacing the in-workspace directory entry rather
+   than truncating a shared inode prevents a hard-link alias from changing an outside file. A
+   symlink or parent-directory swap cannot widen the operation's OS write scope. Outside targets
+   retain their existing human-only, one-call approval; the helper receives only that approved
+   canonical target. Tool names and model-facing schemas stay the same.
+3. **Fail closed on external hard links for sandboxed Bash.** Before a default Bash call, inspect the
+   workspace for regular-file inodes whose link count exceeds the names found inside the workspace.
+   If the scan is incomplete or finds a possible outside alias, do not run the command; explain that
+   the alias must be removed or copied. The OS sandbox must also prevent the model's sandboxed
+   processes from creating a cross-boundary hard link. If a backend cannot establish both
+   conditions, it fails closed. A local process outside Harness with the same user's filesystem
+   permissions is not controlled by this rule; if protection from such peer processes is required,
+   that needs a separate inode-isolated workspace/snapshot design.
+4. **Ask before broad Bash writes, never infer from output.** Add an explicit
+   `workspaceWriteScope` choice to the Harness-owned Bash call, defaulting to `workspace`. A call
+   requesting `outside` is approved before it runs, as a human-only, nonrememberable operation; the
+   approval presentation must expose the complete command (scrollable in the terminal). The
+   eligible Full Permission switch may answer only under its existing restrictions. After approval,
+   run that exact command once with broader filesystem access. stdout/stderr text never triggers
+   approval or an automatic retry, and a denied command is never replayed after partial effects.
+5. **Keep other gates intact.** Plan, read-only, unattended, probe, improver and reflection
+   restrictions, host policy, authorization, and the tool capability set remain in force. Outside
+   writes and broad Bash calls cannot use remembered per-tool grants.
+
+## Alternatives
+
+- **Keep pathname checks and the output regex.** Rejected: hard links are invisible to `realpath`,
+  native operations race after validation, and command output is not evidence of a sandbox event.
+- **Only reject files with `nlink > 1` for native writes.** Rejected: a link can be added after the
+  check, and the native operation remains subject to path swaps.
+- **Run every shell call in a private copy-on-write workspace and commit changes back.** This gives
+  stronger inode isolation, including against peer processes, but changes shell visibility,
+  writeback/conflict behavior, metadata, storage use, and performance. It remains the alternative
+  if protection from same-user processes outside Harness is required.
+- **Remove all outside-write capability.** Rejected for now: the existing contract intentionally
+  supports explicitly approved escapes. The proposed pre-execution request preserves that choice
+  without guessing from output.
+- **Do nothing.** Leaves the default workspace boundary bypassable.
+
+## Consequences
+
+- The public server protocol and stored `RunRecord` layout need no new fields. The Bash tool schema
+  gains an optional scope choice; existing calls default to the current workspace-only behavior.
+- SDK sessions and the standalone terminal must register the same safe native tools and apply the
+  same pre-execution Bash gate. Terminal approval remains available through its existing inbox.
+- Atomic replacement changes the inode for a written path. The implementation must preserve normal
+  file mode behavior where possible and document any platform metadata that cannot be retained.
+- Reject the filesystem root as an active workspace; otherwise every path is inside the pinned root
+  and the boundary provides no containment.
+- A workspace containing a possible external hard link cannot use default sandboxed Bash until it
+  is repaired. Explicit outside scope remains a separate, visible approval, not a way to silently
+  reuse remembered grants.
+- The boundary protects model-controlled operations inside Harness. Other local processes running
+  with the same user's filesystem permissions remain outside this proposal's protection. On macOS,
+  the OS sandbox denies all hard-link creation by sandboxed Bash, including links entirely inside the
+  workspace.
+
+## Migration
+
+No stored runs or workspace data are rewritten. Old sessions continue to pin the same workspace
+root. Existing Bash calls omit `workspaceWriteScope` and therefore remain workspace-only; a command
+that needs broader writes must be issued again with an explicit outside scope and approved before
+execution. Existing outside-write approvals remain per-call and are not migrated into standing
+grants.
+
+## Checks
+
+- Add adversarial tests for native hard-link writes, symlink/parent swaps between validation and
+  mutation, shell writes through pre-existing external hard links, and cross-boundary hard-link
+  creation on macOS and Linux.
+- Verify command output containing denial-like text cannot request approval or rerun a command;
+  verify explicit outside scope asks before execution and runs at most once after approval.
+- Verify the complete requested command is visible in outside-scope approval details, and Full
+  Permission and all read-only, plan, unattended, refinement, authorization, and host policy
+  restrictions remain intact in SDK and terminal paths.
+- Run Harness `npm run typecheck`, `npm test`, and `npm run prove`; run the App compatibility checks
+  and inspect the relevant terminal behavior. Exercise the sandbox integration tests on macOS and
+  Linux before release.

package/docs/architecture/proposals/PROP-0040-one-launch-path.md

@@ -0,0 +1,87 @@
+---
+id: PROP-0040
+title: One launch path and command contract across front ends
+status: Accepted
+created: 2026-11-19
+updated: 2026-11-19
+affects: [INV-EXT-1, INV-RUN-1, INV-VAR-4, INV-PLG-11, INV-PAR-1, INV-PAR-2, INV-STO-3, 01-extension-points.md, 02-sessions-and-runs.md, 03-variants.md, 04-prompt.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0040: One launch path and command contract across front ends
+
+## Problem
+
+The approved App parity and Solo tabs handoff implemented a shared command registry and standard
+prompt sections, but the actual terminal still loads Pi command built-ins, terminal run records
+omit variant pins, session operations differ across front ends, and native browser schemas differ.
+Matching data roots alone does not share credentials: the terminal defaults to a file SecretStore
+while a host may supply its Keychain. Existing compiler-only tests do not establish runtime parity.
+
+## Affected rules
+
+- INV-PAR-1: every capability a person uses in a host is a Harness capability with a terminal surface.
+- INV-PAR-2: both surfaces must pass acceptance before a capability is complete.
+- INV-RUN-1 and INV-VAR-4: runs retain account, variant and capability pins.
+- INV-EXT-1: extension-point changes require a proposal; native backends remain tool providers.
+- INV-STO-3: storage layout changes are explicit and owned by one Harness module.
+- INV-PLG-11: plugin categories remain internal; surface availability is optional metadata, not a category.
+
+## Proposal
+
+The owner approved “Complete App parity and Solo tabs”, including one shared interactive default,
+on 2026-11-19. This proposal records that design; implementation status is tracked separately.
+
+1. Core commands are browser-safe data in `commands/registry.ts`. `commands.list` resolves the
+   effective scope's trusted plugin commands, prompts and skills with identical namespace and
+   collision rules. A menu entry alone does not prove command acceptance.
+2. Saved-history controls cover tree, navigate, fork, clone, rename, last reply and JSONL export.
+   Commands requiring a live session use `SessionRunInput.command`: compact, summarized navigation
+   and HTML export. They retain normal run lifecycle, busy fencing, cancellation and pins.
+3. `Launch.standard` supplies shared role, working-folder and connection wording. Tool and prompt
+   differences must be attributable to declared add-ons or explicit caller policy, not a front end.
+4. Interactive defaults are Harness-owned: data root, state directory, neutral default variant
+   scope and credential backend. Explicit roots/scopes and existing session/continuation pins win.
+   No App-specific discovery, automatic root merge, account substitution, credential downgrade or
+   OAuth-store copying is permitted. Adoption of conflicting populated profiles is explicit.
+5. Both surfaces load Harness-trusted resources and first-party hooks. Terminal-only Pi built-ins
+   and `ask_user_question` are removed; attended plan mode uses `ask_user`.
+6. Browser contracts are backend-neutral and owned by Harness; the isolated and native host
+   backends share names, schemas, safety metadata and ref freshness. A backend must report an
+   unsupported operation honestly, never reinterpret a snapshot ref as a selector.
+7. `get_capabilities` is a read-only Harness tool bound to the current run's frozen callable set
+   and actual registered schemas. Discovery never grants permission or accepts caller identity.
+8. Optional `PluginDescriptor.surfaces` / `Plugin.surfaces` metadata is
+   `{ preferred: 'host', terminal: 'fallback' | 'unavailable', note }`. Generic host-backed
+   capabilities retain Harness ownership; inspection shows fallback/unavailable reasons.
+9. Shared session references/catalog registration belong to Harness. Existing host transcript
+   presentation remains host-owned; native entry identities, not positional message counts,
+   connect navigation and fork to that presentation.
+
+## Alternatives
+
+- Do nothing: leaves command names that only approximate the advertised capabilities.
+- Match roots manually: rejected by the owner's explicit choice of one shared default.
+- Put browser contracts or session orchestration in the host: violates INV-PAR-1.
+- Merge existing stores automatically: unsafe for account pins, credentials and conflicting variants.
+
+## Consequences
+
+Server methods and SDK fields are additive. Existing session histories and account IDs remain valid.
+Terminal run records gain variant identity. Host browser adapters implement the common contract;
+legacy native routes may remain non-model-visible compatibility aliases for one release. Metadata
+labels do not certify acceptance or waive the gate.
+
+## Migration
+
+Keep explicit custom roots and historical pins. Seed only an absent default scope through validated
+variant APIs. Shared profile adoption must preserve originals, report conflicts/failure, and never
+silently select an empty replacement. Credentials remain in their owning backend. Shared processes
+must coordinate credential refresh and respect live run owners. Development/disposable profiles
+remain isolated from production. No migration is exercised on owner data during implementation.
+
+## Checks
+
+Harness typecheck, full tests and prove; deterministic terminal verification; App renderer/sidecar,
+layer/UI and Rust checks; full browser fixtures; shared UI and both consuming applications' checks.
+Runtime parity compares actual prepared launches, tool schemas and recorded pins. Native WebKit
+acceptance uses an isolated profile. Real-provider/cache checks require separate owner permission.

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.