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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +1 -1
  3. package/dist/cli.js +3680 -1947
  4. package/dist/sdk/cli.js +2 -0
  5. package/dist/sdk/commands/registry.d.ts +15 -0
  6. package/dist/sdk/commands/registry.js +2 -0
  7. package/dist/sdk/computer/screenshot.d.ts +32 -0
  8. package/dist/sdk/computer/screenshot.js +35 -0
  9. package/dist/sdk/context/attribution.d.ts +18 -0
  10. package/dist/sdk/context/attribution.js +295 -0
  11. package/dist/sdk/context/types.d.ts +94 -0
  12. package/dist/sdk/context/types.js +10 -0
  13. package/dist/sdk/index.d.ts +2 -1
  14. package/dist/sdk/index.js +2 -1
  15. package/dist/sdk/plugins/builtin.js +1 -0
  16. package/dist/sdk/prompt/compile.d.ts +42 -2
  17. package/dist/sdk/prompt/compile.js +87 -15
  18. package/dist/sdk/remote/addresses.d.ts +19 -0
  19. package/dist/sdk/remote/addresses.js +52 -0
  20. package/dist/sdk/remote/pairing.d.ts +59 -0
  21. package/dist/sdk/remote/pairing.js +160 -0
  22. package/dist/sdk/remote/seal.d.ts +28 -0
  23. package/dist/sdk/remote/seal.js +84 -0
  24. package/dist/sdk/remote/server.d.ts +28 -0
  25. package/dist/sdk/remote/server.js +158 -0
  26. package/dist/sdk/remote/service.d.ts +125 -0
  27. package/dist/sdk/remote/service.js +330 -0
  28. package/dist/sdk/remote/webClient.d.ts +4 -0
  29. package/dist/sdk/remote/webClient.js +444 -0
  30. package/dist/sdk/server/methods.js +3 -0
  31. package/dist/sdk/sessions/contracts.d.ts +4 -0
  32. package/dist/sdk/sessions/contracts.js +2 -0
  33. package/dist/sdk/sessions/planMode.d.ts +26 -1
  34. package/dist/sdk/sessions/planMode.js +48 -1
  35. package/dist/sdk/sessions/runner.d.ts +12 -0
  36. package/dist/sdk/sessions/runner.js +34 -2
  37. package/dist/sdk/sessions/sessions.js +1 -0
  38. package/dist/sdk/sessions/subagentService.d.ts +11 -1
  39. package/dist/sdk/sessions/subagentService.js +120 -38
  40. package/dist/sdk/sessions/subagents.d.ts +31 -0
  41. package/dist/sdk/sessions/subagents.js +45 -0
  42. package/dist/sdk/sessions/workSlice.d.ts +5 -9
  43. package/dist/sdk/sessions/workSlice.js +8 -149
  44. package/dist/sdk/terminal/client.d.ts +3 -1
  45. package/dist/sdk/terminal/client.js +15 -6
  46. package/dist/sdk/terminal/control.d.ts +1 -1
  47. package/dist/sdk/terminal/control.js +2 -2
  48. package/dist/sdk/terminal/controller.d.ts +22 -0
  49. package/dist/sdk/terminal/controller.js +104 -13
  50. package/dist/sdk/terminal/piExtension.js +106 -4
  51. package/dist/sdk/terminal/stallWatch.d.ts +13 -0
  52. package/dist/sdk/terminal/stallWatch.js +16 -0
  53. package/dist/sdk/terminal/standalone.d.ts +2 -0
  54. package/dist/sdk/terminal/standalone.js +9 -2
  55. package/dist/sdk/terminal/terminals.d.ts +14 -0
  56. package/dist/sdk/terminal/terminals.js +98 -2
  57. package/dist/sdk/terminal/tui/commandPages.d.ts +4 -1
  58. package/dist/sdk/terminal/tui/commandPages.js +12 -0
  59. package/dist/sdk/terminal/tui/commands.d.ts +3 -2
  60. package/dist/sdk/terminal/tui/commands.js +19 -5
  61. package/dist/sdk/terminal/tui/dialogs.d.ts +3 -2
  62. package/dist/sdk/terminal/tui/dialogs.js +4 -3
  63. package/dist/sdk/terminal/tui/keybindings.d.ts +1 -1
  64. package/dist/sdk/terminal/tui/keybindings.js +1 -1
  65. package/dist/sdk/terminal/tui/markdown.d.ts +16 -0
  66. package/dist/sdk/terminal/tui/markdown.js +55 -0
  67. package/dist/sdk/terminal/tui/modeChoices.d.ts +3 -2
  68. package/dist/sdk/terminal/tui/modeChoices.js +4 -4
  69. package/dist/sdk/terminal/tui/mouseReport.d.ts +30 -0
  70. package/dist/sdk/terminal/tui/mouseReport.js +80 -0
  71. package/dist/sdk/terminal/tui/pages/annotatePage.js +3 -2
  72. package/dist/sdk/terminal/tui/pages/browserPage.d.ts +1 -1
  73. package/dist/sdk/terminal/tui/pages/contextPage.d.ts +62 -0
  74. package/dist/sdk/terminal/tui/pages/contextPage.js +484 -0
  75. package/dist/sdk/terminal/tui/pages/remoteControlPage.d.ts +32 -0
  76. package/dist/sdk/terminal/tui/pages/remoteControlPage.js +170 -0
  77. package/dist/sdk/terminal/tui/pages/trajectoryPage.js +5 -4
  78. package/dist/sdk/terminal/tui/qr.d.ts +4 -0
  79. package/dist/sdk/terminal/tui/qr.js +35 -0
  80. package/dist/sdk/terminal/tui/runtime.js +8 -2
  81. package/dist/sdk/terminal/tui/search.js +3 -2
  82. package/dist/sdk/terminal/tui/sideQuestion.d.ts +1 -0
  83. package/dist/sdk/terminal/tui/sideQuestion.js +8 -3
  84. package/dist/sdk/terminal/tui/skillInvocation.d.ts +21 -2
  85. package/dist/sdk/terminal/tui/skillInvocation.js +31 -11
  86. package/dist/sdk/terminal/tui/status.d.ts +6 -0
  87. package/dist/sdk/terminal/tui/status.js +15 -1
  88. package/dist/sdk/terminal/tui/theme.d.ts +9 -0
  89. package/dist/sdk/terminal/tui/theme.js +9 -0
  90. package/dist/sdk/tools/defaultSkills.d.ts +19 -0
  91. package/dist/sdk/tools/defaultSkills.js +27 -1
  92. package/dist/sdk/tools/dispatch.js +8 -9
  93. package/dist/sdk/tools/spawnSubagent.d.ts +1 -1
  94. package/dist/sdk/tools/spawnSubagent.js +4 -2
  95. package/dist/terminal-opentui.js +1607 -492
  96. package/dist/terminal-pi.js +256 -144
  97. package/docs/README.md +1 -0
  98. package/docs/architecture/02-sessions-and-runs.md +55 -22
  99. package/docs/architecture/04-prompt.md +23 -4
  100. package/docs/architecture/07-tools-and-gate.md +4 -2
  101. package/docs/architecture/10-server-protocol.md +24 -0
  102. package/docs/architecture/11-terminal.md +52 -10
  103. package/docs/architecture/12-storage.md +5 -2
  104. package/docs/architecture/13-world-tools.md +17 -3
  105. package/docs/architecture/14-surfaces-and-parity.md +7 -3
  106. package/docs/architecture/15-remote-control.md +118 -0
  107. package/docs/architecture/README.md +3 -0
  108. package/docs/architecture/proposals/PROP-0049-context-attribution.md +409 -0
  109. package/docs/architecture/proposals/README.md +2 -1
  110. package/docs/decisions/ADR-0039-progress-aware-stall-guards.md +4 -0
  111. package/docs/decisions/ADR-0048-required-skills-from-a-message.md +42 -0
  112. package/docs/decisions/ADR-0050-approved-window-screenshots.md +19 -0
  113. package/docs/decisions/ADR-0051-terminal-decision-wait.md +10 -0
  114. package/docs/decisions/ADR-0052-per-profile-subagent-budgets.md +25 -0
  115. package/docs/decisions/ADR-0053-no-repeated-work-guard.md +45 -0
  116. package/docs/decisions/ADR-0054-terminal-reply-heartbeat-and-stall.md +52 -0
  117. package/docs/decisions/ADR-0055-plan-output-repair.md +51 -0
  118. package/docs/decisions/ADR-0056-remote-control.md +53 -0
  119. package/docs/decisions/ADR-0057-structured-plan-outcomes.md +39 -0
  120. package/docs/decisions/ADR-0058-ask-user-only-plan-clarification.md +36 -0
  121. package/docs/parity.md +14 -10
  122. package/docs/releases/1.3.1-unstable.3.md +54 -0
  123. package/docs/releases/1.3.1-unstable.4.md +56 -0
  124. package/docs/terminal-tui.md +43 -18
  125. package/package.json +3 -1
