@xingular/harness 1.5.0-unstable → 1.6.0-unstable

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 (95) hide show
  1. package/CHANGELOG.md +93 -0
  2. package/browser-extension/README.md +32 -0
  3. package/browser-extension/background.js +612 -0
  4. package/browser-extension/manifest.json +16 -0
  5. package/browser-extension/overlay.js +97 -0
  6. package/browser-extension/popup.css +19 -0
  7. package/browser-extension/popup.html +30 -0
  8. package/browser-extension/popup.js +101 -0
  9. package/browser-extension/site-access.js +63 -0
  10. package/dist/cli.js +1489 -680
  11. package/dist/sdk/browser/config.d.ts +3 -0
  12. package/dist/sdk/browser/config.js +2 -1
  13. package/dist/sdk/browser/extension/bridge.d.ts +55 -0
  14. package/dist/sdk/browser/extension/bridge.js +336 -0
  15. package/dist/sdk/browser/extension/session.d.ts +50 -0
  16. package/dist/sdk/browser/extension/session.js +321 -0
  17. package/dist/sdk/browser/index.d.ts +7 -2
  18. package/dist/sdk/browser/index.js +58 -25
  19. package/dist/sdk/browser/serverMethods.js +4 -1
  20. package/dist/sdk/browser/tools.d.ts +99 -2
  21. package/dist/sdk/browser/tools.js +6 -1
  22. package/dist/sdk/commands/registry.d.ts +5 -0
  23. package/dist/sdk/commands/registry.js +1 -0
  24. package/dist/sdk/harness.d.ts +4 -0
  25. package/dist/sdk/harness.js +1 -1
  26. package/dist/sdk/pi/retryPolicy.d.ts +19 -0
  27. package/dist/sdk/pi/retryPolicy.js +11 -0
  28. package/dist/sdk/prompt/compile.d.ts +0 -2
  29. package/dist/sdk/prompt/compile.js +2 -6
  30. package/dist/sdk/prompt/reporting.d.ts +1 -1
  31. package/dist/sdk/prompt/reporting.js +30 -13
  32. package/dist/sdk/prompt/standard.d.ts +1 -1
  33. package/dist/sdk/prompt/standard.js +1 -1
  34. package/dist/sdk/remote/webClient.js +6 -2
  35. package/dist/sdk/sessions/contracts.d.ts +2 -0
  36. package/dist/sdk/sessions/contracts.js +5 -1
  37. package/dist/sdk/sessions/planMode.d.ts +16 -6
  38. package/dist/sdk/sessions/planMode.js +59 -23
  39. package/dist/sdk/sessions/runner.js +14 -5
  40. package/dist/sdk/sessions/workSlice.d.ts +15 -1
  41. package/dist/sdk/sessions/workSlice.js +17 -9
  42. package/dist/sdk/terminal/controller.d.ts +6 -0
  43. package/dist/sdk/terminal/controller.js +44 -5
  44. package/dist/sdk/terminal/opentui/model.js +3 -1
  45. package/dist/sdk/terminal/piExtension.js +7 -2
  46. package/dist/sdk/terminal/stallWatch.d.ts +18 -0
  47. package/dist/sdk/terminal/stallWatch.js +20 -0
  48. package/dist/sdk/terminal/subagentMonitor.d.ts +2 -0
  49. package/dist/sdk/terminal/subagentMonitor.js +4 -1
  50. package/dist/sdk/terminal/terminals.js +35 -4
  51. package/dist/sdk/terminal/toolName.d.ts +6 -0
  52. package/dist/sdk/terminal/toolName.js +12 -0
  53. package/dist/sdk/terminal/tui/commandPages.d.ts +1 -1
  54. package/dist/sdk/terminal/tui/commandPages.js +3 -0
  55. package/dist/sdk/terminal/tui/commands.d.ts +14 -0
  56. package/dist/sdk/terminal/tui/commands.js +4 -1
  57. package/dist/sdk/terminal/tui/pages/followUpQueuePage.d.ts +34 -0
  58. package/dist/sdk/terminal/tui/pages/followUpQueuePage.js +130 -0
  59. package/dist/sdk/terminal/tui/pages/trajectoryPage.js +37 -7
  60. package/dist/sdk/terminal/tui/runtime.js +2 -1
  61. package/dist/sdk/terminal/tui/settingsModel.js +88 -7
  62. package/dist/sdk/tools/askUser.js +2 -2
  63. package/dist/sdk/world/world.d.ts +12 -2
  64. package/dist/sdk/world/world.js +42 -4
  65. package/dist/terminal-opentui.js +1456 -756
  66. package/dist/terminal-pi.js +62 -31
  67. package/docs/README.md +1 -0
  68. package/docs/architecture/02-sessions-and-runs.md +43 -25
  69. package/docs/architecture/04-prompt.md +23 -22
  70. package/docs/architecture/10-server-protocol.md +23 -3
  71. package/docs/architecture/11-terminal.md +41 -29
  72. package/docs/architecture/12-storage.md +2 -1
  73. package/docs/architecture/13-world-tools.md +35 -22
  74. package/docs/architecture/14-surfaces-and-parity.md +24 -20
  75. package/docs/architecture/README.md +4 -1
  76. package/docs/architecture/proposals/PROP-0026-connected-sketch-display.md +3 -1
  77. package/docs/decisions/ADR-0027-connected-sketch-display.md +4 -2
  78. package/docs/decisions/ADR-0076-codex-final-answer-verbatim.md +6 -1
  79. package/docs/decisions/ADR-0077-plan-runs-may-conclude-no-plan-needed.md +120 -0
  80. package/docs/decisions/ADR-0078-child-aware-stall-watch.md +46 -0
  81. package/docs/decisions/ADR-0079-phase-led-reporting-guidance.md +72 -0
  82. package/docs/decisions/ADR-0080-fixed-width-question-sketch-canvas.md +50 -0
  83. package/docs/decisions/ADR-0081-no-work-slice-budget-by-default.md +36 -0
  84. package/docs/decisions/ADR-0082-connected-brave-browser.md +72 -0
  85. package/docs/parity.md +7 -5
  86. package/docs/releases/1.5.0-unstable.md +12 -3
  87. package/docs/releases/1.5.1-unstable.md +24 -0
  88. package/docs/releases/1.6.0-unstable.md +59 -0
  89. package/docs/study/00-index.md +17 -1
  90. package/docs/study/STUDY-0007-claude-code-prompt.md +162 -0
  91. package/docs/study/STUDY-0008-browser-control.md +281 -0
  92. package/docs/study/STUDY-0009-claude-code-reporting.md +205 -0
  93. package/docs/study/sources/claude-code.md +51 -39
  94. package/docs/terminal-tui.md +46 -18
  95. package/package.json +2 -1
