@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.3

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

@@ -0,0 +1,382 @@
+---
+id: PROP-0049
+title: Context attribution as a built-in capability
+status: Proposed
+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 terminal's status band 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.
+
+## 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/README.md

@@ -78,6 +78,7 @@ it to the index and update its status as the work progresses.
 | [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
 | [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
 | [PROP-0048](PROP-0048-simple-annotate.md) | One annotate page, two actions, and easy app attach | Implemented; ADR-0044 | PROP-0018, 07, 10, 11, 13, terminal-tui.md, parity.md | 2026-10-27 |
+| [PROP-0049](PROP-0049-context-attribution.md) | Context attribution: what fills the context window, by foundation, variant and application | Proposed | INV-PRM-6, INV-SRV-1, INV-PAR-1/2, INV-RUN-7, 04, 10, 11, 14, parity.md | 2026-10-28 |
 
 Numbers are four digits, start at `0001`, and are never reused.
 

package/docs/decisions/ADR-0048-required-skills-from-a-message.md

@@ -0,0 +1,42 @@
+---
+id: ADR-0048
+title: A skill named anywhere in a message is required for that request
+status: Accepted
+created: 2026-11-20
+---
+
+# ADR-0048: A skill named anywhere in a message is required for that request
+
+## Decision
+
+- `$name` is a skill invocation at any word start in a message, not only as its first token. The
+  composer's palette opens at the caret and replaces only the token being typed; the rest of the
+  draft and its caret stay in place.
+- Every `$name` that names a skill the session can load makes that skill required for the request.
+  The named skills travel as `Launch.requiredSkills`, and the prompt compiler renders them as the
+  dynamic `required-skills` section: the skill's text from the pinned variant, the directive to
+  follow it, and an honest line for a name the variant does not have. The shipped
+  `plugin-authoring` skill fills in when the variant has none.
+- The section belongs to the request. `sessionLaunch` resends it like `references`, even when it is
+  identical to the previous snapshot.
+- The terminal builds the same text with `requiredSkillsText` from Pi's loaded skills and appends it
+  as a hidden `xingular-required-skills` custom message. It no longer rewrites a leading `$name` to
+  `/skill:name`; the person's message reaches the model unchanged and the requirement is enforced at
+  every position.
+- A required skill changes no tool and no permission: the run's callable set and the gate are
+  untouched. It is a prompt-level requirement, not a capability narrowing.
+
+## Rationale
+
+Pi expands only a leading `/skill:name`, so a mid-message skill was plain text and had no effect.
+Moving the requirement into the request-scoped prompt text makes the same promise at every position,
+keeps the stable prefix (and therefore the provider cache) intact, and gives the terminal and a host
+one shared wording through `requiredSkillsText`.
+
+## Consequences
+
+A leading `$name` no longer depends on Pi's `/skill:name` expansion. The skill's text is delivered
+once per request that names it, so repeating the same skill in several turns repeats its text in
+native history; the model sees the most recent copy. The App's composer already inserts `$` chips
+anywhere; its reference path now sends skills as `requiredSkills` rather than as pinned notes.
+Skills that a variant does not contain are reported as unavailable rather than silently dropped.

package/docs/decisions/ADR-0050-approved-window-screenshots.md

@@ -0,0 +1,19 @@
+# ADR-0050: Approved-window screenshot contract
+
+## Decision
+
+A host may supply `computer_screenshot` through the existing tool-provider extension point using
+the Harness contract in `src/computer/screenshot.ts`. The backend must capture one currently
+approved window and exclude the desktop, other windows and overlays, including overlapping ones.
+If it cannot guarantee that scope it refuses without returning pixels; it never silently captures a
+display instead. The adapter is opt-in, goes through the ordinary tool gate, and does not make
+capture plan-mode safe. A host that also offers coordinate-based interactions interprets their
+coordinates relative to the returned image pixels.
+
+## Consequences
+
+Browser screenshots remain a separate capability with their own tab isolation. The contract cannot
+verify native backend isolation; each host must implement and test it. The existing macOS display
+capture has not adopted this contract and is not evidence of approved-window isolation. The
+standalone terminal has no such backend. The contract adds no automatic provider registration or
+new extension point.

package/docs/decisions/ADR-0051-terminal-decision-wait.md

@@ -0,0 +1,10 @@
+# ADR-0051: Revisioned terminal decision waits
+
+The terminal needs timely approval and question updates while avoiding a control request every
+100 ms in every idle session. The controller owns the pending inbox, so it exposes a private,
+control-key-protected revisioned snapshot with a bounded wait. Every inbox mutation wakes waiters;
+the frontend resynchronizes on reconnect. The existing immediate snapshot remains available.
+
+The wait uses a separate socket request, so it does not block other terminal control calls.
+Waits time out after 20 seconds and are woken on controller disposal. Client shutdown cancels its
+request. No persisted state or public server protocol changes.

package/docs/decisions/ADR-0052-per-profile-subagent-budgets.md

@@ -0,0 +1,25 @@
+# ADR-0052: Per-profile and total subagent budgets
+
+A run could start any number of children: `maxDepth` bounded nesting only. Run `90906235`
+("Implement the plan: Safe screenshot capability", 2026-10-28) started 11 children in nine
+minutes for a five-step plan — three spawns before the parent had read a file, five children that
+returned no change, and two tasks retried as fresh children. The shape of delegation was left to
+the prompt.
+
+A run now starts only a bounded number of distinct child conversations. Foundation defaults: four
+children in total, two `worker`, three `explorer`, one of any other named profile and one with no
+profile. A host overrides them through `SessionRunInput.subagents` (`maxChildren`, `maxByProfile`,
+`maxOther`, `maxUnprofiled`), so the terminal and the App receive the same defaults; every value
+is an integer clamped to 0–50.
+
+`Subagents.spawn` counts the run's recorded children in `subagents.json`, the children of the
+parent runs it was continued from (`resumedFromRunId`), and slots reserved by concurrent calls. It
+deduplicates a continuation to its first link, so continuing a stopped child uses no new slot,
+while a child whose startup failed still counts. A refused spawn returns an `invalid_request`
+tool result telling the model to do the work itself; it creates no run. `continue` bypasses the
+check because it is the same child.
+
+The budget is per run, not per conversation, so a long chat is not starved. It lives in the
+foundation because it bounds what every application built on the harness may spend, and changing
+it needs a release. A host that legitimately needs more children raises the limits for its
+session; the spawn tool's description states the effective numbers.

package/docs/parity.md

@@ -30,19 +30,19 @@ implemented is not a parity claim; acceptance is tracked per command.
 | Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
 | Opening a link | `core/links.ts` | `links.open`; `HarnessOptions.linkOpener` (ADR-0047) | hover shows the hand pointer and recolours the link, Ctrl+click (the primary click on macOS, whose ⌘ the mouse protocol cannot report) opens web, `mailto:`, file and folder targets with the system handler, a refused link posts a notice | ⌘-click on macOS and Ctrl+click elsewhere opens with the system handler, a plain click keeps the sidebar and falls back to the system for what it cannot show, `a:hover` uses `--link-hover` | implemented; acceptance not certified | — |
 | Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | parity; terminal projection verified in isolated fixtures | — |
-| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
+| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles; per-profile and total child budgets enforced in `Subagents.spawn` (ADR-0052), with the same refusal result in both surfaces | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
 | Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*`; package profiles through `Loading.profilePaths` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete; package profiles listed under "From a plugin" and switched on `/plugins` | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
 | Run todo list | `tools/todo.ts` | `todo_write`, `runs.todo` (`runs.checklist` deprecated); terminal `todo` telemetry | registered in terminal sessions and their subagents; each write shows as a todo block in the transcript; `/todo` shows the current list; a subagent row shows its `n of m tasks` | `/todo` shows the current list on demand; each write is not rendered inline | terminal done; App shows it on demand | PAR-001 |
 | Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
 | Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
 | Accounts | `accounts/` | `accounts.*` | `/accounts` | Accounts | parity | — |
 | Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
-| Skills | `plugins/`, `tools/dispatch.ts` | `skill_load` | `$name`, `/skill:name`, browser Skills tab | Capability, composer | parity | — |
+| Skills | `plugins/`, `tools/dispatch.ts`, `prompt/compile.ts` | `skill_load`; `Launch.requiredSkills` | `$name` at any word start (required for that request), `/skill:name`, browser Skills tab | composer `$` chip with `requiredSkills`; Capability | implemented; acceptance not recertified | — |
 | Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | full-screen `/plugins` local manager; separate full-screen `/hub` Community catalog with bounded registry/document Preview (no Pi-package Preview) | local Plugins manager; Community Hub with payload Preview for non-package entries | parity | — |
 | Plugin authoring and proposal review | `plugins/proposals.ts`, `tools/defaultSkills.ts` | `plugin_propose`, `plugins.proposals.*` | `/plugins` Proposals tab: preview, accept or reject | structured model tool and skill; review UI not implemented | partial; App review pending | PAR-017 |
 | Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
 | Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
-| Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read and page scroll without refs; unsupported operations refuse explicitly | partial; native backend gap | PAR-015 |
+| Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read, page screenshot and page scroll without refs; unsupported operations refuse explicitly; live screenshot acceptance pending | partial; native backend gap | PAR-015 |
 | Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038, PROP-0048) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` page (Annotate and All annotations tabs; DevTools app list and launch), `/annotate:notes`, `/annotate:submit`, `/annotate:clear` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | App behind PROP-0048 (queue methods removed); native WKWebView gestures unaccepted | PAR-011 |
 | Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | Solo `/worktree` lists records only; Solo starts sessions in the project folder and has no worktree level | partial | PAR-012 |
 | Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `Terminals.ownTools` registers Wiki-read tools through the session socket; `xagent-wiki` remains a person-facing shell utility | structured Harness tools | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
@@ -56,7 +56,7 @@ implemented is not a parity claim; acceptance is tracked per command.
 | Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
 | Session catalog (sessions per folder) | `sessions/` saved-history controls; shared catalog not implemented | `sessions.*` controls; no cross-surface catalog method | `/session` selects native Pi histories in the current folder | `/session` reads `bridge.agent.threads(SOLO_ID)`, maps each thread to its project folder, and filters by current effective account; `all` broadens only this App list | planned; catalogs differ | PAR-008 |
 | Folder choice and recent folders | project/worktree selection remains surface-specific | launch `cwd`, `--worktree`, `/worktree` | starts in launch folder; explicit worktree commands | Solo sidebar is Project › Session; new sessions use the project's folder, with no folder/worktree level | planned; no shared recent-folder picker | PAR-009 |
-| Computer control | — | `computer_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
+| Computer control | `computer/screenshot.ts` defines an opt-in approved-window screenshot contract; other tools remain host-owned | `computer_*` (host tools) | no computer screenshot backend | macOS bridge (host-backed); its display capture has not adopted the approved-window contract | partial; screenshot contract not integrated | PAR-007 |
 | Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
 
 ## Core slash-command surfaces (PROP-0040)
@@ -125,7 +125,7 @@ or live-model sketch quality.
 | PAR-004 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
 | PAR-005 | Wiki browsing only in the App | A `/wiki` page over `wiki.*`. |
 | PAR-006 | Acceptance of terminal first-party hooks | Source gap resolved: enabled hooks are returned by protected `firstParty.list` and loaded by `terminal/piExtension.ts`. Acceptance has not been recertified in this documentation pass. |
-| PAR-007 | Host tools without a Harness owner | Decide each: computer control stays host-backed (terminal shows unavailable); the files vault becomes a Harness capability or is dropped. |
+| PAR-007 | Host tools without a complete Harness surface | The opt-in screenshot contract exists, but terminal availability reporting and a conforming host backend are not wired. The current macOS host captures a display, not an isolated approved window. The remaining computer controls are host-owned; the files vault becomes a Harness capability or is dropped. |
 | PAR-008 | Separate session catalogs | Proposal approved; shared catalog is not implemented. Terminal `/session` selects native Pi history in the current folder. App `/session` reads Solo `agent.threads`, maps threads through Solo project groups, and filters to the current effective account and folder; `/session all` broadens only within that App catalog. It cannot open an arbitrary native session path. No cross-surface catalog or visibility guarantee exists. |
 | PAR-009 | Shared folder/recent-project choice | Terminal starts from its launch `cwd` and can switch through its worktree surface. App Solo uses Project › Session and starts new sessions in the selected project's folder; it has no folder/worktree level or shared recent-folder picker. |
 | PAR-010 | Agent profile management in Solo | App Solo `/agents` can list profiles. Although the renderer allowlist includes `agents.get`, Solo does not wrap it; `agents.create/remove` are not exposed there. Profile details and management actions are unavailable, unlike terminal `/agents`. |
@@ -134,4 +134,4 @@ or live-model sketch quality.
 | PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |
 | PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |
 | PAR-016 | Usage analytics and provider limits in the App | The terminal has `/usage:analysis` and `/usage:limit` over `usage.*`. The App presents the same capability: an analytics view and a per-account provider limit view. |
-| PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads and scrolling without refs. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll), browser screenshots, waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |
+| PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads, page screenshots and scrolling without refs; live screenshot acceptance is pending. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll/ref-screenshot), waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |

package/docs/releases/1.3.1-unstable.3.md

@@ -0,0 +1,54 @@
+# Xingular Harness 1.3.1-unstable.3
+
+Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
+
+- Name a skill anywhere in a message: `$name` at any word start makes that skill required for the
+  request (ADR-0048). `Launch.requiredSkills` carries it, and the compiler renders a
+  `required-skills` section at order 52 from the pinned variant through `readSkillFile`, bounded at
+  12,000 characters. An unavailable skill is named honestly instead of invented, and the built-in
+  `plugin-authoring` skill stands in when the variant ships no skills. The section belongs to the
+  request, so an identical one is delivered again rather than deduplicated. The terminal builds the
+  same text with `requiredSkillsText` and appends it as a hidden `xingular-required-skills` message,
+  so the person's own wording reaches the model unchanged. In the composer the `$` palette opens at
+  the caret and inserts there, keeping the rest of the draft.
+- Bound delegation per run and per profile (ADR-0052). A run now starts at most four distinct child
+  conversations: two `worker`, three `explorer`, one of any other named profile and one with no
+  profile. `SessionRunInput.subagents` / the SDK's `Subagents` options override them with
+  `maxChildren`, `maxByProfile`, `maxOther` and `maxUnprofiled` (clamped to 0–50), and the model's
+  `spawn_subagent` description states the budget it has left. `Subagents.spawn` refuses a child past
+  a limit with `invalid_request` and starts no run; continuing a stopped child costs no slot, and a
+  work-slice continuation keeps the parent's budget.
+- Read what a request was made of. `context.attribution` returns one row per contributor with its
+  estimated tokens and share of the window, reconciled to the provider's measured total, and one
+  row's text on request; the terminal reaches it through `terminal.context`. The compiler now
+  records where its characters went: `renderSized` returns each section's size and the framing that
+  belongs to no section, `Delivery.sizes` stores them on the recorded pack, and `Source.chars`
+  attributes a variant's tool guidance inside the tools section. `context.snapshot` also records the
+  compaction headroom the run was held to (`compaction: { enabled, reserveTokens }`) from Pi's own
+  settings. The terminal page over this data arrives in a later preview; no `/context` command is
+  registered yet.
+- Add an opt-in approved-window screenshot contract (ADR-0050). `src/computer/screenshot.ts` defines
+  `computer_screenshot` for a host-supplied backend: it captures exactly one currently approved
+  window, excludes the desktop, other windows and overlapping overlays, and refuses with
+  `COMPUTER_SCREENSHOT_UNAVAILABLE` rather than returning display pixels. It goes through the
+  ordinary tool gate, is not plan-mode safe, and adds no extension point. The standalone terminal
+  has no backend, and the existing macOS host capture has not adopted this contract.
+- Deliver approvals and questions promptly without polling: the control-key-protected
+  `terminal.pending.wait` returns as soon as the pending revision changes and otherwise waits at most
+  20 s, waking on additions, removals and disposal (ADR-0051). `terminal.pending` is unchanged and
+  the server protocol is untouched.
+- Swap the OpenTUI send keys back. `Return` sends, or queues a follow-up behind a running reply, and
+  `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers that reply. The `app.message.followUp` action is
+  `app.message.steer` again, so a `keybindings.json` entry under the newer name needs renaming.
+- Keep a stray mouse report out of input. A report split across the input parser's timeout no longer
+  types its `<button;column;row>` tail into the composer or a single-line field, so a scroll cannot
+  become a run's prompt or a filter; typing and pastes are untouched and `/trajectory` no longer
+  prints a recorded report.
+
+## Upgrading
+
+- A leading `$name` is no longer rewritten to Pi's `/skill:name`. An embedding host sends required
+  skills as `Launch.requiredSkills`, and the message text reaches the model as written.
+- Runs that spawned children freely now stop at the defaults above; set `subagents` explicitly to
+  change them.
+- A `keybindings.json` entry named `app.message.followUp` is now `app.message.steer`.