@@ -0,0 +1,409 @@
1
+ ---
2
+ id: PROP-0049
3
+ title: Context attribution as a built-in capability
4
+ status: Implemented
5
+ created: 2026-10-28
6
+ updated: 2026-10-28
7
+ 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]
8
+ ---
9
+
10
+ # PROP-0049: Context attribution as a built-in capability
11
+
12
+ ## Problem
13
+
14
+ A person can see that a run is expensive but not where the context goes. The harness already
15
+ records every fact needed to answer it, and no surface shows the answer:
16
+
17
+ - `runs/<id>/context.json` holds the pack the run was given: each section's `title`, `size`
18
+ (characters), `budget`, `cut` and `sources`, plus `toolGroups` and the variant fingerprint
19
+ (`src/prompt/compile.ts`).
20
+ - `runs/<id>/events.jsonl` holds `context.snapshot` — the verbatim `systemPrompt`, the
21
+ `contextUpdate`, and every tool's `{name, description, parameters}` — and `usage.updated`, whose
22
+ `contextTokens` is the provider-measured size of the latest request and `contextWindow` the
23
+ model's limit (`src/sessions/contracts.ts`, emitted by `src/sessions/runner.ts`).
24
+ - `Pi` computes a live `{ tokens, contextWindow, percent }` for the session
25
+ (`getContextUsage()`), and its estimator is `ceil(chars / 4)`
26
+ (`node_modules/@earendil-works/pi-coding-agent/dist/core/compaction/compaction.js`).
27
+
28
+ What is missing is the attribution: a row per contributor, tokens, share of the window, and a
29
+ stack that reconciles to the measured total. The App shows a reply's context pack as a collapsed
30
+ `<details>` list of character counts (`App/src/modes/shared/ContextPackView.tsx`), and a single
31
+ `Meter` for "context at the end" (`App/src/modes/shared/SessionContextInspector.tsx`). The terminal
32
+ declares `model.contextWindow` on its status band and never renders it
33
+ (`src/terminal/tui/status.ts`). `usage.summary` carries no context fields at all
34
+ (`src/usage/types.ts`).
35
+
36
+ Attribution is something a person uses, so it belongs in the Harness with a terminal surface
37
+ before an App screen (`INV-PAR-1`, `INV-PAR-2`).
38
+
39
+ ## What other harnesses show
40
+
41
+ Evidence is from the checkout in `external/` for open repositories, and from official docs for
42
+ Claude Code, Codex CLI and Gemini CLI. "Third-party" marks a claim read from a user report rather
43
+ than a vendor document.
44
+
45
+ | Harness | Where it shows | Rows / categories | % of window | Visual | Measured vs estimated | Thresholds | Actions from the view |
46
+ |---|---|---|---|---|---|---|---|
47
+ | **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 |
48
+ | **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` |
49
+ | **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 |
50
+ | **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` |
51
+ | **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 |
52
+ | **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` |
53
+ | **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 |
54
+ | **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` |
55
+ | **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` |
56
+
57
+ Distinctive ideas worth keeping, by harness: **Claude Code** — a stack closed by `Autocompact
58
+ buffer` + `Free space`, and the remedy named inside the view. **Pi** — `?` when the window is
59
+ unknown rather than `0%`. **opencode** — one `formatContextUsage` helper shared by every surface, so
60
+ they cannot disagree. **omp** — warn on percent *or* absolute tokens (small windows warn at the
61
+ same absolute size) and a declared drop order for narrow terminals. **DeepSeek** — three separate
62
+ projections (billing, occupancy, composition), never mixed into one number. **Kimi** — percent
63
+ first, `used/total` in parentheses, readable at 30 columns. **Orca** — show the provider's own
64
+ category names instead of inventing a taxonomy, and mark deferred context as deferred. **Codex** —
65
+ the person chooses which fields the always-on strip carries.
66
+
67
+ ## Affected rules
68
+
69
+ - **INV-PRM-6** Each run's pack is recorded beside the run; failing to record it never fails the
70
+ session. Attribution reads that record and adds per-section rendered sizes to it. Recording
71
+ stays best-effort.
72
+ - **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. `context.attribution`
73
+ is additive: no existing method, param or result shape changes.
74
+ - **INV-RUN-7** Token accounting keeps its meaning. `usage.updated.contextTokens` stays the
75
+ provider's figure for the latest request; attribution never rewrites it, and marks every row it
76
+ derived as estimated.
77
+ - **INV-PAR-1 / INV-PAR-2** The capability lands in the Harness with a terminal surface, and the App
78
+ presents the same rows from the same method.
79
+ - **INV-PRM-1** The prompt is still assembled only in `src/prompt/compile.ts`. Attribution measures
80
+ what that compiler produced; it never assembles text.
81
+
82
+ ## Proposal
83
+
84
+ ### 1. The measurement model
85
+
86
+ Three facts are read, and nothing new is written per request:
87
+
88
+ | Fact | Source | Kind |
89
+ |---|---|---|
90
+ | `systemPrompt`, `contextUpdate`, `tools[]` | `context.snapshot` event | recorded verbatim |
91
+ | `contextTokens`, `contextWindow` | latest `usage.updated` event | **measured** by the provider |
92
+ | sections, `toolGroups`, variant, `delivery` | `runs/<id>/context.json` | recorded at compile time |
93
+
94
+ One constant, `CHARS_PER_TOKEN = 4`, the same ratio Pi, opencode, DeepSeek and Kimi use, so a row
95
+ in this view and the terminal's status band never disagree by more than rounding.
96
+
97
+ `compile.render()` records the rendered size of each section (including the `## Title` framing and
98
+ the gaps between sections) and, inside a section, the characters contributed by each `Source`. That
99
+ is the only change to recorded data: it removes the need to re-parse a prompt later, which cannot
100
+ be done safely because a variant section's body may itself contain `## ` headings.
101
+
102
+ Rows are built in this order, and the last one is a subtraction rather than an estimate:
103
+
104
+ 1. **System prompt sections** — each `Section`'s rendered characters ÷ 4, attributed to the group
105
+ that owns it.
106
+ 2. **Tool schemas** — `JSON.stringify({name, description, parameters})` ÷ 4 for each recorded tool,
107
+ grouped by the pack's `toolGroups`; a tool in no group becomes `Other tools`.
108
+ 3. **This request's update** — the recorded `contextUpdate` ÷ 4.
109
+ 4. **Conversation** — `contextTokens − tokens(1..3)`, floored at zero. When the subtraction would go
110
+ negative the prefix rows are scaled down and the view says the prefix estimate exceeded the
111
+ measured total; it never shows a negative row.
112
+ 5. **Compaction reserve** — Pi's `settings.compaction.reserveTokens` (default 16 384) when
113
+ auto-compaction is on.
114
+ 6. **Free space** — `contextWindow − contextTokens − reserve`, so the stack sums to the window with the
115
+ reserve shown as its own row (the reserve is headroom the next request may not use, not free space).
116
+
117
+ The rows therefore always add up to the window, and the number in the header is always the
118
+ provider's. A run with no `usage.updated` yet shows estimated rows and marks the header
119
+ `estimate only`; a session whose window is unknown shows `/ ?` like Pi, never `0%`.
120
+
121
+ ### 2. The row taxonomy: foundation, variant, application, conversation
122
+
123
+ This is where the harness can say something no other harness can. Rows group by *who owns the
124
+ text*, and variant rows say whether they cost every request:
125
+
126
+ | Group | Members | Owner |
127
+ |---|---|---|
128
+ | **Foundation** | Harness identity, tool guidance, tool schemas (History, Wiki, Native, World, Progress, Session, Annotations), Wiki pointer, session state, references, reporting rules | released harness |
129
+ | **Variant c1–c8** | Instructions (c1), Guardrails (c2), Memory (c3), Tool guidance (c4), subagent index (c5), skills index (c6), scripts index (c7) | `variant/`, refinable |
130
+ | **Your application** | Identity, role, working folder, skills, plugin descriptions, connected apps, annotations | the host's sections and tool groups |
131
+ | **Conversation** | Messages and tool results (measured residual), context updates | the run |
132
+ | **Reserved and free** | Compaction reserve, free space | Pi, the model |
133
+
134
+ Two facts make the variant rows actionable: `alwaysOnMax` caps always-on variant text at 24 000
135
+ characters (`src/variant/surface.ts`), and only components with `reach: 'always'` occupy the prompt
136
+ on every request. The view therefore shows a **budget meter per variant row** (`3.6K of 24K`) and a
137
+ separate **on demand** list — skills, subagents, scripts — which are not in this request but will
138
+ cost about *n* tokens when loaded. Claude Code shows a `Skills` row without that distinction; Orca
139
+ has the `deferred` flag but no per-row cost. Showing both is the improvement.
140
+
141
+ The foundation/variant split also gives the view its one obvious action: a variant row deeper than
142
+ the cap, or plainly oversized, links to the Harness screen where it is edited or refined.
143
+
144
+ ### 3. Surfaces
145
+
146
+ **Harness (reference terminal).** A `/context` full-screen page built like `/usage`:
147
+ `src/terminal/tui/pages/contextPage.ts`, registered in `commandPages.ts` as a command page, reading
148
+ `context.attribution`. It also fills the gap in `src/terminal/tui/status.ts`, whose band declares
149
+ `model.contextWindow` and never paints it: the band gains `45.3%/200K` in the same place Pi puts it.
150
+
151
+ **Server.** One additive method:
152
+
153
+ ```
154
+ context.attribution { runId }
155
+ → {
156
+ runId, model, provider, window, used, share, // numbers the provider reported
157
+ source: 'measured' | 'estimate', // which of the above is trusted
158
+ compaction: { enabled, reserveTokens, thresholdTokens } | null,
159
+ rows: [{ id, title, group, tokens, chars, share, always, estimated, cut?,
160
+ budget?, sources?, tools?, note? }],
161
+ onDemand: [{ id, title, tokens, items }],
162
+ totals: { foundation, variant, application, conversation, reserved },
163
+ recordedAt
164
+ }
165
+ ```
166
+
167
+ `context.runPack` keeps returning the text; the App already calls it from
168
+ `App/src/bridge/commands.ts:642`, and the new page uses it to show a row's actual prompt slice.
169
+
170
+ **App.** A full-width page, not a sidebar tab — the sidebar is ~360–420 px wide, and a 6-column
171
+ accounting sheet needs the main pane:
172
+
173
+ - `ContextAttributionPage` in the main pane, opened from (a) the Context view's header, (b) a
174
+ compact meter in the composer footer, (c) the command palette. It uses the same host pattern as
175
+ agent configuration: a header strip with a close control
176
+ (`App/src/modes/solo/SoloWorkspace.tsx:263-265`).
177
+ - The compact meter reuses `Meter` (`variant="ring"`) from `@xingular/ui` and opens the page.
178
+ - The stack and its legend reuse `SegmentedBar` from `@xingular/ui/ui/charts`, whose `Segment` type
179
+ is already `{ key, label, value, color, display, share, title, recorded }` — exactly this page.
180
+ - A cache strip uses `CacheUsageBadge` and `formatTokens` from
181
+ `App/src/modes/shared/usage/usageModel.ts`.
182
+
183
+ ### 4. Sketches
184
+
185
+ A rendered version of these sketches, in the dark theme with the shared tokens, is
186
+ [`outputs/context-attribution-sketch.html`](../../../../outputs/context-attribution-sketch.html)
187
+ (open it in a browser; four tabs, switchable). All three options use one dataset, and the rows add
188
+ to the provider's measured total.
189
+
190
+ **Option A — accounting sheet (Claude Code's shape, this harness's rows).** Recommended.
191
+
192
+ ```
193
+ ┌─ Context ────────────────────────────────────────────────────────────────────────────────┐
194
+ │ claude-sonnet-4-6 · 1M window · run r-8f21 auto-compact at 983.6K [x] │
195
+ │ │
196
+ │ 183.4K / 1M · 18.3% measured · provider-reported │
197
+ │ ████████▓▓▓▓▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
198
+ │ ├ foundation 13.1K ┤├ variant 18.4K ┤├ app 9.8K ┤├ conversation 142.1K ┤ │
199
+ │ │
200
+ │ ALWAYS IN CONTEXT TOKENS SHARE OF BUDGET │
201
+ │ v Foundation · harness 13.1K 1.3% │
202
+ │ Harness identity 29 0.0% 29 / 1.0K chars │
203
+ │ Tool guidance 1.9K 0.2% 1.9K / 8.0K chars │
204
+ │ Tool schemas · 34 tools 9.4K 0.9% │
205
+ │ History 3 · Wiki 6 · Native 6 · World 5 · Connections 7 · Other 7 │
206
+ │ Wiki pointer 1.1K 0.1% 1.1K / 2.5K chars │
207
+ │ Reporting rules 712 0.1% 712 / 2.0K chars │
208
+ │ Session state · references 0 0.0% no update this request │
209
+ │ v Variant · c3 · 9a1f 18.4K 1.8% │
210
+ │ Instructions (c1) 8.2K 0.8% 8.2K / 24K chars │
211
+ │ Guardrails (c2) 4.1K 0.4% │
212
+ │ Memory (c3) 3.6K 0.4% │
213
+ │ Tool guidance (c4) 2.5K 0.3% │
214
+ │ v Your application 9.8K 1.0% │
215
+ │ Identity · Role · Working folder 2.4K 0.2% │
216
+ │ Skills index · 12 skills 1.1K 0.1% │
217
+ │ Connected apps · 7 tools 6.3K 0.6% │
218
+ │ v Conversation 142.1K 14.2% measured by subtraction │
219
+ │ Messages and tool results 142.1K 14.2% │
220
+ │ │
221
+ │ RESERVED AND FREE │
222
+ │ Compaction reserve 16.4K 1.6% Pi, auto-compaction │
223
+ │ Free space 800.2K 80.0% │
224
+ │ │
225
+ │ ON DEMAND · not in this request when loaded │
226
+ │ Skills c6 · 12 available ~ 4.2K per skill │
227
+ │ Subagents c5 · 3 available own context each │
228
+ │ │
229
+ │ Rows are estimated from recorded character counts (÷ 4) and reconciled to │
230
+ │ the provider measured 183.4K; Conversation is the remainder, so the rows add │
231
+ │ to the whole. │
232
+ └──────────────────────────────────────────────────────────────────────────────────────────┘
233
+ ```
234
+
235
+ **Option B — ledger plus detail pane.** The same rows on the left; selecting one shows what it is
236
+ on the right: the prompt text, the section's sources and revision, and the actions that apply.
237
+
238
+ ```
239
+ ┌───────────────────────────────────────────────┬──────────────────────────────────────────┐
240
+ │ CONTEXT ██████████░░░░░░░░░░ 18.3% │ Instructions (c1) │
241
+ │ 183.4K of 1M · sonnet-4-6 · 34 tools │ ───────────────────────────────────── │
242
+ │ │ 8.2K tokens · 0.8% of the window │
243
+ │FOUNDATION 13.1K 1.3%│ always in context · 8.2K / 24K chars │
244
+ │ Harness identity 29 0.0%│ variant c3 · fingerprint 9a1f │
245
+ │ Tool schemas 9.4K 0.9%│ source systemprompt.md │
246
+ │ Tool guidance 1.9K 0.2%│ +----------------------------------+ │
247
+ │ Wiki pointer 1.1K 0.1%│ | You are the person's assistant, | │
248
+ │ Reporting 712 0.1%│ | working with them directly in | │
249
+ │VARIANT · c3 18.4K 1.8%│ | this session: research, writing | │
250
+ │ Instructions c1 8.2K 0.8%│ | and coding in its working folder | │
251
+ │ Guardrails c2 4.1K 0.4%│ +----------------------------------+ │
252
+ │ Memory c3 3.6K 0.4%│ [Open in Harness] [Refine this] │
253
+ │ Tool guidance c4 2.5K 0.3%│ │
254
+ │YOUR APPLICATION 9.8K 1.0%│ │
255
+ │CONVERSATION 142.1K 14.2%│ │
256
+ │RESERVED 16.4K 1.6%│ │
257
+ │FREE 800.2K 80.0%│ │
258
+ └───────────────────────────────────────────────┴──────────────────────────────────────────┘
259
+ ```
260
+
261
+ **Option C — growth over the session.** A second tab for the same page: the stack at each request,
262
+ so "what grew" is visible. Compaction markers come from `compaction.ended` (`tokensBefore`,
263
+ `tokensAfter`), which the run already records.
264
+
265
+ ```
266
+ ┌ Growth ───────────────────────────────────────────────────────────────────────────────────┐
267
+ │ 1M ┤│
268
+ │ │ ╭── 44.2K│
269
+ │ 20% ┤ ╭──╮ ╭──╮ ╭───╮ ╭────╮ ╭─────╯│
270
+ │ │ ╭──╮ │ │ │ │ │ │ │ │ │ │
271
+ │ 0% ┼──────┴──┴────┴──┴───┴──┴───┴───┴───┴────┴───┴─────┬─────────────── requests →│
272
+ │ r1 r2 r3 r4 r5 r6 r7 r8 ⧗ compacted 112K → 31K│
273
+ │ │
274
+ │ foundation ▓ variant ▒ application ░ conversation █ each segment a group│
275
+ └──────────────────────────────────────────────────────────────────────────────────────────┘
276
+ ```
277
+
278
+ **The compact meter** — one always-visible readout, everywhere, opening the page:
279
+
280
+ ```
281
+ App composer footer Terminal status band
282
+ ┌────────────────────────────────────┐ ~/project (main) · account · sonnet-4-6
283
+ │ ▸ model sonnet-4-6 ◔ 18% ↑ ⏎ │ ↑12.1k ↓3.4k R84.9k 18.3%/1M
284
+ └────────────────────────────────────┘ └─ click / /context ─────────────────
285
+ ring colour: 18% data-1 · 80% warning · 95% destructive
286
+ ```
287
+
288
+ **The terminal page** (`/context`), for reference:
289
+
290
+ ```
291
+ Context sonnet-4-6 · 1M 18.3% used · measured
292
+ ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
293
+ foundation 13.1K 1.3% ██
294
+ variant 18.4K 1.8% █
295
+ your app 9.8K 1.0% ▌
296
+ conversation 142.1K 14.2% ██████
297
+ reserved 16.4K 1.6% █
298
+ free 800.2K 80.0% (dim)
299
+ j/k move · enter open · v variant · c compact · r refresh · q close
300
+ ```
301
+
302
+ ### 5. Honesty rules the view must keep
303
+
304
+ Taken from the mistakes of the harnesses above, and from `INV-RUN-7`:
305
+
306
+ 1. The header number is the provider's, or the word `estimate`.
307
+ 2. `Conversation` is a subtraction, never a guess, and is labelled `measured by subtraction`.
308
+ 3. Free space is `window − measured − reserve`, never `window − listed rows` — the Claude Code #94436
309
+ report is exactly that bug.
310
+ 4. A row that could not be measured is `not recorded`, not `0`.
311
+ 5. An unknown window is `/?`, never `0%`.
312
+ 6. Rows are `approx` in the copy, and the page states the ratio once.
313
+ 7. No number is recomputed from a provider's figure in a way that changes its meaning; a scaled row
314
+ is marked scaled.
315
+
316
+ ### 6. What this proposal does not do
317
+
318
+ - No tokenizer. `chars / 4` is the house constant; a real tokenizer would need the provider's
319
+ encoding per model and would still not reconcile with the measured total.
320
+ - No new storage. Everything is read from files the harness already writes, plus the rendered sizes
321
+ added to the pack (`INV-PRM-6`, `INV-MEM-5` untouched).
322
+ - No new writer for run records or the ledger.
323
+ - No cost attribution per row in the first surface. Cost per request exists (`pricing.ts`) and can
324
+ be added as a column later without changing the model.
325
+
326
+ ## Alternatives
327
+
328
+ - **Do nothing.** The App already shows a pack's character counts and one meter. The gap is the
329
+ share of the window per contributor, the free space, and the variant's always-on cost — the three
330
+ questions a person actually asks.
331
+ - **A tab in the existing sidebar Context view.** Rejected: the sidebar is too narrow for a six
332
+ column table, and the request is explicitly a full-width page.
333
+ - **Client-side computation in the App.** Rejected by `INV-PAR-1`: the terminal needs the same rows,
334
+ and two implementations of the subtraction rule would drift.
335
+ - **Reuse `usage.summary`.** Rejected: that is a period aggregate over the ledger. Attribution is
336
+ one request's composition, and `UsageTotals` has no context fields.
337
+ - **Full tokenizer.** Rejected: see above; it would also make the view disagree with Pi's own
338
+ footer, which is the number a person already sees.
339
+
340
+ ## Consequences
341
+
342
+ - **Applications.** One new method, additive. A host that shows the page reads
343
+ `context.attribution`; a host that does not is unaffected.
344
+ - **Stored data.** `runs/<id>/context.json` gains a `rendered` size per section (and per source).
345
+ Older packs lack it; the view falls back to `size` and marks the section `approximate`.
346
+ - **Protocol.** One new method name and result shape; no `PROTOCOL_VERSION` change.
347
+ - **Spec.** `04-prompt.md` gains the recorded rendered sizes; `11-terminal.md` gains `/context`;
348
+ `14-surfaces-and-parity.md` and `parity.md` gain the row.
349
+
350
+ ## Migration
351
+
352
+ Nothing to migrate. Packs recorded before this change stay readable; the only difference is the
353
+ `approximate` marker on rows whose rendered size was not recorded. The capability can be removed by
354
+ deleting the page, the method and the extra pack field; no data depends on it.
355
+
356
+ ## Checks
357
+
358
+ - Harness: `npm run typecheck`, `npm test`, `npm run prove`.
359
+ - New unit tests: the reconciliation (rows sum to `contextTokens`), the negative-prefix case, a pack
360
+ with no `usage.updated`, a pack with no `delivery`, and a run with unknown `contextWindow`.
361
+ - Terminal: a page test in the style of `usagePage.test.ts`.
362
+ - App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`, and
363
+ `cd src-tauri && cargo test`.
364
+ - A visual check of both surfaces against one real run, comparing the header figure with the
365
+ terminal status band and with Pi's own footer.
366
+
367
+ ## What shipped
368
+
369
+ - `prompt/compile.ts` renders the pack with `renderSized` and records `delivery.sizes` (system and
370
+ update maps plus framing); `render()` is unchanged byte for byte. The sizes are recorded in place of
371
+ the per-section `rendered?: number` the design proposed: one map, keyed by the ids that already
372
+ name the sections.
373
+ - `sessions/contracts.ts` records `compaction: { enabled, reserveTokens }` in `context.snapshot`, read
374
+ from the Pi session's own settings; absent stays absent.
375
+ - `context/attribution.ts` builds the rows, the measured reconciliation, the reserve and free space,
376
+ the per-request history, the compaction markers and the on-demand list. `context.attribution` is a
377
+ new server method; `terminal.context` resolves the terminal's latest run, so no surface passes a
378
+ run id it could not verify.
379
+ - The bar is segmented: one colour per kind of context (the App's `--data-1..4` on both surfaces), the
380
+ track for free space, and a `│` where the reserve begins. The terminal's palette lives in
381
+ `terminal/tui/theme.ts` as `SERIES_COLORS`; the shared `SegmentedBar` grew `track`, `marker` and
382
+ `height` so the App draws one bar instead of a single-tone meter above a split. Severity moved to
383
+ the percentage text, on one rule for both surfaces: amber at 80, red at 95.
384
+ - The terminal `/context` page shipped with the one-column ledger and the detail replacing the list on
385
+ `enter` (the side-by-side panes in Option B were not built); `g` regroups by owner or kind, `c`
386
+ compacts after a confirmation, `v` navigates to `/harness`. The band and the OpenTUI status bar
387
+ gained the reading, shown only when the session knows it.
388
+ - The App gained `context.attribution` on the bridge, a full-width `ContextAttributionPage` opened from
389
+ the Context tab, and a context ring in the composer footer. The ring reports; it does not open the
390
+ page yet, so the Context tab is the only App entry point.
391
+ - `context.attribution` takes `{ runId }` only; the session-scoped case is `terminal.context`, which is
392
+ the surface that has a session rather than a run.
393
+
394
+ ## Open questions
395
+
396
+ 1. **Placement.** Full-width page in the main pane (recommended), a new workspace view tab that
397
+ renders full width, or a tab beside `Usage` in the sidebar? The sketches assume the first.
398
+ 2. **Shape.** Option A (accounting sheet), A plus Option B's detail pane on wide windows, or all
399
+ three as tabs of one page?
400
+ 3. **Rows.** Group by owner (foundation / variant / application / conversation), as proposed, or by
401
+ kind (`System prompt`, `Tools`, `Skills`, `Memory`, `Messages`) as Claude Code does? Owner
402
+ grouping is what makes the variant actionable; kind grouping is what a person coming from Claude
403
+ Code expects.
404
+ 4. **Cost per row.** Show `cost per request` beside tokens from the first version, or keep the view
405
+ token-only?
406
+ 5. **Live updates.** Refresh on every `usage.updated` while a reply streams, or on open and on
407
+ `completed` only?
408
+ 6. **The compact meter.** Add the ring to the App composer footer, the terminal status band, or
409
+ both? Pi's footer already shows `45.3%/200K` and this harness's band shows neither.
@@ -75,9 +75,10 @@ it to the index and update its status as the work progresses.
75
75
  | [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
76
76
  | [PROP-0044](PROP-0044-work-slice-defaults.md) | Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap | Accepted; implemented | INV-RUN-13, 02, 10, 11, PROP-0041 | 2026-10-26 |
77
77
  | [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
78
- | [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 |
78
+ | [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039, targeted protections superseded by ADR-0053 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
79
79
  | [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 |
80
80
  | [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 |
81
+ | [PROP-0049](PROP-0049-context-attribution.md) | Context attribution: what fills the context window, by foundation, variant and application | Implemented | INV-PRM-6, INV-SRV-1, INV-PAR-1/2, INV-RUN-7, 04, 10, 11, 14, parity.md | 2026-10-28 |
81
82
 
82
83
  Numbers are four digits, start at `0001`, and are never reused.
83
84
 
@@ -2,12 +2,16 @@
2
2
  id: ADR-0039
3
3
  title: Progress-aware stall guards and bounded plan research children
4
4
  status: Accepted
5
+ superseded_by: ADR-0053 (targeted protections only)
5
6
  created: 2026-10-27
6
7
  proposal: PROP-0046
7
8
  ---
8
9
 
9
10
  # ADR-0039: Progress-aware stall guards and bounded plan research children
10
11
 
12
+ The targeted repeated-call, repeated-failing-check and edit-churn protections decided here are
13
+ superseded by [ADR-0053](ADR-0053-no-repeated-work-guard.md); the rest of the decision stands.
14
+
11
15
  ## Decision
12
16
 
13
17
  Remove the global file-change/check no-progress trigger. Keep the targeted protections for repeated
@@ -0,0 +1,42 @@
1
+ ---
2
+ id: ADR-0048
3
+ title: A skill named anywhere in a message is required for that request
4
+ status: Accepted
5
+ created: 2026-11-20
6
+ ---
7
+
8
+ # ADR-0048: A skill named anywhere in a message is required for that request
9
+
10
+ ## Decision
11
+
12
+ - `$name` is a skill invocation at any word start in a message, not only as its first token. The
13
+ composer's palette opens at the caret and replaces only the token being typed; the rest of the
14
+ draft and its caret stay in place.
15
+ - Every `$name` that names a skill the session can load makes that skill required for the request.
16
+ The named skills travel as `Launch.requiredSkills`, and the prompt compiler renders them as the
17
+ dynamic `required-skills` section: the skill's text from the pinned variant, the directive to
18
+ follow it, and an honest line for a name the variant does not have. The shipped
19
+ `plugin-authoring` skill fills in when the variant has none.
20
+ - The section belongs to the request. `sessionLaunch` resends it like `references`, even when it is
21
+ identical to the previous snapshot.
22
+ - The terminal builds the same text with `requiredSkillsText` from Pi's loaded skills and appends it
23
+ as a hidden `xingular-required-skills` custom message. It no longer rewrites a leading `$name` to
24
+ `/skill:name`; the person's message reaches the model unchanged and the requirement is enforced at
25
+ every position.
26
+ - A required skill changes no tool and no permission: the run's callable set and the gate are
27
+ untouched. It is a prompt-level requirement, not a capability narrowing.
28
+
29
+ ## Rationale
30
+
31
+ Pi expands only a leading `/skill:name`, so a mid-message skill was plain text and had no effect.
32
+ Moving the requirement into the request-scoped prompt text makes the same promise at every position,
33
+ keeps the stable prefix (and therefore the provider cache) intact, and gives the terminal and a host
34
+ one shared wording through `requiredSkillsText`.
35
+
36
+ ## Consequences
37
+
38
+ A leading `$name` no longer depends on Pi's `/skill:name` expansion. The skill's text is delivered
39
+ once per request that names it, so repeating the same skill in several turns repeats its text in
40
+ native history; the model sees the most recent copy. The App's composer already inserts `$` chips
41
+ anywhere; its reference path now sends skills as `requiredSkills` rather than as pinned notes.
42
+ Skills that a variant does not contain are reported as unavailable rather than silently dropped.
@@ -0,0 +1,19 @@
1
+ # ADR-0050: Approved-window screenshot contract
2
+
3
+ ## Decision
4
+
5
+ A host may supply `computer_screenshot` through the existing tool-provider extension point using
6
+ the Harness contract in `src/computer/screenshot.ts`. The backend must capture one currently
7
+ approved window and exclude the desktop, other windows and overlays, including overlapping ones.
8
+ If it cannot guarantee that scope it refuses without returning pixels; it never silently captures a
9
+ display instead. The adapter is opt-in, goes through the ordinary tool gate, and does not make
10
+ capture plan-mode safe. A host that also offers coordinate-based interactions interprets their
11
+ coordinates relative to the returned image pixels.
12
+
13
+ ## Consequences
14
+
15
+ Browser screenshots remain a separate capability with their own tab isolation. The contract cannot
16
+ verify native backend isolation; each host must implement and test it. The existing macOS display
17
+ capture has not adopted this contract and is not evidence of approved-window isolation. The
18
+ standalone terminal has no such backend. The contract adds no automatic provider registration or
19
+ new extension point.
@@ -0,0 +1,10 @@
1
+ # ADR-0051: Revisioned terminal decision waits
2
+
3
+ The terminal needs timely approval and question updates while avoiding a control request every
4
+ 100 ms in every idle session. The controller owns the pending inbox, so it exposes a private,
5
+ control-key-protected revisioned snapshot with a bounded wait. Every inbox mutation wakes waiters;
6
+ the frontend resynchronizes on reconnect. The existing immediate snapshot remains available.
7
+
8
+ The wait uses a separate socket request, so it does not block other terminal control calls.
9
+ Waits time out after 20 seconds and are woken on controller disposal. Client shutdown cancels its
10
+ request. No persisted state or public server protocol changes.
@@ -0,0 +1,25 @@
1
+ # ADR-0052: Per-profile and total subagent budgets
2
+
3
+ A run could start any number of children: `maxDepth` bounded nesting only. Run `90906235`
4
+ ("Implement the plan: Safe screenshot capability", 2026-10-28) started 11 children in nine
5
+ minutes for a five-step plan — three spawns before the parent had read a file, five children that
6
+ returned no change, and two tasks retried as fresh children. The shape of delegation was left to
7
+ the prompt.
8
+
9
+ A run now starts only a bounded number of distinct child conversations. Foundation defaults: four
10
+ children in total, two `worker`, three `explorer`, one of any other named profile and one with no
11
+ profile. A host overrides them through `SessionRunInput.subagents` (`maxChildren`, `maxByProfile`,
12
+ `maxOther`, `maxUnprofiled`), so the terminal and the App receive the same defaults; every value
13
+ is an integer clamped to 0–50.
14
+
15
+ `Subagents.spawn` counts the run's recorded children in `subagents.json`, the children of the
16
+ parent runs it was continued from (`resumedFromRunId`), and slots reserved by concurrent calls. It
17
+ deduplicates a continuation to its first link, so continuing a stopped child uses no new slot,
18
+ while a child whose startup failed still counts. A refused spawn returns an `invalid_request`
19
+ tool result telling the model to do the work itself; it creates no run. `continue` bypasses the
20
+ check because it is the same child.
21
+
22
+ The budget is per run, not per conversation, so a long chat is not starved. It lives in the
23
+ foundation because it bounds what every application built on the harness may spend, and changing
24
+ it needs a release. A host that legitimately needs more children raises the limits for its
25
+ session; the spawn tool's description states the effective numbers.
@@ -0,0 +1,45 @@
1
+ ---
2
+ id: ADR-0053
3
+ title: No repeated-work guard in the work slice
4
+ status: Accepted
5
+ created: 2026-10-28
6
+ supersedes: ADR-0039 (targeted protections only)
7
+ ---
8
+
9
+ # ADR-0053: No repeated-work guard in the work slice
10
+
11
+ ## Decision
12
+
13
+ Remove the repeated-work rules from the shared work-slice guard (`src/sessions/workSlice.ts`). A
14
+ reply is no longer refused for calling the same tool with the same arguments three times, for
15
+ running a Bash check that failed twice, or for more than four successful `edit`/`write` results on
16
+ one path. Nothing ends a reply as `stuck`.
17
+
18
+ The bounds that remain are the configured tool-call, minute and new-token budget and the
19
+ third-compaction thrash rule, both of which still ask for a checkpoint handoff and end the reply on
20
+ further calls. A budget-ended reply is `interrupted` with terminal reason `slice_complete` in both
21
+ surfaces. Slice continuation, the plan-research child bound and the model-written `blocked`
22
+ checkpoint gate are unchanged.
23
+
24
+ `checkpointReasonSchema` keeps `stuck` so stored `checkpoint` events stay readable and the
25
+ `checkpoint_write` argument set does not change; nothing produces it any more.
26
+
27
+ ## Rationale
28
+
29
+ The rules fired on calls that are ordinary work. Reading a file again, editing one file several
30
+ times, or re-running a check after a partial fix are not loops, and a refusal there costs a reply
31
+ plus the checkpoint and continuation round trip. Tool arguments are not a reliable signal of a loop:
32
+ a changed argument is different work, an identical argument can be legitimate (a poll, a re-read
33
+ after an edit, a retried check), and the guard cannot tell them apart. The reply budget already
34
+ bounds a model that never stops, which is the failure the guard existed to catch; the compaction
35
+ rule covers the other observed thrash.
36
+
37
+ ## Consequences
38
+
39
+ A reply may repeat any call until its budget, so a genuinely stuck model runs up to 320 calls or 60
40
+ minutes instead of being stopped earlier. No run-event schema, stored-data layout, server method or
41
+ App presentation changes: `stuck` remains a readable checkpoint reason and `stalled` remains the
42
+ watchdog's reason for a silent run. This supersedes the targeted repeated-call, repeated-failing-check
43
+ and edit-churn protections in [ADR-0039](ADR-0039-progress-aware-stall-guards.md); the rest of that
44
+ decision, including the bounded plan-research child, stands. See also
45
+ [PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md).