@xingular/harness 2.0.0 → 2.0.1-unstable

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.

package/docs/architecture/proposals/PROP-0049-context-attribution.md

@@ -0,0 +1,415 @@
+---
+id: PROP-0049
+title: Context attribution as a built-in capability
+status: Implemented
+created: 2026-10-28
+updated: 2026-10-28
+affects: [INV-PRM-6, INV-SRV-1, INV-PAR-1, INV-PAR-2, INV-RUN-7, 04-prompt.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, parity.md]
+---
+
+# PROP-0049: Context attribution as a built-in capability
+
+## Problem
+
+A person can see that a run is expensive but not where the context goes. The harness already
+records every fact needed to answer it, and no surface shows the answer:
+
+- `runs/<id>/context.json` holds the pack the run was given: each section's `title`, `size`
+  (characters), `budget`, `cut` and `sources`, plus `toolGroups` and the variant fingerprint
+  (`src/prompt/compile.ts`).
+- `runs/<id>/events.jsonl` holds `context.snapshot` — the verbatim `systemPrompt`, the
+  `contextUpdate`, and every tool's `{name, description, parameters}` — and `usage.updated`, whose
+  `contextTokens` is the provider-measured size of the latest request and `contextWindow` the
+  model's limit (`src/sessions/contracts.ts`, emitted by `src/sessions/runner.ts`).
+- `Pi` computes a live `{ tokens, contextWindow, percent }` for the session
+  (`getContextUsage()`), and its estimator is `ceil(chars / 4)`
+  (`node_modules/@earendil-works/pi-coding-agent/dist/core/compaction/compaction.js`).
+
+What is missing is the attribution: a row per contributor, tokens, share of the window, and a
+stack that reconciles to the measured total. The App shows a reply's context pack as a collapsed
+`<details>` list of character counts (`App/src/modes/shared/ContextPackView.tsx`), and a single
+`Meter` for "context at the end" (`App/src/modes/shared/SessionContextInspector.tsx`). The terminal
+declares `model.contextWindow` on its status band and never renders it
+(`src/terminal/tui/status.ts`). `usage.summary` carries no context fields at all
+(`src/usage/types.ts`).
+
+Attribution is something a person uses, so it belongs in the Harness with a terminal surface
+before an App screen (`INV-PAR-1`, `INV-PAR-2`).
+
+## What other harnesses show
+
+Evidence is from the checkout in `external/` for open repositories, and from official docs for
+Claude Code, Codex CLI and Gemini CLI. "Third-party" marks a claim read from a user report rather
+than a vendor document.
+
+| Harness | Where it shows | Rows / categories | % of window | Visual | Measured vs estimated | Thresholds | Actions from the view |
+|---|---|---|---|---|---|---|---|
+| **Claude Code** | `/context` command in the transcript; ring in the desktop panel; scriptable status line | `System prompt`, `System tools`, `MCP tools`, `Custom agents` (with source), `Memory files`, `Skills`, `Messages`; plus `Autocompact buffer` and `Free space` | Per row and in the header `598.5k / 1M (60%)` | "Colored grid" (docs); a table of tokens + % in the panel (**third-party**, [issue #94436](https://github.com/anthropics/claude-code/issues/94436)) | Estimated per row; header from measured | Ring blue → yellow → red; over-limit banner naming `/compact` | Text suggestions only ("trim CLAUDE.md · 49k per request"); `/usage` can apply some |
+| **Pi** (the engine under this harness) | TUI footer segment | One aggregate: `45.3%/200K (auto)` plus `↑in ↓out R<cache> W<cache> CH<hit>% $cost` (`dist/modes/interactive/components/footer.js:133-200`) | Yes, one decimal | Text, coloured | `getContextUsage()` = measured usage anchored, tail estimated at chars/4 | `>70` warning, `>90` error; `?/window` when unknown | `/compact` |
+| **opencode** | Sidebar block + prompt footer (`external/opencode/packages/tui/src/feature-plugins/sidebar/context.tsx:20-51`, `prompt/footer.tsx:38-55`) | One aggregate: `N tokens`, `N% used`, `$cost` | Rounded integer | Plain text, no bar, no colour | Last provider usage only (`util/session.ts:46-61`) | None | `<leader>c` / `/compact`; auto-compact reserves 15% or 16k |
+| **oh-my-pi (omp)** | Status-line segment system (`external/omp/packages/tui/src/status-line/footer.ts:171-260`) | One aggregate: `45.3%/200K`, per-direction counters, billing | One decimal | Coloured text, segment priorities | Provider-anchored, tail estimated; strict/approximate/upperbound tokenizer modes | Percent **or** absolute tokens, whichever first: 50%/150k, 70%/270k, 90%/500k (`chrome/context-thresholds.ts:6-11`) | `/compact` modes, `/shake` (drop heavy tool results), `/handoff` |
+| **DeepSeek Harness** | Web chat statistics dock; per-turn disclosure (`external/deepseek-harness/packages/client/ui-chat`) | `systemTokens`, `toolsTokens`, `messageTokens` — exactly three (`packages/llm/token-meter/README.md`) | Separate `contextPressure.pressureTokens`; the division is client-side | Not confirmed | Explicit: provider usage reused only on an identical request envelope, else estimated; rows are "approximate composition, never a total" | Compaction at `min(W×0.8, W−O−65536)` | `/compact`; tool-result pruning |
+| **Kimi CLI** | Status bar, right-aligned (`external/kimi-cli/src/kimi_cli/ui/shell/prompt.py:2251`, `soul/__init__.py:80`) | One aggregate: `context: 42.0% (4.2k/10.0k)` | Percent first | Plain text | Last provider usage (lags one request) | Ratio 85% **or** 50k reserve (`soul/compaction.py:59`) | `/compact`, `/clear` |
+| **Orca** | 16px SVG ring in the composer row, click/hover opens a popover (`external/orca/src/.../NativeChatContextUsageRing.tsx`) | Passes the underlying CLI's own categories through verbatim, with a `deferred` flag for on-demand context | Row % only, one decimal; ring clamps, stored value does not | Ring + `Progress` bar in the popover | Three states: `report`, `estimate`, `unknown`; window held separately from used | `CRITICAL_PERCENTAGE = 90` turns the ring destructive | None — read-only |
+| **Codex CLI** | `/status` prints configuration and "remaining context capacity"; `/statusline` picks footer fields (`developers.openai.com/codex/cli/slash-commands`) | No breakdown | Remaining capacity | Configurable footer items: model / context / limits / git / tokens / session | Not documented | Not documented | `/compact` |
+| **Gemini CLI** | `/stats` full-screen report (`external`-free; `docs/reference/commands.md:438-450`) | `session` (duration, tool calls), `model` (token counts, quota), `tools` (per-tool) | Not in the documented output | Text tables | Not documented | Not documented | `/compress` |
+
+Distinctive ideas worth keeping, by harness: **Claude Code** — a stack closed by `Autocompact
+buffer` + `Free space`, and the remedy named inside the view. **Pi** — `?` when the window is
+unknown rather than `0%`. **opencode** — one `formatContextUsage` helper shared by every surface, so
+they cannot disagree. **omp** — warn on percent *or* absolute tokens (small windows warn at the
+same absolute size) and a declared drop order for narrow terminals. **DeepSeek** — three separate
+projections (billing, occupancy, composition), never mixed into one number. **Kimi** — percent
+first, `used/total` in parentheses, readable at 30 columns. **Orca** — show the provider's own
+category names instead of inventing a taxonomy, and mark deferred context as deferred. **Codex** —
+the person chooses which fields the always-on strip carries.
+
+## Affected rules
+
+- **INV-PRM-6** Each run's pack is recorded beside the run; failing to record it never fails the
+  session. Attribution reads that record and adds per-section rendered sizes to it. Recording
+  stays best-effort.
+- **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. `context.attribution`
+  is additive: no existing method, param or result shape changes.
+- **INV-RUN-7** Token accounting keeps its meaning. `usage.updated.contextTokens` stays the
+  provider's figure for the latest request; attribution never rewrites it, and marks every row it
+  derived as estimated.
+- **INV-PAR-1 / INV-PAR-2** The capability lands in the Harness with a terminal surface, and the App
+  presents the same rows from the same method.
+- **INV-PRM-1** The prompt is still assembled only in `src/prompt/compile.ts`. Attribution measures
+  what that compiler produced; it never assembles text.
+
+## Proposal
+
+### 1. The measurement model
+
+Three facts are read, and nothing new is written per request:
+
+| Fact | Source | Kind |
+|---|---|---|
+| `systemPrompt`, `contextUpdate`, `tools[]` | `context.snapshot` event | recorded verbatim |
+| `contextTokens`, `contextWindow` | latest `usage.updated` event | **measured** by the provider |
+| sections, `toolGroups`, variant, `delivery` | `runs/<id>/context.json` | recorded at compile time |
+
+One constant, `CHARS_PER_TOKEN = 4`, the same ratio Pi, opencode, DeepSeek and Kimi use, so a row
+in this view and the `/context` header never disagree by more than rounding.
+
+`compile.render()` records the rendered size of each section (including the `## Title` framing and
+the gaps between sections) and, inside a section, the characters contributed by each `Source`. That
+is the only change to recorded data: it removes the need to re-parse a prompt later, which cannot
+be done safely because a variant section's body may itself contain `## ` headings.
+
+Rows are built in this order, and the last one is a subtraction rather than an estimate:
+
+1. **System prompt sections** — each `Section`'s rendered characters ÷ 4, attributed to the group
+   that owns it.
+2. **Tool schemas** — `JSON.stringify({name, description, parameters})` ÷ 4 for each recorded tool,
+   grouped by the pack's `toolGroups`; a tool in no group becomes `Other tools`.
+3. **This request's update** — the recorded `contextUpdate` ÷ 4.
+4. **Conversation** — `contextTokens − tokens(1..3)`, floored at zero. When the subtraction would go
+   negative the prefix rows are scaled down and the view says the prefix estimate exceeded the
+   measured total; it never shows a negative row.
+5. **Compaction reserve** — Pi's `settings.compaction.reserveTokens` (default 16 384) when
+   auto-compaction is on.
+6. **Free space** — `contextWindow − contextTokens − reserve`, so the stack sums to the window with the
+   reserve shown as its own row (the reserve is headroom the next request may not use, not free space).
+
+The rows therefore always add up to the window, and the number in the header is always the
+provider's. A run with no `usage.updated` yet shows estimated rows and marks the header
+`estimate only`; a session whose window is unknown shows `/ ?` like Pi, never `0%`.
+
+### 2. The row taxonomy: foundation, variant, application, conversation
+
+This is where the harness can say something no other harness can. Rows group by *who owns the
+text*, and variant rows say whether they cost every request:
+
+| Group | Members | Owner |
+|---|---|---|
+| **Foundation** | Harness identity, tool guidance, tool schemas (History, Wiki, Native, World, Progress, Session, Annotations), Wiki pointer, session state, references, reporting rules | released harness |
+| **Variant c1–c8** | Instructions (c1), Guardrails (c2), Memory (c3), Tool guidance (c4), subagent index (c5), skills index (c6), scripts index (c7) | `variant/`, refinable |
+| **Your application** | Identity, role, working folder, skills, plugin descriptions, connected apps, annotations | the host's sections and tool groups |
+| **Conversation** | Messages and tool results (measured residual), context updates | the run |
+| **Reserved and free** | Compaction reserve, free space | Pi, the model |
+
+Two facts make the variant rows actionable: `alwaysOnMax` caps always-on variant text at 24 000
+characters (`src/variant/surface.ts`), and only components with `reach: 'always'` occupy the prompt
+on every request. The view therefore shows a **budget meter per variant row** (`3.6K of 24K`) and a
+separate **on demand** list — skills, subagents, scripts — which are not in this request but will
+cost about *n* tokens when loaded. Claude Code shows a `Skills` row without that distinction; Orca
+has the `deferred` flag but no per-row cost. Showing both is the improvement.
+
+The foundation/variant split also gives the view its one obvious action: a variant row deeper than
+the cap, or plainly oversized, links to the Harness screen where it is edited or refined.
+
+### 3. Surfaces
+
+**Harness (reference terminal).** A `/context` full-screen page built like `/usage`:
+`src/terminal/tui/pages/contextPage.ts`, registered in `commandPages.ts` as a command page, reading
+`context.attribution`. It also fills the gap in `src/terminal/tui/status.ts`, whose band declares
+`model.contextWindow` and never paints it: the band gains `45.3%/200K` in the same place Pi puts it.
+
+**Server.** One additive method:
+
+```
+context.attribution { runId }
+  → {
+      runId, model, provider, window, used, share,            // numbers the provider reported
+      source: 'measured' | 'estimate',                         // which of the above is trusted
+      compaction: { enabled, reserveTokens, thresholdTokens } | null,
+      rows: [{ id, title, group, tokens, chars, share, always, estimated, cut?,
+               budget?, sources?, tools?, note? }],
+      onDemand: [{ id, title, tokens, items }],
+      totals: { foundation, variant, application, conversation, reserved },
+      recordedAt
+    }
+```
+
+`context.runPack` keeps returning the text; the App already calls it from
+`App/src/bridge/commands.ts:642`, and the new page uses it to show a row's actual prompt slice.
+
+**App.** A full-width page, not a sidebar tab — the sidebar is ~360–420 px wide, and a 6-column
+accounting sheet needs the main pane:
+
+- `ContextAttributionPage` in the main pane, opened from (a) the Context view's header, (b) a
+  compact meter in the composer footer, (c) the command palette. It uses the same host pattern as
+  agent configuration: a header strip with a close control
+  (`App/src/modes/solo/SoloWorkspace.tsx:263-265`).
+- The compact meter reuses `Meter` (`variant="ring"`) from `@xingular/ui` and opens the page.
+- The stack and its legend reuse `SegmentedBar` from `@xingular/ui/ui/charts`, whose `Segment` type
+  is already `{ key, label, value, color, display, share, title, recorded }` — exactly this page.
+- A cache strip uses `CacheUsageBadge` and `formatTokens` from
+  `App/src/modes/shared/usage/usageModel.ts`.
+
+### 4. Sketches
+
+A rendered version of these sketches, in the dark theme with the shared tokens, is
+[`outputs/context-attribution-sketch.html`](../../../../outputs/context-attribution-sketch.html)
+(open it in a browser; four tabs, switchable). All three options use one dataset, and the rows add
+to the provider's measured total.
+
+**Option A — accounting sheet (Claude Code's shape, this harness's rows).** Recommended.
+
+```
+┌─ Context ────────────────────────────────────────────────────────────────────────────────┐
+│ claude-sonnet-4-6 · 1M window · run r-8f21          auto-compact at 983.6K   [x]         │
+│                                                                                          │
+│ 183.4K / 1M · 18.3%                        measured · provider-reported                  │
+│ ████████▓▓▓▓▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░         │
+│ ├ foundation 13.1K ┤├ variant 18.4K ┤├ app 9.8K ┤├ conversation 142.1K ┤                 │
+│                                                                                          │
+│ ALWAYS IN CONTEXT                             TOKENS   SHARE  OF BUDGET                  │
+│ v Foundation · harness                         13.1K    1.3%                             │
+│     Harness identity                              29    0.0%  29 / 1.0K chars            │
+│     Tool guidance                               1.9K    0.2%  1.9K / 8.0K chars          │
+│     Tool schemas · 34 tools                     9.4K    0.9%                             │
+│       History 3 · Wiki 6 · Native 6 · World 5 · Connections 7 · Other 7                  │
+│     Wiki pointer                                1.1K    0.1%  1.1K / 2.5K chars          │
+│     Reporting rules                              712    0.1%  712 / 2.0K chars           │
+│     Session state · references                     0    0.0%  no update this request     │
+│ v Variant · c3 · 9a1f                          18.4K    1.8%                             │
+│     Instructions (c1)                           8.2K    0.8%  8.2K / 24K chars           │
+│     Guardrails (c2)                             4.1K    0.4%                             │
+│     Memory (c3)                                 3.6K    0.4%                             │
+│     Tool guidance (c4)                          2.5K    0.3%                             │
+│ v Your application                              9.8K    1.0%                             │
+│     Identity · Role · Working folder            2.4K    0.2%                             │
+│     Skills index · 12 skills                    1.1K    0.1%                             │
+│     Connected apps · 7 tools                    6.3K    0.6%                             │
+│ v Conversation                                142.1K   14.2%  measured by subtraction    │
+│     Messages and tool results                 142.1K   14.2%                             │
+│                                                                                          │
+│ RESERVED AND FREE                                                                        │
+│     Compaction reserve                         16.4K    1.6%  Pi, auto-compaction        │
+│     Free space                                800.2K   80.0%                             │
+│                                                                                          │
+│ ON DEMAND · not in this request                  when loaded                             │
+│     Skills c6 · 12 available                                  ~ 4.2K per skill           │
+│     Subagents c5 · 3 available                                own context each           │
+│                                                                                          │
+│ Rows are estimated from recorded character counts (÷ 4) and reconciled to                │
+│ the provider measured 183.4K; Conversation is the remainder, so the rows add             │
+│ to the whole.                                                                            │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Option B — ledger plus detail pane.** The same rows on the left; selecting one shows what it is
+on the right: the prompt text, the section's sources and revision, and the actions that apply.
+
+```
+┌───────────────────────────────────────────────┬──────────────────────────────────────────┐
+│ CONTEXT   ██████████░░░░░░░░░░  18.3%         │ Instructions (c1)                        │
+│ 183.4K of 1M · sonnet-4-6 · 34 tools          │ ─────────────────────────────────────    │
+│                                               │ 8.2K tokens · 0.8% of the window         │
+│FOUNDATION                        13.1K    1.3%│ always in context · 8.2K / 24K chars     │
+│  Harness identity                   29    0.0%│ variant c3 · fingerprint 9a1f            │
+│  Tool schemas                     9.4K    0.9%│ source systemprompt.md                   │
+│  Tool guidance                    1.9K    0.2%│ +----------------------------------+     │
+│  Wiki pointer                     1.1K    0.1%│ | You are the person's assistant,  |     │
+│  Reporting                         712    0.1%│ | working with them directly in    |     │
+│VARIANT · c3                      18.4K    1.8%│ | this session: research, writing  |     │
+│  Instructions c1                  8.2K    0.8%│ | and coding in its working folder |     │
+│  Guardrails c2                    4.1K    0.4%│ +----------------------------------+     │
+│  Memory c3                        3.6K    0.4%│ [Open in Harness]  [Refine this]         │
+│  Tool guidance c4                 2.5K    0.3%│                                          │
+│YOUR APPLICATION                   9.8K    1.0%│                                          │
+│CONVERSATION                     142.1K   14.2%│                                          │
+│RESERVED                          16.4K    1.6%│                                          │
+│FREE                             800.2K   80.0%│                                          │
+└───────────────────────────────────────────────┴──────────────────────────────────────────┘
+```
+
+**Option C — growth over the session.** A second tab for the same page: the stack at each request,
+so "what grew" is visible. Compaction markers come from `compaction.ended` (`tokensBefore`,
+`tokensAfter`), which the run already records.
+
+```
+┌ Growth ───────────────────────────────────────────────────────────────────────────────────┐
+│ 1M  ┤│
+│     │                                                    ╭── 44.2K│
+│ 20% ┤              ╭──╮   ╭──╮   ╭───╮   ╭────╮   ╭─────╯│
+│     │      ╭──╮    │  │   │  │   │   │   │    │   │                                      │
+│  0% ┼──────┴──┴────┴──┴───┴──┴───┴───┴───┴────┴───┴─────┬─────────────── requests →│
+│      r1    r2   r3   r4    r5   r6    r7   r8   ⧗ compacted 112K → 31K│
+│                                                                                          │
+│ foundation ▓  variant ▒  application ░  conversation █        each segment a group│
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+**The compact meter** — one always-visible readout, everywhere, opening the page:
+
+```
+ App composer footer                       Terminal status band
+ ┌────────────────────────────────────┐    ~/project (main) · account · sonnet-4-6
+ │ ▸ model  sonnet-4-6   ◔ 18%   ↑ ⏎ │    ↑12.1k ↓3.4k R84.9k 18.3%/1M
+ └────────────────────────────────────┘    └─ click / /context ─────────────────
+   ring colour: 18% data-1 · 80% warning · 95% destructive
+```
+
+**The terminal page** (`/context`), for reference:
+
+```
+ Context   sonnet-4-6 · 1M                                   18.3% used · measured
+ ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+ foundation    13.1K   1.3%  ██
+ variant       18.4K   1.8%  █
+ your app       9.8K   1.0%  ▌
+ conversation 142.1K  14.2%  ██████
+ reserved      16.4K   1.6%  █
+ free         800.2K  80.0%  (dim)
+ j/k move · enter open · v variant · c compact · r refresh · q close
+```
+
+### 5. Honesty rules the view must keep
+
+Taken from the mistakes of the harnesses above, and from `INV-RUN-7`:
+
+1. The header number is the provider's, or the word `estimate`.
+2. `Conversation` is a subtraction, never a guess, and is labelled `measured by subtraction`.
+3. Free space is `window − measured − reserve`, never `window − listed rows` — the Claude Code #94436
+   report is exactly that bug.
+4. A row that could not be measured is `not recorded`, not `0`.
+5. An unknown window is `/?`, never `0%`.
+6. Rows are `approx` in the copy, and the page states the ratio once.
+7. No number is recomputed from a provider's figure in a way that changes its meaning; a scaled row
+   is marked scaled.
+
+### 6. What this proposal does not do
+
+- No tokenizer. `chars / 4` is the house constant; a real tokenizer would need the provider's
+  encoding per model and would still not reconcile with the measured total.
+- No new storage. Everything is read from files the harness already writes, plus the rendered sizes
+  added to the pack (`INV-PRM-6`, `INV-MEM-5` untouched).
+- No new writer for run records or the ledger.
+- No cost attribution per row in the first surface. Cost per request exists (`pricing.ts`) and can
+  be added as a column later without changing the model.
+
+## Alternatives
+
+- **Do nothing.** The App already shows a pack's character counts and one meter. The gap is the
+  share of the window per contributor, the free space, and the variant's always-on cost — the three
+  questions a person actually asks.
+- **A tab in the existing sidebar Context view.** Rejected: the sidebar is too narrow for a six
+  column table, and the request is explicitly a full-width page.
+- **Client-side computation in the App.** Rejected by `INV-PAR-1`: the terminal needs the same rows,
+  and two implementations of the subtraction rule would drift.
+- **Reuse `usage.summary`.** Rejected: that is a period aggregate over the ledger. Attribution is
+  one request's composition, and `UsageTotals` has no context fields.
+- **Full tokenizer.** Rejected: see above; it would also make the view disagree with Pi's own
+  footer, which is the number a person already sees.
+
+## Consequences
+
+- **Applications.** One new method, additive. A host that shows the page reads
+  `context.attribution`; a host that does not is unaffected.
+- **Stored data.** `runs/<id>/context.json` gains a `rendered` size per section (and per source).
+  Older packs lack it; the view falls back to `size` and marks the section `approximate`.
+- **Protocol.** One new method name and result shape; no `PROTOCOL_VERSION` change.
+- **Spec.** `04-prompt.md` gains the recorded rendered sizes; `11-terminal.md` gains `/context`;
+  `14-surfaces-and-parity.md` and `parity.md` gain the row.
+
+## Migration
+
+Nothing to migrate. Packs recorded before this change stay readable; the only difference is the
+`approximate` marker on rows whose rendered size was not recorded. The capability can be removed by
+deleting the page, the method and the extra pack field; no data depends on it.
+
+## Checks
+
+- Harness: `npm run typecheck`, `npm test`, `npm run prove`.
+- New unit tests: the reconciliation (rows sum to `contextTokens`), the negative-prefix case, a pack
+  with no `usage.updated`, a pack with no `delivery`, and a run with unknown `contextWindow`.
+- Terminal: a page test in the style of `usagePage.test.ts`.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`, and
+  `cd src-tauri && cargo test`.
+- A visual check of both surfaces against one real run, comparing the header figure with the
+  terminal status band and with Pi's own footer.
+
+## What shipped
+
+- `prompt/compile.ts` renders the pack with `renderSized` and records `delivery.sizes` (system and
+  update maps plus framing); `render()` is unchanged byte for byte. The sizes are recorded in place of
+  the per-section `rendered?: number` the design proposed: one map, keyed by the ids that already
+  name the sections.
+- `sessions/contracts.ts` records `compaction: { enabled, reserveTokens }` in `context.snapshot`, read
+  from the Pi session's own settings; absent stays absent.
+- `context/attribution.ts` builds the rows, the measured reconciliation, the reserve and free space,
+  the per-request history, the compaction markers and the on-demand list. `context.attribution` is a
+  new server method; `terminal.context` resolves the terminal's latest run, so no surface passes a
+  run id it could not verify.
+- The bar is segmented: one colour per kind of context (the App's `--data-1..4` on both surfaces), the
+  track for free space, and a `│` where the reserve begins. The terminal's palette lives in
+  `terminal/tui/theme.ts` as `SERIES_COLORS`; the shared `SegmentedBar` grew `track`, `marker` and
+  `height` so the App draws one bar instead of a single-tone meter above a split. Severity moved to
+  the percentage text, on one rule for both surfaces: amber at 80, red at 95.
+- The terminal `/context` page shipped with the one-column ledger and the detail replacing the list on
+  `enter` (the side-by-side panes in Option B were not built); `g` regroups by owner or kind, `c`
+  compacts after a confirmation, `v` navigates to `/harness`. The band and the OpenTUI status bar
+  gained the reading, shown only when the session knows it.
+- The App gained `context.attribution` on the bridge, a full-width `ContextAttributionPage` opened from
+  the Context tab, and a context ring in the composer footer. The ring reports; it does not open the
+  page yet, so the Context tab is the only App entry point.
+- `context.attribution` takes `{ runId }` only; the session-scoped case is `terminal.context`, which is
+  the surface that has a session rather than a run.
+
+**Amendment (2026-10-29).** The composer status band carries no context reading in either
+renderer: at the person's request the terminal shows the share of the window only on `/context`,
+whose header reads the figure above (`18.3%/1M`). The compact-meter wireframe and the visual
+verification step that compares against the band record the accepted design, not the current
+band. The App composer ring is unchanged.
+
+## Open questions
+
+1. **Placement.** Full-width page in the main pane (recommended), a new workspace view tab that
+   renders full width, or a tab beside `Usage` in the sidebar? The sketches assume the first.
+2. **Shape.** Option A (accounting sheet), A plus Option B's detail pane on wide windows, or all
+   three as tabs of one page?
+3. **Rows.** Group by owner (foundation / variant / application / conversation), as proposed, or by
+   kind (`System prompt`, `Tools`, `Skills`, `Memory`, `Messages`) as Claude Code does? Owner
+   grouping is what makes the variant actionable; kind grouping is what a person coming from Claude
+   Code expects.
+4. **Cost per row.** Show `cost per request` beside tokens from the first version, or keep the view
+   token-only?
+5. **Live updates.** Refresh on every `usage.updated` while a reply streams, or on open and on
+   `completed` only?
+6. **The compact meter.** Add the ring to the App composer footer, the terminal status band, or
+   both? Pi's footer already shows `45.3%/200K` and this harness's band shows neither.

package/docs/architecture/proposals/PROP-0050-run-stop-codes-and-refusals.md

@@ -0,0 +1,30 @@
+---
+id: PROP-0050
+title: Run stop codes and refusal evidence
+status: Implemented
+created: 2026-10-29
+affects: [INV-RUN-3, INV-RUN-4, INV-GATE-1, INV-TUI-3, INV-PAR-1]
+---
+
+# PROP-0050: Run stop codes and refusal evidence
+
+## Problem
+
+A run's human-readable stop reason and tool results do not consistently identify the rule or
+lifecycle event that stopped it. Diagnostics need recorded causes rather than guesses based on prose.
+A settled run is not necessarily a finished task.
+
+## Design
+
+Record gate and work-slice refusals as `tool.refused` events, retaining the original tool response.
+Record a fixed `terminalCode` separately from the descriptive `terminalReason`. Interrupted events
+can carry the code; failure events retain their existing code and the run store maps it to a stop
+code. Legacy records without a code remain unknown. Report known compaction measurements, and expose
+refusals and stop evidence through trajectory search and the terminal trajectory page.
+
+Terminal telemetry is best effort when the controller is unreachable. These fields do not infer
+whether the requested work was completed and do not change the gate or its approval requirements.
+The binding contracts are in [sessions and runs](../02-sessions-and-runs.md),
+[tools and the gate](../07-tools-and-gate.md), [memory and history](../08-memory-and-history.md),
+and [terminal](../11-terminal.md). The architectural decision is
+[ADR-0059](../../decisions/ADR-0059-run-diagnostic-evidence.md).

package/docs/architecture/proposals/PROP-0051-unfinished-run-handoff.md

@@ -0,0 +1,110 @@
+---
+id: PROP-0051
+title: Unfinished runs must hand off a decision and a next step
+status: Implemented
+created: 2026-10-30
+updated: 2026-10-30
+affects: [INV-PRM-2, INV-PRM-8, 04-prompt.md, ADR-0008]
+---
+
+# PROP-0051: Unfinished runs must hand off a decision and a next step
+
+## Problem
+
+The `reporting` section tells the model to "Include blockers, risks, or next steps only when they are
+concrete and relevant" (`src/prompt/compile.ts:170`). That sentence is permissive, so a run that ends
+with work unfinished can satisfy it by naming blockers and never stating what the person must decide
+or do next.
+
+Run `55ad7d48-92b0-4d9d-9d80-c93b5112b80b` is the observed case, diagnosed in the run report
+`thaivlm/outputs/diagnoses/2026-10-29-55ad7d48.md` in the projects workspace:
+
+- The person asked for a 1,000-SHr training study to be implemented (seq 2).
+- The run stopped with two of four todos open — "Implement reproducible mixture and study
+  configuration" (in_progress) and "Implement model and optimizer compatibility checks" (pending)
+  (seq 119) — and completed (seq 145).
+- The final reply listed four changed files and three blockers — an empty OPC source, an in-progress
+  document dataset, an HTTP 403 on gated Gemma weights, missing model adapters — then a line about
+  tests, and stopped (seq 143). It named no decision, no owner and no next step.
+
+The person's report: "agent said whats blocking which is good but the reply lacks of whats saying what
+user has to do next or decision for user to do." The blocking was accurate; the handoff was missing.
+A reply that names only blockers leaves the person to reconstruct the decision themselves, which is
+the work the run was supposed to reduce.
+
+Prevalence is unknown: no sweep has been run over recent runs, so this is one confirmed case plus the
+guidance hole that permits it.
+
+## Proposal
+
+Add one conditional sentence to `REPORTING_GUIDANCE` in `src/prompt/compile.ts:165-176` — the
+foundation's stable `reporting` section, not variant data — requiring that a reply which ends with
+work unfinished states, in one short block, what the person must decide and what happens next:
+
+- **when:** the run leaves todos open, reports a blocker it could not clear, or stops before the
+  requested work is done. Ordinary completed replies are unaffected, so the "do not force a fixed set
+  of report headings" rule (`src/prompt/compile.ts:168`) still holds.
+- **what:** for each open item, either the decision the person owns (a choice only they can make) or
+  the next action with its owner; not a restatement of the blocker.
+- **how:** the same content-driven style as the rest of the section — a bulleted list or a short
+  table, no mandated heading names.
+
+The text stays stable and conditional. It cannot read live state: `INV-PRM-2` keeps changing state out
+of the system prompt, so the clause is written for the model to apply against its own todo list and
+blockers, not injected from `todo.updated` events.
+
+Spec page to update in the same change: [`04-prompt.md`](../04-prompt.md), Reporting section — one
+sentence saying that guidance also covers how an unfinished reply hands off. `INV-PRM-2` is unchanged
+in meaning (the section is still fixed text); it is listed in `affects` because the section's text
+changes. `INV-PRM-8` applies: the stable prefix changes once, so sessions miss the provider cache once
+after upgrade, exactly as recorded for PROP-0001 and PROP-0004.
+
+## Surfaces
+
+No new capability and no new screen. The section is harness-owned and identical in the terminal
+(`xagent`) and the App, because both receive the compiled pack
+([`04-prompt.md`](../04-prompt.md) § Reporting; `SECTION_ORDER.reporting = 95`). `docs/parity.md`
+needs no row: nothing is added that a host must present. Applications bundling the harness rebuild to
+pick up the new text.
+
+## Tests
+
+`src/prompt/compile.test.ts:304` already asserts the section's shape and stability. The test that goes
+red today is an added expectation on the guidance text itself, in that same test or beside it:
+
+```ts
+expect(REPORTING_GUIDANCE).toContain('ends with work unfinished')
+```
+
+plus a guard that the flexibility rule survives — `expect(REPORTING_GUIDANCE).toContain('do not force
+a fixed set of report headings')`, already at `compile.test.ts:311`, must stay green.
+
+## Alternatives
+
+- **Do nothing; leave "only when concrete and relevant".** This is the status quo that produced the run
+  above. It cannot distinguish "no blockers" from "blockers listed, decision unstated".
+- **Inject live todo state into the reporting section.** Rejected: `INV-PRM-2` forbids changing state in
+  the system prompt, and dynamic text would break the stable prefix (`INV-PRM-8`).
+- **Reinstate a fixed heading list (PROP-0001's original).** Rejected already by PROP-0004 and
+  [ADR-0008](../../decisions/ADR-0008-flexible-reporting-guidance.md): mandatory headings produced
+  generic sections. This proposal adds a trigger condition, not a template.
+- **Handle it in the variant prompt instead.** Rejected on routing: the guidance is foundation-owned
+  (`src/prompt/compile.ts:468`), identical for every variant, so a variant edit would not reach the run
+  that failed and would have to be redone per variant.
+
+## Consequences
+
+- Unfinished replies carry a decision or next action, at a small cost in length; completed replies are
+  unchanged.
+- One provider-prefix change, one cache miss after upgrade.
+- No stored data, server protocol, gate or tool change.
+- It remains guidance, not enforcement: a model can still under-report. A recurring pattern would
+  justify a checked run-level signal (for example, a stop code that marks a run unfinished), which is
+  out of scope here.
+
+## Out of scope
+
+- Completing the study whose todos stayed open.
+- Making the harness judge whether a task is finished, or any change to run status, stop codes or the
+  gate.
+- Sweeping recent runs to measure how often unfinished replies omit a decision.