@@ -62,20 +62,25 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
62
62
  is no terminal-only question alias (PROP-0040).
63
63
  - The approved plan outcome contract on page 02 applies equally to the terminal and server:
64
64
  only `plan_ready` offers a plan card and Implement; `blocked` reports unavailable required input
65
- without Implement; `invalid` gets at most one shared bounded repair and, if still invalid, a
66
- warning and the retained original text. New final replies do not ask free-text questions or use
65
+ without Implement; `no_plan` is an ordinary reply that offers nothing at all; `invalid` gets at
66
+ most one shared bounded repair and, if still invalid, a warning and the retained original text.
67
+ New final replies do not ask free-text questions or use
67
68
  `<plan_clarification>`: clarification uses `ask_user`, which blocks the active run. Repair at
68
69
  Pi's settlement boundary is in the same run and may call `ask_user`. Existing `<proposed_plan>`
69
- cards and old transcripts, including clarification blocks, remain intact; see ADR-0058.
70
+ cards and old transcripts, including clarification blocks, remain intact; see ADR-0077.
70
71
  - A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
71
72
  (PROP-0043). A user `!` command submitted during a plan request waits as a separate turn; it
72
73
  cannot run inside the plan's read-only request.
73
74
  - The terminal message-delivery contract is Enter to send or queue a follow-up, and
74
75
  Cmd/Ctrl/Alt+Enter to steer an active reply. Pending steering, follow-up and deferred plan/Bash
75
- inputs are projected above the working line from Pi's queues and the deferred barrier. Pi's
76
- projection may briefly include an item already taken for delivery. A queued plan or Bash command
77
- runs separately after the active reply, and later inputs cannot bypass it through Pi's native
78
- queues. Modified shortcuts require terminal support.
76
+ inputs are projected above the working line from Pi's queues and the deferred barrier. Native
77
+ Follow-up and Steer rows are clickable and open `/follow-up`, which edits, sends the next eligible
78
+ item, or removes a selected message while preserving attached images. A successful reply keeps
79
+ Pi's configured queue behavior. At an explicit user-stop boundary, the terminal sends one
80
+ unconsumed steer before any follow-up and returns the remainder to Pi; retrying requests,
81
+ provider failures and non-user interruptions do not dispatch the queue. A queued plan or Bash
82
+ command runs separately after the active reply, and later inputs cannot bypass it through Pi's
83
+ native queues. Modified shortcuts require terminal support.
79
84
  - Current standalone source defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
80
85
  `~/.xingular-harness-dev/{data,state}`. The standalone development launch uses a file SecretStore
81
86
  under its resolved state directory or the `--account-state` one, even when its profile names a
@@ -261,9 +266,14 @@ the focused list or action list. Account actions retain their Session, Account,
261
266
  groups; pool actions remain grouped under Manage and Remove. See the
262
267
  [terminal guide](../terminal-tui.md#blocks-and-pages) for layout and interaction.
263
268
 
264
- `/settings` is a full-screen page with category tabs, search, settings list and the device-local
265
- Browser tab for `allowPrivate`. Enabling private address access requires confirmation and allows both
266
- agent browsing and annotation capture to reach localhost and private networks. It is off by default.
269
+ `/settings` is a full-screen page with category tabs, search, settings list and a device-local Browser
270
+ tab. It selects the isolated browser or Brave profile; selecting Brave requires explicit confirmation.
271
+ The tab also shows bridge status, pairing instructions and `allowPrivate`. Brave pairing is explicit,
272
+ site access is granted separately in the extension popup, and the in-page badge provides Pause and
273
+ Stop. Brave exposes normal tabs only, never Incognito; the extension does not request history or
274
+ cookie permissions or export cookies. A disconnect refuses calls without switching backends.
275
+ Enabling private address access requires confirmation and allows both agent browsing and annotation
276
+ capture to reach localhost and private networks. It is off by default.
267
277
 
268
278
  ## Worktrees command (PROP-0016)
269
279
 
@@ -305,16 +315,17 @@ pan the sketch horizontally or vertically.
305
315
  When a question sets `uiSketch: true`, one shared border-only monospace preview below the choices
306
316
  shows the hovered or focused choice's ASCII wireframe, with no visible caption or extra left rule.
307
317
  Sketch source supports up to 80 columns by 24 lines (page 02) and remains literal ASCII in
308
- persistence. The terminal uses a bounded structural display projection: recognized ASCII table-border
309
- rows—including a title between horizontal runs—and enclosed vertical table edges become connected
310
- box-drawing glyphs, while internal framed tables retain their original widths and positions. For a
311
- high-confidence frame with matched `+` corners, missing or slightly displaced side edges may be
312
- filled or moved only through whitespace to the established boundary columns; interior text is never
313
- moved or overwritten, and conflicting or ambiguous rows remain literal. Bare standalone hyphen
314
- divider rows expand to `max(panel viewport width, original sketch widest line)` and join the outer
315
- single-line preview frame with `├` and `┤`. This is not a global `+|-` substitution: prose, content
316
- operators, ordinary pipes and unrecognized rows remain literal. Source sketches and all persisted
317
- whitespace remain unchanged; only the display projection adjusts recognized boundary cells.
318
+ persistence. The terminal projects every valid sketch onto a fixed 80-column content canvas, padding
319
+ short rows and extending standalone hyphen dividers to that width. The outer preview frame stays
320
+ bounded to the available dock width and the canvas remains horizontally pannable when it does not
321
+ fit. Within the canvas, recognized ASCII table-border rows—including a title between horizontal
322
+ runs—and enclosed vertical table edges become connected box-drawing glyphs, while internal framed
323
+ tables retain their original widths and positions. For a high-confidence frame with matched `+`
324
+ corners, missing or slightly displaced side edges may be filled or moved only through whitespace to
325
+ the established boundary columns; interior text is never moved or overwritten, and conflicting or
326
+ ambiguous rows remain literal. This is not a global `+|-` substitution: prose, content operators,
327
+ ordinary pipes and unrecognized rows remain literal. Source sketches and all persisted whitespace
328
+ remain unchanged; padding, projected glyphs and expanded dividers exist only in the display.
318
329
 
319
330
  There is no wrapping, reflow, truncation or markup interpretation. A bounded two-axis viewport makes
320
331
  all overflow reachable by panning. Moving focus changes the preview without changing the staged
@@ -322,7 +333,8 @@ answer. Projected glyphs and expanded dividers never enter persisted events or a
322
333
  contract is unchanged. See [PROP-0025](proposals/PROP-0025-contextual-question-wireframes.md),
323
334
  [ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md) and the approved display amendment
324
335
  [PROP-0026](proposals/PROP-0026-connected-sketch-display.md) /
325
- [ADR-0027](../decisions/ADR-0027-connected-sketch-display.md), and
336
+ [ADR-0027](../decisions/ADR-0027-connected-sketch-display.md), amended for the fixed canvas by
337
+ [ADR-0080](../decisions/ADR-0080-fixed-width-question-sketch-canvas.md), and
326
338
  [PROP-0028](proposals/PROP-0028-normalize-question-wireframes.md) /
327
339
  [ADR-0029](../decisions/ADR-0029-normalized-question-wireframe-borders.md). Isolated production
328
340
  PTY verification is retained in `docs/evidence/terminal-wireframe-normalization/`; it establishes
@@ -376,21 +388,21 @@ release.
376
388
 
377
389
  Terminal tool-gate and work-slice refusals are relayed as `tool.refused` events with a code and reason; the original refusal text remains the tool response. Interrupted terminal runs record stop codes for work-slice limits, user abort, stalls and terminal closure.
378
390
 
379
- Terminal replies carry the same work-slice guard as structured runs: 320 tool calls or 60 minutes,
380
- with no new-token limit by default (PROP-0044), then a refusal that asks the model to stop and report
381
- where it is. An ordinary terminal reply settles as it ends (INV-RUN-15, ADR-0075): the terminal
391
+ Terminal replies carry the same work-slice guard as structured runs, with no budget by default
392
+ (ADR-0081): no tool-call, time or token limit. When a limit is set (below), the guard refuses the
393
+ next call and asks the model to stop and report where it is. An ordinary terminal reply settles as it ends (INV-RUN-15, ADR-0075): the terminal
382
394
  never sends it back and never marks it unfinished from the todo list. A `/goal` is the only layer
383
395
  that continues a reply; a goal that stops blocked, paused or at a limit sends a harness-written
384
396
  `checkpoint` and the `needs_person` or `unfinished` code, which the controller records on the active
385
397
  run, so an App reading the same session sees the handoff. No model judges an ordinary reply. A reply that
386
- reaches its budget after doing work continues in place as its next slice (ADR-0070): a
398
+ reaches a budget someone set, after doing work, continues in place as its next slice (ADR-0070): a
387
399
  `xingular-slice-continue` message in the same run, a checkpoint and a notice per boundary, up to
388
- `maxSlices` (8). A fruitless, blocked, failed, aborted or plan slice, or one whose todo items are all
400
+ `maxSlices` (8 by default). A fruitless, blocked, failed, aborted or plan slice, or one whose todo items are all
389
401
  done, is not continued; the reply then settles `interrupted` with terminal reason `slice_complete`
390
402
  so the person or a host can continue it. A checkpoint card in the transcript is not built yet
391
- (PAR-004). Start the terminal with `XINGULAR_WORK_SLICE=off` to launch a reply with no boundary at
392
- all, or with key=value pairs such as `maxToolCalls=15,maxSlices=3` for a smaller policy; neither is
393
- persisted, so the next launch without it restores the defaults.
403
+ (PAR-004). Start the terminal with key=value pairs such as `XINGULAR_WORK_SLICE=maxToolCalls=15,maxSlices=3`
404
+ to give replies a budget; `off` also disables the compaction guard. Neither is persisted, so the
405
+ next launch without it restores the default of no budget.
394
406
 
395
407
  ## `/goal` (ADR-0072, INV-RUN-16)
396
408
 
@@ -46,7 +46,8 @@ index.
46
46
  worktrees.json managed worktree registry (02, PROP-0016)
47
47
  worktrees/<repo>/<name>/ managed worktree checkouts; worktrees/logs/ setup output (PROP-0016)
48
48
  worktree-setup-trust.json trusted setup-script hashes, owner-only (PROP-0016)
49
- browser/ isolated browser settings and profiles (13)
49
+ browser.json device-local BrowserConfig: backend, CDP, private-address policy and domains (13)
50
+ browser/ isolated profiles, downloads, and owner-only extension-bridge.json pairing state (13, ADR-0082)
50
51
  notes-bridge.json the page bridge's port and token, kept so an app's script tag stays valid (13, PROP-0018)
51
52
  harness.log standalone terminal diagnostics
52
53
  ```
@@ -2,21 +2,28 @@
2
2
 
3
3
  The Foundation owns the generic isolated browser engine, per-session contexts and profiles,
4
4
  network policy, and lifecycle. Built-in World plugins contribute the user-facing web search/page
5
- tools, browser tools and annotations through the existing tool-provider surface. Every tool passes
6
- the same capability and policy gate. Web requests use the public-address guard; browser requests
7
- use the device-local private-address setting. Read page content is untrusted. Sending, purchasing,
8
- deleting, changing accounts and granting access require explicit human approval. Sensitive fields
9
- are not filled by the agent.
5
+ tools, browser tools and annotations through the existing tool-provider surface. The same
6
+ backend-neutral browser tools can also target an explicitly paired Brave extension, which controls
7
+ normal tabs on origins separately permitted by the person; Incognito is excluded, and the
8
+ extension never requests history or cookie permissions or exports cookies (page content can still
9
+ reflect the person's active sign-in). Every tool passes the same capability and policy gate. Web requests use the
10
+ public-address guard; isolated-browser requests use the device-local private-address setting. Read
11
+ page content is untrusted. Sending, purchasing, deleting, changing accounts and granting access
12
+ require explicit human approval. Sensitive fields are not filled by the agent. A disconnected or
13
+ paused Brave bridge refuses calls and never switches to another backend.
10
14
 
11
15
  The App owns its shared WebKit browser UI, private/shared tab policy, selected-file uploads,
12
16
  windows and the native computer bridge. These application objects do not enter the Harness.
13
17
  Other hosts may add backend capabilities and diagnostics through ToolProvider or WorldPart.
14
18
 
15
- Browser configuration is device-local. User-configured CDP attachment is explicit; diagnostics
16
- never attach to it. Doctor browser probes instead use disposable headless profiles and an offline
17
- synthetic page. Their input runs only after live-check confirmation, and their resources are
18
- released on completion, timeout or cancellation. Computer interaction needs a host-provided
19
- isolated surface; without one it is blocked.
19
+ Browser configuration is device-local. The selected backend is either the isolated engine or
20
+ Brave. The extension bridge listens only on loopback, pairs with a short-lived code, and persists
21
+ its bearer token and extension origin in owner-only state. Pairing validates the extension origin; subsequent calls require the bearer token and reject a mismatched Origin when present because service-worker fetches may omit that header. The extension uses the browser debugger
22
+ API. Chrome host grants can cover every port on a host, so the extension separately records each exact allowed origin (scheme, host and port) and checks it before exposing a tab; the loopback bridge permission alone never enables site access. It does not request history or cookie access or export cookies.
23
+ User-configured CDP attachment is explicit; diagnostics never attach to it. Doctor browser probes
24
+ instead use disposable headless profiles and an offline synthetic page. Their input runs only after
25
+ live-check confirmation, and their resources are released on completion, timeout or cancellation.
26
+ Computer interaction needs a host-provided isolated surface; without one it is blocked.
20
27
 
21
28
  ## Approved-window screenshot contract
22
29
 
@@ -50,28 +57,34 @@ verified authorization boundary before they can be exposed; an implementation th
50
57
  window confinement must refuse rather than post global input.
51
58
 
52
59
 
53
- ## Shared browser contract and native WebKit limits (PROP-0040)
60
+ ## Shared browser contract and host backend limits (PROP-0040, ADR-0082)
54
61
 
55
62
  `browser/contracts.ts` owns the backend-neutral names and input schemas for `browser_*` tools;
56
63
  providers adapt those definitions rather than inventing host-specific selectors. The isolated Harness
57
- backend supports accessibility snapshots and snapshot-scoped refs. A native WebKit host backend
58
- supports navigation, tab management, visible-text reads, page screenshots and page-level scrolling
59
- without a ref. It does not support accessibility snapshots, snapshot refs or ref-based
60
- click/type/select/scroll/screenshot, browser waits or keyboard presses. Native page screenshot
61
- implementation and authorization checks are present, but live host capture acceptance remains open.
64
+ backend and the connected Brave adapter support accessibility snapshots and snapshot-scoped refs.
65
+ The Brave adapter relays calls through the paired extension, enforces the extension's exact-origin allow list and
66
+ network policy, and invalidates refs when the page or debugger attachment changes. A native WebKit
67
+ host backend supports navigation, tab management, visible-text reads, page screenshots and
68
+ page-level scrolling without a ref. It does not support accessibility snapshots, snapshot refs or
69
+ ref-based click/type/select/scroll/screenshot, browser waits or keyboard presses. Native page
70
+ screenshot implementation and authorization checks are present, but live host capture acceptance
71
+ remains open.
62
72
 
63
73
  For an unsupported operation the native provider returns an explicit `browser_unsupported` refusal
64
74
  with “Nothing was done”; it never treats a snapshot ref as a selector and never silently switches to
65
- the isolated browser. The isolated Harness browser is an independent backend, not an automatic
66
- fallback for the native provider. A host plugin's `surfaces` description labels that fallback and its
67
- limits; it does not assert full browser parity.
75
+ another backend. The isolated Harness browser and Brave extension are separate device-selected
76
+ backends, not fallbacks for a host's native provider. The App's `browser_upload` remains its own
77
+ WebKit-only operation and is absent from the shared Brave tool set. A host plugin's `surfaces`
78
+ description labels its fallback and limits; it does not assert full browser parity.
68
79
 
69
80
  Plugin ownership and the Foundation boundary are recorded in PROP-0012, ADR-0014 and PROP-0020.
70
81
  World providers are assembled through `BuiltinPluginRegistry`; no eighth extension point is added.
71
82
 
72
- An embedding host may set `browser: false` to disable the generic backend and its plugin
73
- descriptor before supplying its own browser tool provider. The App uses this option for its
74
- shared-tab browser, so matching tool names never silently select the wrong backend.
83
+ An embedding host may set `browser: false` to disable the generic browser provider and its plugin
84
+ descriptor, then supply its own provider. `HarnessOptions.browserExtension` keeps the Harness-owned
85
+ Brave bridge available alongside that host provider. The App uses both options: its WebKit provider
86
+ remains separate, and Brave mode supplies `browserToolsForSession` from the Harness. Provider calls
87
+ are pinned to the selected backend and never fall through to another browser.
75
88
 
76
89
  ## Page notes (PROP-0017)
77
90
 
@@ -65,22 +65,24 @@ terminal command or page, a host screen.
65
65
  research; both terminal and host use the same gate and child-capability narrowing.
66
66
  - Question choice sketches use one optional validated event contract: up to 80 printable ASCII
67
67
  columns by 24 LF-separated lines (1,943 bytes maximum; page 02). Both surfaces use the same
68
- literal ASCII source, persisted unchanged, in one shared preview with access to overflow; neither
69
- changes the answer payload (PROP-0025, ADR-0026; originally PROP-0024). The terminal may project
70
- recognized ASCII table-border rows—including title-bearing rules—and enclosed vertical table
71
- edges into connected box-drawing glyphs, retaining internal framed table widths. For a
72
- high-confidence frame, it may fill a missing boundary cell or realign a displaced edge only
73
- through whitespace to matched corner columns; interior text and ambiguous rows remain unchanged
74
- (PROP-0028, ADR-0029). Bare standalone hyphen dividers expand to the larger of viewport width and
75
- original sketch widest line and join the outer single-line frame with `├` and `┤` (PROP-0026,
76
- ADR-0027). Prose, content operators and ordinary pipes are not globally substituted. Hosts may
77
- retain literal ASCII previews: equivalent capability does not require identical structural
78
- typography. No schema, validation-bound, persistence or answer-payload change follows from these
79
- display amendments. Terminal geometry, scrolling and projection boundaries follow page 11; hosts
80
- may use native presentation without narrowing accepted metadata. Existing hosts with the old
81
- bounds must update before accepting larger sketches. Acceptance of the expanded contract on both
82
- surfaces is tracked in the parity register. Isolated production PTY evidence verifies bounded
83
- fixture topology, not every emulator/font or live-model sketch quality.
68
+ literal ASCII source, persisted unchanged, and neither changes the answer payload (PROP-0025,
69
+ ADR-0026; originally PROP-0024). Shared `ask_user` guidance asks the model to use a fixed
70
+ 80-column canvas, but validation remains permissive for shorter sketches. The terminal pads its
71
+ display projection to 80 content columns, bounds the outer frame to the available dock width and
72
+ provides horizontal panning. It may project recognized ASCII table-border rows—including
73
+ title-bearing rules—and enclosed vertical table edges into connected box-drawing glyphs, retaining
74
+ internal framed table widths. For a high-confidence frame, it may fill a missing boundary cell or
75
+ realign a displaced edge only through whitespace to matched corner columns; interior text and
76
+ ambiguous rows remain unchanged (PROP-0028, ADR-0029). Bare standalone hyphen dividers expand to
77
+ the fixed 80-column canvas and join the outer frame with `├` and `┤` (PROP-0026, ADR-0027,
78
+ amended by ADR-0080). Prose, content operators and ordinary pipes are not globally substituted.
79
+ Hosts may retain literal ASCII previews with accessible overflow; equivalent capability does not
80
+ require identical structural typography. No schema, validation-bound, persistence or answer-payload
81
+ change follows from these display amendments. Terminal geometry, scrolling and projection
82
+ boundaries follow page 11; hosts may use native presentation without narrowing accepted metadata.
83
+ Existing hosts with the old bounds must update before accepting larger sketches. Acceptance of the
84
+ expanded contract on both surfaces is tracked in the parity register. Isolated production PTY
85
+ evidence verifies bounded fixture topology, not every emulator/font or live-model sketch quality.
84
86
  - Side questions use one Harness service on both surfaces. Each caller supplies its visible
85
87
  transcript projection; Harness adds the parent run's effective prompt and public events, then
86
88
  starts an independent tool-free run.
@@ -96,10 +98,12 @@ terminal command or page, a host screen.
96
98
  the terminal reports Pi's active tools and schemas, applying its plan-mode allowed set when active.
97
99
  It is in the shared plan-mode allowlist and grants no permission. Hosts use this Harness tool rather
98
100
  than defining a duplicate.
99
- - `browser/contracts.ts` owns shared backend-neutral browser schemas. A native WebKit host backend
100
- lacks accessibility snapshots and snapshot-ref interactions, waits and keyboard input; it supports
101
- page screenshots without refs in source, with live acceptance pending. Unsupported calls return an
102
- explicit refusal before effects and do not trigger an automatic backend switch (page 13, PAR-015).
101
+ - `browser/contracts.ts` owns shared backend-neutral browser schemas. The isolated Harness engine
102
+ and paired Brave extension implement the snapshot-ref contract. A native WebKit host backend lacks
103
+ accessibility snapshots and snapshot-ref interactions, waits and keyboard input; it supports page
104
+ screenshots without refs in source, with live acceptance pending. The App chooses WebKit or Brave
105
+ at the device level; unsupported calls return an explicit refusal before effects and never trigger
106
+ an automatic backend switch (page 13, PAR-015, ADR-0082).
103
107
  - Shared interactive defaults, profile adoption, credentials and a cross-surface session catalog
104
108
  remain in progress under PROP-0040. Existing pins and explicit profile choices win; adoption must
105
109
  not merge stores, copy credentials or silently downgrade the secret backend.
@@ -109,6 +109,9 @@ resolve relevant drift by updating the implementation and specification together
109
109
 
110
110
  | ID | Where | What disagrees |
111
111
  |---|---|---|
112
+ | D-27 | Subagent compaction, pages 02 and 04 | A subagent compacted at the context threshold (run `5cd1d8aa`, 2026-11-01) produced a summary whose `## Goal` read "No specific research question or task was provided" while its split-turn section kept the brief. The model that continued still had the task through the turn context, but the summary's headline contradicts it. Not resolved here; the cause (the brief sits in the split part of the turn) is not confirmed. |
113
+ | D-26 | App browser tool catalog, pages 13 and 14 (PAR-015) — rechecked with ADR-0082 | Brave mode now supplies all shared Harness browser tools except the App-only upload through `browserToolsForSession` (`agent-app/sidecar/src/app.ts:172-177`, `appTools.ts:91-126`); WebKit still filters unsupported snapshot/ref operations. The Rust `app.capabilities` response remains backend-agnostic (`src-tauri/src/app_tools.rs:111-123`), while its `TOOL_IDS` and shared contract contain the new Browser tools (`shared/contracts.ts:557-562`, `src-tauri/src/agents.rs:90-103`). Thus a connected Brave backend implements the advertised refs, but the capability catalog can still mark WebKit-unsupported tools available. Partly resolved; backend-aware capability reporting remains open. |
114
+ | D-25 | Native WebKit interaction, page 13 — rechecked with ADR-0082 | The Brave adapter now uses the shared ref-based definitions, but the App's Rust backend still routes `browser_click`, `browser_type` and the App-only `browser_upload` by CSS `selector` (`agent-app/src-tauri/src/browser_workspace.rs:1493`, `agent-app/shared/appTools.ts:20`). The shared provider refuses those WebKit operations and never maps refs to selectors. Open: extend the contract to selectors or remove the native selector paths. |
112
115
  | D-24 | Plan instruction delivery, pages 02 and 04 — resolved | The plan instruction exceeded its 4,000-character section budget, and the compaction checkpoint separately clipped it at 4,000 characters, risking loss of outcome rules. Both bounds are increased and covered by delivery tests so the complete current instruction survives compilation and compaction. |
113
116
  | D-23 | Terminal model-tool caller identity, pages 07 and 08 — resolved | `ownTools` used the session caller without the active run id, so `trajectory_read` with `run: 'current'` failed over `tools.call`. It now derives the caller on each execution and clears the identity after settlement. |
114
117
  | D-1 | `AGENTS.md` (before this spec), `INV-RUN-6` | The old rule said only `sessions/runStore.ts` writes `runs/<id>/`. In code, four other harness modules also write side files there: `prompt/compile.ts` (`context.json`), `sessions/sessions.ts` (`caller.json`), `capabilities/runSnapshot.ts` (`capabilities.json`), `mcp/service.ts` (`mcp-context.json`). The spec states the rule the code keeps (see `INV-RUN-6`); whether to route all of them through `runStore.ts` is open. |
@@ -124,7 +127,7 @@ resolve relevant drift by updating the implementation and specification together
124
127
  | D-11 | `INV-RUN-5`, unattended approval and question paths | Source inspection on 2026-10-23 found that `SessionRunInput.automatic` disables resource discovery and extension dialogs (`sessions/runner.ts:574`), but the general gate does not receive that flag. `Sessions.gate` explicitly refuses approvals for `probe`, `improver` and `reflection` triggers, then otherwise calls `requestApproval` (`sessions/sessions.ts:198`). `ask_user` was also constructed independently of `automatic` when harness tools were enabled (`sessions/sessions.ts:397`, `tools/askUser.ts:69`). That question-tool gap is resolved for newly resolved runs by PROP-0022/ADR-0022 (2026-10-24); an unattended continuation of a run pinned with that tool is rejected. Thus the flag alone does not establish the invariant that every unattended run refuses human interaction; host policy and capability selection can narrow these paths. This is a static source finding, not a live reproduction. See [proactive autonomy research](../study/proactive-autonomy.md#current-foundation-and-the-missing-loop). |
125
128
  | D-12 | 12-storage layout | The isolated browser keeps device-local profiles and settings under `<state dir>/browser/` (`browser/config.ts`, `browser/session.ts`); page 12's layout did not list it. Resolved 2026-10-23: page 12 lists it. |
126
129
  | D-13 | `docs/study/feature-gap-review.md` row 8 | Says browser and computer interaction are not built in. Page 13 (PROP-0012) records a generic isolated browser in the foundation; computer interaction needs a host surface. |
127
- | D-14 | 12-storage layout | Page 12 lists browser settings under `<state dir>/browser/`, while `browser/config.ts` stores configuration in `<state dir>/browser.json`; browser profiles and downloads use the `browser/` directory. The layout needs an owner decision before either side is changed. |
130
+ | D-14 | 12-storage layout — resolved with ADR-0082 | Page 12 now distinguishes `<state dir>/browser.json` (`BrowserConfig`) from `<state dir>/browser/` (profiles, downloads and owner-only extension pairing state), matching `browser/config.ts` and `browser/extension/bridge.ts`. |
128
131
  | D-15 | Terminal sketch verification status — resolved 2026-10-24 by PROP-0028 | Pages 11 and 14 and `terminal-tui.md` said connected-sketch implementation verification was pending, while retained PTY evidence and PAR-014 recorded it as verified. Updated the docs to distinguish deterministic fixture verification from owner visual acceptance, every-emulator rendering and live-model sketch quality. |
129
132
  | D-16 | Terminal slash-command highlighting — resolved 2026-10-24 | `terminal-tui.md` specified accent coloring for recognized leading commands while typing, but the OpenTUI composer only styled attachment labels. User-message bubbles also lacked command-token styling. The renderer now uses the active command registry for both surfaces. |
130
133
  | D-17 | `PROP-0039`, `ADR-0036`, `INV-GATE-3/8` | Implementation is in progress in the 1.2.0 worktree: native writes revalidate canonical targets and atomically replace files under an OS write scope; default Bash fails closed on external hard-link aliases and runs in a sandbox that prevents new cross-boundary links; outside-scope Bash requires approval before one execution and command output never triggers approval or replay. The filesystem root is rejected as a workspace, and approval details expose the complete command. Launcher selection uses fixed system paths. Same-user peer processes remain outside this boundary. Focused macOS tests, full Harness CI, App compatibility checks, and PTY verification at 40x20, 80x24, and 100x30 pass. Linux sandbox integration remains unverified locally because this Darwin host has no `bwrap` and Colima is stopped; both CI workflows now install bubblewrap and `scripts/ci.sh` fails if it is absent, but an Ubuntu run is still required. No candidate, tag, or publication exists. |
@@ -12,7 +12,9 @@ affects: [INV-PAR-1, INV-PAR-2, 11-terminal.md, 14-surfaces-and-parity.md, termi
12
12
  The owner approved this foundation presentation change with “yes, fix it” after inspecting a
13
13
  screenshot of disconnected sketch lines. Implementation and rendered-topology verification passed
14
14
  in isolated production fixtures; see [retained evidence](../../evidence/terminal-connected-sketches/README.md) and
15
- [ADR-0027](../../decisions/ADR-0027-connected-sketch-display.md).
15
+ [ADR-0027](../../decisions/ADR-0027-connected-sketch-display.md). The viewport-relative canvas and
16
+ divider sizing below were later amended by [ADR-0080](../../decisions/ADR-0080-fixed-width-question-sketch-canvas.md);
17
+ the connected-border projection remains in force.
16
18
 
17
19
  ## Problem
18
20
 
@@ -4,7 +4,7 @@ title: Project structural ASCII sketch lines into connected terminal borders
4
4
  status: accepted
5
5
  created: 2026-10-24
6
6
  updated: 2026-10-24
7
- related: [PROP-0026, ADR-0026, ADR-0029, INV-RUN-3, INV-PAR-1, INV-PAR-2]
7
+ related: [PROP-0026, ADR-0026, ADR-0029, ADR-0080, INV-RUN-3, INV-PAR-1, INV-PAR-2]
8
8
  supersedes: null
9
9
  superseded_by: null
10
10
  ---
@@ -13,7 +13,9 @@ superseded_by: null
13
13
 
14
14
  **Design accepted by the product owner on 2026-10-24** with “yes, fix it” after screenshot review.
15
15
  This foundation presentation change is implemented and verified in isolated production fixtures;
16
- see [retained evidence](../evidence/terminal-connected-sketches/README.md).
16
+ see [retained evidence](../evidence/terminal-connected-sketches/README.md). The viewport-relative
17
+ canvas and divider sizing was later amended by [ADR-0080](ADR-0080-fixed-width-question-sketch-canvas.md);
18
+ the structural projection rules below remain in force.
17
19
 
18
20
  ## Context
19
21
 
@@ -3,8 +3,9 @@ id: ADR-0076
3
3
  title: Codex's final-answer guidance, adopted verbatim
4
4
  status: accepted
5
5
  created: 2026-11-01
6
- updated: 2026-11-01
6
+ updated: 2026-11-02
7
7
  supersedes: ADR-0074 (its four content questions, human-check block, next-step block and examples)
8
+ amended_by: ADR-0079
8
9
  related:
9
10
  - ADR-0074
10
11
  - ADR-0075
@@ -16,6 +17,10 @@ related:
16
17
  > questions, the human-check block, the next-step block, the evidence table, the anti-pattern table
17
18
  > and the three examples are replaced by Codex's final-answer and technical-communication text.
18
19
 
20
+ > **Amended by [ADR-0079](ADR-0079-phase-led-reporting-guidance.md):** add the cold-reader test,
21
+ > explicit verification honesty, concise subagent reports and a preference for content-named `#` / `##`
22
+ > headings in substantial reports. The phase order is explicit; heading wording remains flexible.
23
+
19
24
  ## Context
20
25
 
21
26
  ADR-0074 replaced four required blocks with four content questions, a one-line evidence rule, an
@@ -0,0 +1,120 @@
1
+ ---
2
+ id: ADR-0077
3
+ title: A plan run may conclude that no plan is needed
4
+ status: accepted
5
+ created: 2026-11-02
6
+ updated: 2026-11-02
7
+ supersedes: ADR-0055 (its "every attended plan reply must carry a block" criterion), ADR-0057 and ADR-0058 (their repair criterion), not their mechanisms
8
+ related:
9
+ - ADR-0055
10
+ - ADR-0057
11
+ - ADR-0058
12
+ - ADR-0074
13
+ - ADR-0075
14
+ ---
15
+ # ADR-0077 — A plan run may conclude that no plan is needed
16
+
17
+ > **Supersedes the repair criterion of [ADR-0055](ADR-0055-plan-output-repair.md),
18
+ > [ADR-0057](ADR-0057-structured-plan-outcomes.md) and
19
+ > [ADR-0058](ADR-0058-ask-user-only-plan-clarification.md), not their mechanisms.** The same-run,
20
+ > one-attempt repair, the shared classification, the tool gate and the `<plan_blocked>` channel stay.
21
+
22
+ ## Context
23
+
24
+ Plan mode had no legitimate empty outcome. Its classification recognized `plan_ready` (one complete
25
+ `<proposed_plan>` block), `blocked` (required input that `ask_user` could not obtain) and `invalid`
26
+ for everything else, so a reply that concluded there was nothing to do was a formatting failure.
27
+ Two instructions then demanded an artifact: the plan section ended "end the reply with exactly one
28
+ block", and the hidden repair turn told the model to re-send its plan inside one block and offered
29
+ only a blocked block as the alternative.
30
+
31
+ The result is a fabricated plan. A person who asked the agent to plan work that already exists, or
32
+ who said not to plan at all, received a plan anyway: the harness's own instruction outranked the
33
+ person's, and the repair repeated it. Two live cases in one harness test session did exactly that —
34
+ a no-op plan whose only content restated the request, and then, after the person rejected it, a
35
+ second plan produced by the repair turn. The appetite for a required artifact had already been
36
+ rejected elsewhere: ADR-0074 removed the required report blocks, and ADR-0075 removed the stop gate.
37
+
38
+ A second defect sits beside the first. Tag accounting was a raw substring count over the whole
39
+ reply, so a reply that quoted plan syntax inside a fenced or inline code block declared extra
40
+ outcomes and became `invalid`. That is how a plan *about* the plan tags failed its own parser.
41
+
42
+ ## Decision
43
+
44
+ Add `no_plan` to the plan outcome contract:
45
+
46
+ | Reply ending | Outcome |
47
+ |---|---|
48
+ | One complete, nonempty `<proposed_plan>` block, outside code | `plan_ready` |
49
+ | One complete, nonempty `<plan_blocked>` block, outside code | `blocked` |
50
+ | No outcome tag at all, nonempty text | `no_plan` |
51
+ | Unbalanced, empty, duplicated or conflicting tags; legacy `<plan_clarification>`; empty reply | `invalid` |
52
+
53
+ - `no_plan` is a conclusion, not a failure. It offers no plan card, no Implement, no notice and no
54
+ warning in any surface, and it never costs a second model request.
55
+ - The plan section says that a reply with no block is a valid ending, that the model must check
56
+ whether the requested work already exists before designing it, and that a person's instruction
57
+ not to plan outranks the mode's output shape.
58
+ - The repair keeps its one bounded attempt, the same run and the same tool gate, but exists only
59
+ for `invalid`: a block the model started and left incomplete, empty or in conflict. It may finish
60
+ that block, may state that there is nothing to plan, or may return the blocked block. It may not
61
+ re-plan, research again, invent a decision or invent work to fill a block.
62
+ - Tags outside fenced and inline code alone declare an outcome; a quoted example is text. The rule
63
+ matches the one the App already used to split a plan out of a reply.
64
+
65
+ The outcome stays derived from reply text. No run event, run-record field, storage layout, server
66
+ method or host schema changes, so clients that understand only the plan tag keep working.
67
+
68
+ ## Rationale
69
+
70
+ The contract conflated *format* with *outcome*. Once the artifact is the only way to answer, every
71
+ honest "nothing to do" becomes a lie about the work, and the repair turn is the machinery that asks
72
+ for the lie. Making the empty conclusion explicit fixes the cause instead of the symptom, and it
73
+ keeps the plan card exactly where it is useful: on a reply that actually contains a plan.
74
+
75
+ Text-derived classification is cheaper than the alternatives. A `no_plan` tag would still demand an
76
+ artifact for every request. A plan tool would change the tool list at the moment the mode switches,
77
+ changing the cached prompt prefix in headless runs, and would need a new renderer path in the
78
+ terminal and the App. A declared free-text line (`No plan needed: …`) adds a phrase the model must
79
+ remember and makes its absence ambiguous again.
80
+
81
+ ## Consequences
82
+
83
+ - A plan request that needs no plan answers in ordinary prose. The person sees no card and no
84
+ warning, and the turn costs one request instead of two.
85
+ - A model that forgets the block for a real plan now loses the card and the Implement choice
86
+ silently. The reply text remains, and asking again produces the plan; the alternative was to keep
87
+ demanding an artifact that is sometimes fiction. The plan section still makes the block the
88
+ default when there is work to design.
89
+ - Plan mode read as "research-only mode" rather than "always produce a plan", which is what a bare
90
+ `/plan` toggle already meant in practice.
91
+ - Quoted or fenced plan syntax no longer invalidates a reply, so a reply may discuss the format
92
+ without being repaired.
93
+ - `blocked` is unchanged: it still reports a required decision that `ask_user` could not obtain, and
94
+ the terminal still warns about it.
95
+ - New final replies still must not use `<plan_clarification>` or free-text questions; `ask_user`
96
+ remains the clarification channel.
97
+
98
+ ## Alternatives
99
+
100
+ - **Keep requiring a block and allow a "nothing to do" sentence inside it.** Rejected: that is the
101
+ ceremony the defect is about, and it makes a no-op plan look like a plan.
102
+ - **Add a `<no_plan>` tag.** Rejected: symmetric and simple to parse, but it still forces an
103
+ artifact and a repair for every request, so the person's "do nothing" instruction is again
104
+ overridden.
105
+ - **Add a plan tool.** Rejected for now: it changes the tool list and the cached prompt prefix, and
106
+ needs new renderer paths in both surfaces, for a problem a classification change solves.
107
+ - **Drop the repair entirely.** Rejected: an incomplete block is a real, observable failure, and one
108
+ bounded turn fixes it without costing the card.
109
+ - **Keep raw substring counting.** Rejected: a reply that quotes the tags was already misclassified,
110
+ and with `no_plan` in place the false `invalid` would trigger the repair for a correct answer.
111
+
112
+ ## Checks
113
+
114
+ `src/sessions/planMode.test.ts` covers the outcome table, the code-fence rule, repair exclusion for
115
+ `no_plan` and the instruction text. `src/sessions/sessions.test.ts` covers a plain no-plan reply
116
+ with no repair and no warning, a repaired no-plan reply, and a malformed block repaired once.
117
+ `src/terminal/piExtension.lifecycle.test.ts`, `src/terminal/opentui/app.test.ts` and
118
+ `src/terminal/tui/runtime.socket.test.ts` cover the same contract at the terminal's settlement
119
+ boundary and in the plan choice. The App needs no code change: it renders a card only for a complete
120
+ block and shows nothing otherwise.
@@ -0,0 +1,46 @@
1
+ ---
2
+ id: ADR-0078
3
+ title: A reply waiting on subagents is judged by its children, and the working row names the wait
4
+ status: accepted
5
+ created: 2026-11-01
6
+ updated: 2026-11-01
7
+ related:
8
+ - ADR-0054
9
+ ---
10
+ # ADR-0078 — A reply waiting on subagents is judged by its children
11
+
12
+ ## Context
13
+
14
+ Run `da1a7e39` ("Fix follow-up steering UX") looked stuck for 19 minutes: a spinner and a random
15
+ verb on the working row, a spinning subagent, and a trajectory of 40 identical heartbeats. Nothing
16
+ was wrong. The parent was inside `wait_subagents` and its child (run `5cd1d8aa`) did a tool call or
17
+ a model request every minute until it finished. The person could not tell that from a hang, and the
18
+ harness could not either: the stall watch saw one tool running (30-minute limit) and none of the
19
+ child's progress, so a child that really wedged would have held the parent for half an hour and then
20
+ ended the parent, not the child.
21
+
22
+ Two other limits made real outages worse: Pi's default of three retries at 2, 4 and 8 seconds ended a
23
+ reply after about fourteen seconds of network trouble, and the retry showed only as a passing toast.
24
+
25
+ ## Decision
26
+
27
+ - Each subagent the terminal reply waits on has its own stall clock in `TerminalController`: its last
28
+ event other than a heartbeat and the tools it is inside. A child quiet for the reply window (15
29
+ minutes) or inside one tool for the tool window (30) is interrupted with reason `stalled`; the wait
30
+ returns it as `interrupted` and the parent continues without the person.
31
+ - While the only running tools of the reply are `wait_subagents` or `spawn_subagent`, the parent's own
32
+ rule is paused as long as a child answers to its own watch. It resumes if no child is tracked or a
33
+ child ignored the stop for five minutes.
34
+ - Heartbeats carry `activeTools` and `oldestToolMs`; the trajectory page shows what a beat was
35
+ inside and folds runs of beats into one row.
36
+ - The working row names the phase (waiting on subagents, a long tool, a silent model, a retry
37
+ countdown) in place of the verb whenever the verb would hide it.
38
+ - Model requests that fail for a transient reason are retried up to eight times over about four
39
+ minutes. A person's own `retry` settings are kept.
40
+
41
+ ## Consequences
42
+
43
+ A long, healthy wait is no longer cut short, and a wedged child no longer costs the parent. The
44
+ retry budget lengthens the time before a real outage reaches the person, and the row shows the
45
+ countdown meanwhile. Constants (15 and 30 minutes, five-minute grace, eight retries) are unchanged
46
+ or new knobs in `stallWatch.ts` and `retryPolicy.ts`.