@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,52 @@
1
+ ---
2
+ id: ADR-0054
3
+ title: A live terminal reply reports a heartbeat and ends when it stops making progress
4
+ status: Accepted
5
+ created: 2026-10-28
6
+ proposal: PROP-0041
7
+ ---
8
+
9
+ # ADR-0054: A live terminal reply reports a heartbeat and ends when it stops making progress
10
+
11
+ ## Context
12
+
13
+ A structured run emits a `heartbeat` every 30 seconds while it works, and the run sweep uses it to
14
+ settle a reply that stopped reporting (INV-RUN-14). A terminal reply emitted none: the extension sent
15
+ tool, message and usage telemetry, but never a heartbeat. Two consequences followed.
16
+
17
+ The sweep could not tell a wedged reply from one written before heartbeats existed, so it waited the
18
+ full 30-minute silence window, and then recorded `owner_gone` — "the owner process is gone" — while
19
+ the owner was alive and its turn was still pending. On 2026-10-28 a `deepseek-v4.1-flash` request in
20
+ a terminal session produced a partial tool call and then nothing for 38 minutes; a request earlier in
21
+ the same session stayed open for 2 h 13 min and ended only when the person typed the next message.
22
+ The run showed as `running` the whole time.
23
+
24
+ ## Decision
25
+
26
+ A terminal reply reports a `heartbeat` every 30 seconds for as long as its turn is live, with the
27
+ counters its work slice already keeps: steps, elapsed time, last tool, compactions, slice and the
28
+ call budget. The controller records it on the active run like any other telemetry, so the sweep's
29
+ existing five-minute heartbeat rule now applies to terminal replies.
30
+
31
+ A heartbeat proves the turn is alive, not that it is working, so the terminal controller also ends a
32
+ reply that produced no event other than heartbeats for fifteen minutes. It does that by asking the
33
+ native turn to abort through the command the extension already polls; the run records `interrupted`
34
+ with reason `stalled`. A reply whose oldest running tool has run for thirty minutes is ended the same
35
+ way. A reply with an unanswered approval or question is never cut short, because it is waiting on the
36
+ person, not on the model.
37
+
38
+ ## Rationale
39
+
40
+ The two windows are different questions. Five minutes of silence with no heartbeat means the process
41
+ stopped reporting, which the sweep settles; fifteen minutes of heartbeats with no progress means the
42
+ process is alive but the reply is not moving, which only the controller can end. Keeping both avoids
43
+ weakening the rule that protects a live but quiet turn: a long tool or a long reasoning stream still
44
+ reports its heartbeat, and the person answering a decision is never timed out.
45
+
46
+ ## Consequences
47
+
48
+ A model request that never returns is ended after fifteen minutes instead of running for hours, and
49
+ the record carries a reason that is true. Terminal replies now write one small event every 30
50
+ seconds (about 60 KB an hour), the same as a bounded structured reply. No tool, permission, run-event
51
+ schema or stored-data layout changes: `heartbeat` already exists in the stream, and the reason
52
+ `stalled` is already part of the contract.
@@ -0,0 +1,51 @@
1
+ ---
2
+ id: ADR-0055
3
+ title: An attended plan run repairs a missing plan block once, in the same run
4
+ status: Accepted
5
+ created: 2026-10-28
6
+ ---
7
+
8
+ # ADR-0055: An attended plan run repairs a missing plan block once, in the same run
9
+
10
+ ## Context
11
+
12
+ Plan mode ends with a `<proposed_plan>` block that both the terminal and the App parse into a plan
13
+ card and the Implement choice. The block is an instruction to the model, not a schema, and a model
14
+ can omit it while still writing a correct plan body. On 2026-10-28 two attended plan runs in one
15
+ terminal session did exactly that: the plan instructions and the plan-only tool set were present,
16
+ the model's reasoning said it would tag the plan, and the final text had no block. The renderer then
17
+ showed ordinary assistant text with no card, no plan choice and no Implement.
18
+
19
+ The tag contract is deliberately text-only: it keeps the plan tool list and the cached prompt prefix
20
+ unchanged when the mode switches. Replacing it with a plan tool or a plan artifact would change that
21
+ boundary, the protocol and both renderers for a rare omission.
22
+
23
+ ## Decision
24
+
25
+ When a top-level attended plan run ends without a complete plan block, the harness makes one hidden
26
+ format-repair turn in the same run. The custom message is not displayed, carries no new user
27
+ request, and asks the model to re-send its own plan, unchanged, in one complete block; a model that
28
+ was asking for input answers `No plan:` instead. The repair is attempted once, uses the same plan
29
+ tool set and gate, and is skipped for plan-research children, commands, probes, improvers,
30
+ reflections and other unattended runs.
31
+
32
+ If the repair also fails, the plan run still completes: the original reply stays in the transcript,
33
+ the harness records an `extension.notice` warning, and the terminal shows a warning instead of a
34
+ plan choice. The App shows the repaired card when the repair succeeds and otherwise keeps the
35
+ untagged reply.
36
+
37
+ ## Rationale
38
+
39
+ The repair is the smallest change at the ownership layer that preserves the existing plan contract and
40
+ both surfaces. It does not fabricate a plan or guess where one starts, and it leaves the plan tool
41
+ list, the prompt prefix and the run event schema unchanged. Asking the model to re-send its own
42
+ answer is cheaper and less disruptive than re-planning, and a single bounded attempt keeps the extra
43
+ cost and latency predictable.
44
+
45
+ ## Consequences
46
+
47
+ An attended plan run may make one additional model request and produce a second assistant message;
48
+ the first untagged reply remains visible. The extra request is counted in the run's usage, and the
49
+ run record, status and event types are unchanged. If the repair proves insufficient, a structured
50
+ plan tool or artifact remains the durable follow-up, but it changes the tool list, the cached prefix
51
+ and both renderers and is not part of this decision.
@@ -0,0 +1,53 @@
1
+ ---
2
+ id: ADR-0056
3
+ title: Remote control connects a phone directly to the terminal session, with sealed frames
4
+ status: Accepted
5
+ created: 2026-10-28
6
+ ---
7
+
8
+ # ADR-0056: Remote control connects a phone directly to the terminal session, with sealed frames
9
+
10
+ ## Context
11
+
12
+ A person wants to keep a terminal session going from a phone or iPad, the way Claude Code's
13
+ `/remote-control` (`/rc`) does: the session keeps running on the computer, and the phone sends
14
+ messages, watches the reply, stops it and answers approvals. Claude Code reaches the phone through
15
+ Anthropic's cloud relay. The harness has no cloud service, and every listener it had bound only
16
+ 127.0.0.1.
17
+
18
+ ## Decision
19
+
20
+ `/remote-control` (`/rc`) starts a small HTTP server in the `xagent` parent process, bound to one
21
+ address: the computer's Tailscale address when it has one, otherwise its private Wi-Fi or LAN
22
+ address. The terminal shows a QR code for a pairing link whose key is in the URL fragment. A phone
23
+ that opens it asks to pair; the person at the terminal allows it; the phone receives its own key.
24
+ The phone then becomes a second person at the terminal, with the same powers and the same paths:
25
+ `Terminals.send` and the terminal controller's interrupt and decision calls (page 15).
26
+
27
+ Every request and event body is a NaCl `secretbox` frame under the link or device key, with a
28
+ replay counter. All keys live in memory and end with the session.
29
+
30
+ ## Rationale
31
+
32
+ - **Direct, not relayed.** A relay is a service to build, run and trust. A direct connection
33
+ needs nothing outside the computer, and Tailscale covers the "away from home" case with its own
34
+ end-to-end encryption.
35
+ - **Sealed frames, not TLS.** A LAN page cannot have a trusted certificate, and a self-signed one
36
+ shows a warning a person learns to click through. Over plain HTTP the browser has no WebCrypto,
37
+ so the page uses `tweetnacl`, served beside it. The key never crosses the network: it reaches the
38
+ phone in the QR code's fragment.
39
+ - **Confirmation at the terminal.** A photographed QR code is not enough to pair; the person at the
40
+ terminal sees the device and allows it.
41
+ - **In-memory keys.** Nothing to revoke later, nothing on disk (INV-ACC-3), and the link dies with
42
+ the session.
43
+
44
+ ## Consequences
45
+
46
+ - New harness module `src/remote/`, a new spec page (15), and two dependencies: `tweetnacl` (also
47
+ served to the phone) and `uqr` (QR encoding).
48
+ - The terminal extension now reports streamed assistant text, batched, as `delta` telemetry, and
49
+ terminal runs record `message.delta` events the way structured runs already do.
50
+ - An attacker who can change LAN traffic could serve a changed page to the phone; the terminal
51
+ confirmation and the advice to use Tailscale on untrusted networks are the mitigation.
52
+ - The App presents remote control only as a stub for now (`PAR-018`): its sessions are not
53
+ terminal sessions.
@@ -0,0 +1,39 @@
1
+ ---
2
+ id: ADR-0057
3
+ title: Structured outcomes for attended plan requests
4
+ status: Accepted
5
+ ---
6
+
7
+ # ADR-0057: Structured outcomes for attended plan requests
8
+
9
+ ## Context
10
+
11
+ A reply asking for a decision is not a finished plan. ADR-0055 prescribes one repair for a missing
12
+ plan block, but the prior server parser recognized only `<proposed_plan>` and could treat a request
13
+ for input as a format failure. The terminal did not run that repair. D-22 records the prior
14
+ implementation gap and documentation ambiguity.
15
+
16
+ ## Decision
17
+
18
+ An attended top-level plan reply has one classified outcome: `plan_ready` for a complete existing
19
+ `<proposed_plan>` block, `needs_input` for a complete `<plan_clarification>` block containing the
20
+ needed question or explanation, and `invalid` for missing, incomplete, conflicting or malformed
21
+ outcome blocks. Only `plan_ready` permits a plan card and Implement. `needs_input` is displayed as
22
+ input needed, never as an actionable plan. The same classification and bounded repair belong to the
23
+ Harness and apply to both server and terminal, rather than independent surface heuristics.
24
+
25
+ When `ask_user` is available, it blocks for the person's answer and the same run continues; the
26
+ clarification outcome describes input still needed at the end, including when interaction is not
27
+ available. The model must not invent a decision. For an eligible run ending in `invalid`, one hidden
28
+ repair turn in the same run requests a valid outcome without changing substance or inventing
29
+ answers. Either valid outcome ends repair. If repair fails, retain the original text, complete with
30
+ a warning, and offer no Implement. Skip repair for unattended or child runs, commands, aborts,
31
+ errors and work-slice termination. The plan gate remains in force.
32
+
33
+ ## Compatibility and consequences
34
+
35
+ This supersedes ADR-0055's plan-only repair criterion, not its bounded same-run mechanism. Existing
36
+ `<proposed_plan>` output and cards remain valid; no new tool, mandatory event type, changed stable
37
+ prompt prefix or widened permissions are required. Older clients may show clarification as ordinary
38
+ text, but must not interpret it as a plan. Historical untagged replies remain visible without being
39
+ fabricated into plans. D-22 is resolved by shared classification and bounded repair on both paths.
@@ -0,0 +1,36 @@
1
+ ---
2
+ id: ADR-0058
3
+ title: Ask-user-only plan clarification
4
+ status: Accepted
5
+ ---
6
+
7
+ # ADR-0058: Ask-user-only plan clarification
8
+
9
+ ## Context
10
+
11
+ ADR-0057 allowed a final `<plan_clarification>` containing a question or explanation. That creates
12
+ another clarification channel alongside the blocking `ask_user` tool and can end a run instead of
13
+ continuing planning after the person's answer.
14
+
15
+ ## Decision
16
+
17
+ For new attended top-level plan final replies, the shared server and terminal classification is
18
+ `plan_ready`, `blocked`, or `invalid`. A complete `<proposed_plan>` is `plan_ready` and alone offers
19
+ a plan card and Implement. If a required user decision cannot be obtained because `ask_user` is
20
+ unavailable, the reply is `blocked`: explain the blocker without inventing the decision, asking a
21
+ free-text question, or offering Implement. Malformed, missing or conflicting outcomes are `invalid`.
22
+ New final replies do not use `<plan_clarification>` or free-text questions for clarification.
23
+
24
+ When `ask_user` is available and clarification is needed, call it: it blocks the active run for the
25
+ answer, after which the same run continues. The existing one bounded hidden repair for an eligible
26
+ `invalid` outcome remains in the same run and under the same plan gate; it may call `ask_user` and
27
+ wait for the answer. If repair remains invalid, retain the original reply, warn and offer no
28
+ Implement. The existing repair exclusions remain in force.
29
+
30
+ ## Compatibility and consequences
31
+
32
+ This supersedes ADR-0057's `needs_input` and `<plan_clarification>` final-outcome decision, not its
33
+ shared classification, bounded repair or other safeguards. Old transcripts remain intact and
34
+ visible, including historical clarification blocks; they are not rewritten or promoted into plans.
35
+ Existing plan cards, run events, permissions and the cached prompt boundary remain compatible. This
36
+ is an approved contract; implementation and surface acceptance must be verified separately.
package/docs/parity.md CHANGED
@@ -22,27 +22,27 @@ implemented is not a parity claim; acceptance is tracked per command.
22
22
  | Capability | Harness owner | Method or tool | Terminal surface | App surface | Status | Gap |
23
23
  |---|---|---|---|---|---|---|
24
24
  | Sessions and turns | `sessions/` | `sessions.run`, `terminal.*` | the terminal itself | Solo chat | parity | — |
25
- | Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; bounded plan/todo context is restored after compaction | plan request, PlanCard; shared Harness checkpoint behavior | parity | — |
25
+ | Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; shared outcome and bounded repair; plan/todo context restored after compaction | plan request, PlanCard; shared Harness classification and checkpoint behavior | ADR-0058 clarification contract approved; implementation and surface acceptance not verified | — |
26
26
  | Capability discovery | `tools/getCapabilities.ts` | read-only `get_capabilities` | terminal extension reports Pi's active tools and schemas; shared plan allowlist includes it | structured Harness run uses the same tool; no duplicate App-owned tool | implemented; acceptance not recertified | — |
27
27
  | Bash command mode | `sessions/sessions.ts`, `sessions/initialBash.ts` | `initialBashCommand`; Bash `workspaceWriteScope` | `!command` defaults to workspace; `!outside command` asks before running once | same `!command` and `!outside command` composer semantics | parity | — |
28
28
  | Workspace-scoped writes | `core/workspace.ts`, `sessions/workspaceBoundary.ts`, `core/workspaceBashTool.ts`, `core/workspaceSandbox.ts`, `core/workspaceWriteOperations.ts` | pinned non-root `RunRecord.workspaceRoot`; native `edit`/`write`; Bash scope | revalidated atomic native writes; external-hard-link scan and Bash sandbox (Windows: no sandbox, each Bash call asks once, plan-mode Bash refused; ADR-0042); complete escaped outside command in scrollable approval details (deny if too small); no output-triggered retry | same Harness gate and full approval action in scrollable App details; App policy can tighten scope; Full Permission remains the eligible explicit bypass | parity | — |
29
- | Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock with scroll and copy | side-question dock through the shared service | parity | — |
29
+ | Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock; the answer renders as Markdown, with scroll and copy | side-question dock through the shared service | parity | — |
30
30
  | Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
31
31
  | Opening a link | `core/links.ts` | `links.open`; `HarnessOptions.linkOpener` (ADR-0047) | hover shows the hand pointer and recolours the link, Ctrl+click (the primary click on macOS, whose ⌘ the mouse protocol cannot report) opens web, `mailto:`, file and folder targets with the system handler, a refused link posts a notice | ⌘-click on macOS and Ctrl+click elsewhere opens with the system handler, a plain click keeps the sidebar and falls back to the system for what it cannot show, `a:hover` uses `--link-hover` | implemented; acceptance not certified | — |
32
- | Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | parity; terminal projection verified in isolated fixtures | — |
33
- | Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
32
+ | Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | existing question surface parity; ADR-0058 plan clarification contract not verified | — |
33
+ | Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles; per-profile and total child budgets enforced in `Subagents.spawn` (ADR-0052), with the same refusal result in both surfaces | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
34
34
  | Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*`; package profiles through `Loading.profilePaths` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete; package profiles listed under "From a plugin" and switched on `/plugins` | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
35
35
  | Run todo list | `tools/todo.ts` | `todo_write`, `runs.todo` (`runs.checklist` deprecated); terminal `todo` telemetry | registered in terminal sessions and their subagents; each write shows as a todo block in the transcript; `/todo` shows the current list; a subagent row shows its `n of m tasks` | `/todo` shows the current list on demand; each write is not rendered inline | terminal done; App shows it on demand | PAR-001 |
36
36
  | Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
37
- | Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
37
+ | Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts`, `terminal/stallWatch.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; every live reply heartbeats and a reply with no progress for fifteen minutes ends as `stalled`; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
38
38
  | Accounts | `accounts/` | `accounts.*` | `/accounts` | Accounts | parity | — |
39
39
  | Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
40
- | Skills | `plugins/`, `tools/dispatch.ts` | `skill_load` | `$name`, `/skill:name`, browser Skills tab | Capability, composer | parity | — |
40
+ | Skills | `plugins/`, `tools/dispatch.ts`, `prompt/compile.ts` | `skill_load`; `Launch.requiredSkills` | `$name` at any word start (required for that request), `/skill:name`, browser Skills tab | composer `$` chip with `requiredSkills`; Capability | implemented; acceptance not recertified | — |
41
41
  | Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | full-screen `/plugins` local manager; separate full-screen `/hub` Community catalog with bounded registry/document Preview (no Pi-package Preview) | local Plugins manager; Community Hub with payload Preview for non-package entries | parity | — |
42
42
  | Plugin authoring and proposal review | `plugins/proposals.ts`, `tools/defaultSkills.ts` | `plugin_propose`, `plugins.proposals.*` | `/plugins` Proposals tab: preview, accept or reject | structured model tool and skill; review UI not implemented | partial; App review pending | PAR-017 |
43
43
  | Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
44
44
  | Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
45
- | Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read and page scroll without refs; unsupported operations refuse explicitly | partial; native backend gap | PAR-015 |
45
+ | Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read, page screenshot and page scroll without refs; unsupported operations refuse explicitly; live screenshot acceptance pending | partial; native backend gap | PAR-015 |
46
46
  | Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038, PROP-0048) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` page (Annotate and All annotations tabs; DevTools app list and launch), `/annotate:notes`, `/annotate:submit`, `/annotate:clear` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | App behind PROP-0048 (queue methods removed); native WKWebView gestures unaccepted | PAR-011 |
47
47
  | Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | Solo `/worktree` lists records only; Solo starts sessions in the project folder and has no worktree level | partial | PAR-012 |
48
48
  | Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `Terminals.ownTools` registers Wiki-read tools through the session socket; `xagent-wiki` remains a person-facing shell utility | structured Harness tools | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
@@ -53,10 +53,12 @@ implemented is not a parity claim; acceptance is tracked per command.
53
53
  | Doctor | `doctor/` | `doctor.*` | `/doctor` | diagnostics | parity | — |
54
54
  | Run inspection | `sessions/runStore.ts` | `runs.*` | `/trajectory`, `/log` | run views, analytics | parity | — |
55
55
  | Usage analytics | `usage/` (PROP-0042) | `usage.summary`, `usage.sync` | `/usage:`, `/usage:analysis` page (Analysis tab) | not wired | terminal implemented; host planned | PAR-016 |
56
+ | Remote control (ADR-0056) | `remote/` | protected `terminal.remoteControl.*`; phone calls through `Terminals.send` and the terminal controller | `/remote-control` (`/rc`) page with link, QR code, devices and pair confirmation; `rc` status-bar group; `--remote-control`; the served phone page | stub: App sessions are not terminal sessions | terminal only | PAR-018 |
57
+ | Context attribution (PROP-0049) | `context/` | `context.attribution`; protected `terminal.context` | `/context` page with Request and Growth tabs, a four-colour context bar with a free track and a compaction marker, `space` fold, `enter` row text, `g` grouping, `c` compact; the status band reads `18.3%/1M` | full-width Context page opened from the Context tab with the same four-colour bar and a screen-reader reading of it, composer ring reading the same share | implemented on both; acceptance not recertified | — |
56
58
  | Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
57
59
  | Session catalog (sessions per folder) | `sessions/` saved-history controls; shared catalog not implemented | `sessions.*` controls; no cross-surface catalog method | `/session` selects native Pi histories in the current folder | `/session` reads `bridge.agent.threads(SOLO_ID)`, maps each thread to its project folder, and filters by current effective account; `all` broadens only this App list | planned; catalogs differ | PAR-008 |
58
60
  | Folder choice and recent folders | project/worktree selection remains surface-specific | launch `cwd`, `--worktree`, `/worktree` | starts in launch folder; explicit worktree commands | Solo sidebar is Project › Session; new sessions use the project's folder, with no folder/worktree level | planned; no shared recent-folder picker | PAR-009 |
59
- | Computer control | — | `computer_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
61
+ | Computer control | `computer/screenshot.ts` defines an opt-in approved-window screenshot contract; other tools remain host-owned | `computer_*` (host tools) | no computer screenshot backend | macOS bridge (host-backed); its display capture has not adopted the approved-window contract | partial; screenshot contract not integrated | PAR-007 |
60
62
  | Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
61
63
 
62
64
  ## Core slash-command surfaces (PROP-0040)
@@ -77,6 +79,7 @@ this fixed table.
77
79
  | `/session` (`/resume`) | Search/select native saved history in the current folder | Lists App Solo threads by folder and effective account; `all` widens only within that App list | PAR-008: separate catalogs; no native-history path opening; not certified |
78
80
  | `/history` (`/tree`) | Navigate branches in the current native session | Calls `session.navigate` with stable native entry ID; same-session navigation, optional summary, no fork fallback | Route uses Harness `sessions.navigate`; per-command acceptance pending |
79
81
  | `/fork` | Fork from a user message | Uses session tree/fork and opens the new session | Not certified per command |
82
+ | `/remote-control` (`/rc`) | Pairing link, QR code and devices; phone page served by the harness | Stub notice: remote control runs from an `xagent` terminal session | PAR-018; terminal only |
80
83
  | `/clone` | Clone the current branch | Uses session clone and opens the copy | Not certified per command |
81
84
  | `/model` | Choose model | App model picker updates session runtime | Not certified per command |
82
85
  | `/effort` | Choose reasoning effort | Updates session runtime effort | Not certified per command |
@@ -118,6 +121,7 @@ or live-model sketch quality.
118
121
 
119
122
  | ID | Gap | Planned change |
120
123
  |---|---|---|
124
+ | PAR-018 | Remote control from the App | `/remote-control` drives an `xagent` terminal session from a phone (page 15). App sessions are structured runs, not terminal sessions; the App would need the same pairing over its own session controls, or to present a terminal session's remote control. |
121
125
  | PAR-017 | Plugin proposal review surfaces | The terminal provides hash-bound review in `/plugins`; the App has no proposal review UI yet. |
122
126
  | PAR-001 | Todo list not rendered inline in the App | Both surfaces can show the current list: the terminal renders each write as a todo block and `/todo` shows a snapshot; the App's `/todo` shows a read-only list. The App still does not draw an inline block for each write. |
123
127
  | PAR-002 | Acceptance of terminal-model History/Wiki/skill tools | Source gap resolved: `Terminals.ownTools` registers History/trajectory, Wiki-read and skill tools over the session socket; `xagent-wiki` is a user-facing shell utility, not the model's only route. Acceptance has not been recertified in this documentation pass. |
@@ -125,7 +129,7 @@ or live-model sketch quality.
125
129
  | PAR-004 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
126
130
  | PAR-005 | Wiki browsing only in the App | A `/wiki` page over `wiki.*`. |
127
131
  | PAR-006 | Acceptance of terminal first-party hooks | Source gap resolved: enabled hooks are returned by protected `firstParty.list` and loaded by `terminal/piExtension.ts`. Acceptance has not been recertified in this documentation pass. |
128
- | PAR-007 | Host tools without a Harness owner | Decide each: computer control stays host-backed (terminal shows unavailable); the files vault becomes a Harness capability or is dropped. |
132
+ | PAR-007 | Host tools without a complete Harness surface | The opt-in screenshot contract exists, but terminal availability reporting and a conforming host backend are not wired. The current macOS host captures a display, not an isolated approved window. The remaining computer controls are host-owned; the files vault becomes a Harness capability or is dropped. |
129
133
  | PAR-008 | Separate session catalogs | Proposal approved; shared catalog is not implemented. Terminal `/session` selects native Pi history in the current folder. App `/session` reads Solo `agent.threads`, maps threads through Solo project groups, and filters to the current effective account and folder; `/session all` broadens only within that App catalog. It cannot open an arbitrary native session path. No cross-surface catalog or visibility guarantee exists. |
130
134
  | PAR-009 | Shared folder/recent-project choice | Terminal starts from its launch `cwd` and can switch through its worktree surface. App Solo uses Project › Session and starts new sessions in the selected project's folder; it has no folder/worktree level or shared recent-folder picker. |
131
135
  | PAR-010 | Agent profile management in Solo | App Solo `/agents` can list profiles. Although the renderer allowlist includes `agents.get`, Solo does not wrap it; `agents.create/remove` are not exposed there. Profile details and management actions are unavailable, unlike terminal `/agents`. |
@@ -134,4 +138,4 @@ or live-model sketch quality.
134
138
  | PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |
135
139
  | PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |
136
140
  | PAR-016 | Usage analytics and provider limits in the App | The terminal has `/usage:analysis` and `/usage:limit` over `usage.*`. The App presents the same capability: an analytics view and a per-account provider limit view. |
137
- | PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads and scrolling without refs. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll), browser screenshots, waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |
141
+ | PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads, page screenshots and scrolling without refs; live screenshot acceptance is pending. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll/ref-screenshot), waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |
@@ -0,0 +1,54 @@
1
+ # Xingular Harness 1.3.1-unstable.3
2
+
3
+ Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
4
+
5
+ - Name a skill anywhere in a message: `$name` at any word start makes that skill required for the
6
+ request (ADR-0048). `Launch.requiredSkills` carries it, and the compiler renders a
7
+ `required-skills` section at order 52 from the pinned variant through `readSkillFile`, bounded at
8
+ 12,000 characters. An unavailable skill is named honestly instead of invented, and the built-in
9
+ `plugin-authoring` skill stands in when the variant ships no skills. The section belongs to the
10
+ request, so an identical one is delivered again rather than deduplicated. The terminal builds the
11
+ same text with `requiredSkillsText` and appends it as a hidden `xingular-required-skills` message,
12
+ so the person's own wording reaches the model unchanged. In the composer the `$` palette opens at
13
+ the caret and inserts there, keeping the rest of the draft.
14
+ - Bound delegation per run and per profile (ADR-0052). A run now starts at most four distinct child
15
+ conversations: two `worker`, three `explorer`, one of any other named profile and one with no
16
+ profile. `SessionRunInput.subagents` / the SDK's `Subagents` options override them with
17
+ `maxChildren`, `maxByProfile`, `maxOther` and `maxUnprofiled` (clamped to 0–50), and the model's
18
+ `spawn_subagent` description states the budget it has left. `Subagents.spawn` refuses a child past
19
+ a limit with `invalid_request` and starts no run; continuing a stopped child costs no slot, and a
20
+ work-slice continuation keeps the parent's budget.
21
+ - Read what a request was made of. `context.attribution` returns one row per contributor with its
22
+ estimated tokens and share of the window, reconciled to the provider's measured total, and one
23
+ row's text on request; the terminal reaches it through `terminal.context`. The compiler now
24
+ records where its characters went: `renderSized` returns each section's size and the framing that
25
+ belongs to no section, `Delivery.sizes` stores them on the recorded pack, and `Source.chars`
26
+ attributes a variant's tool guidance inside the tools section. `context.snapshot` also records the
27
+ compaction headroom the run was held to (`compaction: { enabled, reserveTokens }`) from Pi's own
28
+ settings. The terminal page over this data arrives in a later preview; no `/context` command is
29
+ registered yet.
30
+ - Add an opt-in approved-window screenshot contract (ADR-0050). `src/computer/screenshot.ts` defines
31
+ `computer_screenshot` for a host-supplied backend: it captures exactly one currently approved
32
+ window, excludes the desktop, other windows and overlapping overlays, and refuses with
33
+ `COMPUTER_SCREENSHOT_UNAVAILABLE` rather than returning display pixels. It goes through the
34
+ ordinary tool gate, is not plan-mode safe, and adds no extension point. The standalone terminal
35
+ has no backend, and the existing macOS host capture has not adopted this contract.
36
+ - Deliver approvals and questions promptly without polling: the control-key-protected
37
+ `terminal.pending.wait` returns as soon as the pending revision changes and otherwise waits at most
38
+ 20 s, waking on additions, removals and disposal (ADR-0051). `terminal.pending` is unchanged and
39
+ the server protocol is untouched.
40
+ - Swap the OpenTUI send keys back. `Return` sends, or queues a follow-up behind a running reply, and
41
+ `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers that reply. The `app.message.followUp` action is
42
+ `app.message.steer` again, so a `keybindings.json` entry under the newer name needs renaming.
43
+ - Keep a stray mouse report out of input. A report split across the input parser's timeout no longer
44
+ types its `<button;column;row>` tail into the composer or a single-line field, so a scroll cannot
45
+ become a run's prompt or a filter; typing and pastes are untouched and `/trajectory` no longer
46
+ prints a recorded report.
47
+
48
+ ## Upgrading
49
+
50
+ - A leading `$name` is no longer rewritten to Pi's `/skill:name`. An embedding host sends required
51
+ skills as `Launch.requiredSkills`, and the message text reaches the model as written.
52
+ - Runs that spawned children freely now stop at the defaults above; set `subagents` explicitly to
53
+ change them.
54
+ - A `keybindings.json` entry named `app.message.followUp` is now `app.message.steer`.
@@ -0,0 +1,56 @@
1
+ # Xingular Harness 1.3.1-unstable.4
2
+
3
+ Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
4
+
5
+ - Continue a terminal session from a phone or iPad with `/remote-control` (alias `/rc`), without a
6
+ cloud relay (ADR-0056, [page 15](../architecture/15-remote-control.md)). The harness serves a small
7
+ phone page on the computer's Tailscale address, or its private Wi-Fi address, and the terminal
8
+ shows a half-block QR code for a one-device pairing link. A paired phone sends messages, watches
9
+ the reply stream, stops it, and answers approvals and questions through the same `Terminals` and
10
+ controller methods the terminal uses. Bodies are sealed with NaCl `secretbox` and a replayed
11
+ counter is refused; device keys live in memory only, and remote control ends with the session.
12
+ `xagent --remote-control` (`--rc`) turns it on at start, `/rc off` stops it, and the status bar
13
+ reads `rc` while it is on and `rc ●` while a device is connected. Terminal runs now also record
14
+ streamed `message.delta` events. New dependencies: `tweetnacl`, `uqr`.
15
+ - Classify a plan reply instead of guessing at it, and repair one bad reply. An attended top-level
16
+ plan run has one shared outcome: `plan_ready` for a complete `<proposed_plan>`, `blocked` when a
17
+ required decision cannot be obtained, and `invalid` for missing, incomplete, conflicting or
18
+ malformed blocks; only `plan_ready` offers a plan card and Implement (ADR-0055, ADR-0057,
19
+ ADR-0058). An `invalid` reply gets one hidden format-repair turn in the same run, and a failed
20
+ repair leaves the run completed with a warning instead of a plan choice. Clarification now goes
21
+ through the blocking `ask_user` tool, so new final replies no longer use `<plan_clarification>` or
22
+ free-text questions. Both the server and the terminal use the same classification rather than
23
+ separate heuristics. The App's plan card has not adopted the classification yet.
24
+ - Report a live reply's heartbeat every 30 seconds, and end a reply that produces nothing but
25
+ heartbeats for 15 minutes as `interrupted` with reason `stalled`, instead of showing a run that
26
+ never settles (ADR-0054). A running tool gets 30 minutes, and an unanswered approval or question is
27
+ never cut short. Before this, a terminal reply reported no heartbeat at all, so the run sweep
28
+ waited the full 30-minute silence window and recorded `owner_gone` while the process was alive.
29
+ - Stop refusing repeated work (ADR-0053). A reply is no longer refused or ended for calling the same
30
+ tool with the same arguments three times, for a Bash check that keeps failing, or for editing one
31
+ path more than four times: those calls are ordinary work and the reply budget is the single bound.
32
+ The 320-call/60-minute budget, its checkpoint handoff, slice continuation and the
33
+ three-compaction thrash rule are unchanged, and the `stuck` checkpoint reason stays readable in
34
+ existing runs.
35
+ - Answer what the latest request was made of with `/context`. The page has a Request tab (one row per
36
+ contributor with its estimated tokens and share of the window, four-colour ownership bar with a
37
+ free track and a compaction marker) and a Growth tab (how the window filled over the session).
38
+ `space` folds a group, `enter` shows one row's text, `g` switches grouping between owner and kind,
39
+ and `c` asks the session to compact. `terminal.context` serves it from `context.attribution`; the
40
+ status band reads the same share, such as `18.3%/1M`.
41
+ - Render the `/btw` side answer as Markdown instead of plain text. Headings, emphasis, lists, quotes,
42
+ links, tables and fenced code use the theme's markdown colours, a streaming answer re-renders in
43
+ place, and terminal control sequences in model output are still removed.
44
+
45
+ ## Upgrading
46
+
47
+ - Two new runtime dependencies arrive with remote control: `tweetnacl` and `uqr`.
48
+ - A plan reply that ends in `<plan_clarification>` or a free-text question is now `invalid` and gets
49
+ the single repair turn; use `ask_user` for a decision the run needs before it can plan.
50
+ - The `stuck` checkpoint reason is no longer produced, but it stays readable in existing run records.
51
+
52
+ ## Publication note
53
+
54
+ This preview was published with the test job removed and without waiting for the smoke job, by
55
+ request. The `check` job and the smoke gate are restored in the next commit; the candidate pack,
56
+ integrity check, preflight, provenance and registry verification in the publish job still ran.
@@ -29,10 +29,11 @@ overrides the Bun executable.
29
29
  [`app.ts`](../src/terminal/opentui/app.ts) owns the terminal lifecycle and reuses the shared
30
30
  `TerminalRuntime`, session replacement, commands, decisions, account pinning and run records. It
31
31
  projects the runtime's snapshot and transcript into an OpenCode-inspired view, with a native
32
- OpenTUI textarea for the prompt and `Ctrl+K` for the command palette. `Return` sends or steers a
33
- running reply; `Cmd+Return`, `Ctrl+Return` or `Alt+Return` queues a follow-up, and `Shift+Return`
34
- inserts a newline. Typing `/` or `$` filters
35
- matching commands or skills; `Tab` inserts the selected entry and leaves the cursor at the end of the inserted text.
32
+ OpenTUI textarea for the prompt and `Ctrl+K` for the command palette. `Return` sends or queues a
33
+ follow-up; `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers a running reply, and `Shift+Return`
34
+ inserts a newline. Typing `/` at the start of the draft filters matching commands, and typing `$` at any word start
35
+ filters matching skills; `Tab` inserts the selected entry and leaves the cursor after it. A `$`
36
+ entry replaces only the token being typed, so text before and after it stays in place.
36
37
  With an empty composer, unmodified Up recalls the latest non-empty user message from the active session.
37
38
  With a draft, unmodified Up browses older history and Down browses newer history when the caret is at
38
39
  either absolute draft endpoint (start or end). Down past the newest entry restores the draft, cursor
@@ -95,7 +96,7 @@ The frontend is verified with a real isolated PTY and a loopback provider. Run
95
96
  `python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
96
97
  welcome, product label, accent colors and `/help` transition. Run
97
98
  `python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
98
- and a user bubble, enabled-skill colors in the composer, unknown-token and argument colors,
99
+ and a user bubble, enabled-skill colors in the composer (leading and after text), unknown-token and argument colors,
99
100
  explicit-newline and soft-wrap checks of both prompt gutters, and normal/plan/Bash mode exclusivity.
100
101
  Run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
101
102
  input dialog, `--file-completion-only` for filesystem completion and insertion,
@@ -246,8 +247,9 @@ end. A narrow `▕` thumb marks transcript position at the right edge; its mouse
246
247
  thinking, tools, image results, notices, summaries, custom messages, user messages, plan cards and
247
248
  Bash entries. User, plan and Bash bubbles also have one blank row of internal padding above and below
248
249
  their content; other entries have no internal vertical padding. Bubble padding is additional to the
249
- inter-entry gap. Internal lines within an entry stay together. The transcript stays pinned to the
250
- latest message until you scroll away. While scrolled away, a `↓ Jump to latest` badge overlays the
250
+ inter-entry gap. A plan card carries its title as an underlined header in the plan blue, then one
251
+ blank row before the plan body. Internal lines within an entry stay together. The transcript stays
252
+ pinned to the latest message until you scroll away. While scrolled away, a `↓ Jump to latest` badge overlays the
251
253
  transcript's lower-right corner; clicking it returns to the newest message and hides the badge.
252
254
  `Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty
253
255
  welcome area focuses the composer. Dragging to select text anywhere in the TUI—including the
@@ -263,6 +265,12 @@ question's action is clicked. Dialogs preserve their existing confirmation safeg
263
265
  hover; terminals or multiplexers that do not report motion retain keyboard navigation. ANSI-only
264
266
  custom UI without a mouse handler remains keyboard-driven.
265
267
 
268
+ A mouse report the terminal delivers in two pieces across the input parser's timeout arrives as
269
+ printable keys. The composer and every single-line field drop the report's `<button;column;row>`
270
+ tail instead of keeping it, so a stray scroll never becomes a draft, a filter or a prompt; text typed
271
+ at human speed is untouched even when it spells the same shape. Recorded text never prints a
272
+ reported sequence on a page, and a bare tail that was recorded stays visible as recorded evidence.
273
+
266
274
  Page dialogs and blocks are absolute overlays, so the transcript stays behind them. The screen
267
275
  restores the terminal's alternate-screen state when the application exits.
268
276
 
@@ -316,6 +324,14 @@ of two rule-based shapes, using the 2-cell composer gutter on each side and a di
316
324
  `/plugins` and `/hub` menus are pages. Section labels inside a page are plain bold headings, never
317
325
  text set into a rule. `/trajectory` is a full-screen page with searchable Runs and Events
318
326
  tabs; its Events view keeps the event list beside the selected event's JSON on wide terminals.
327
+ `/context` is a full-screen page with Request and Growth tabs: one bar that gives each kind of
328
+ context its own colour — foundation blue, variant orange, your application green, conversation
329
+ amber, the same four values as the App's `--data-1..4` tokens — with the track for free space and a
330
+ `│` where Pi would start compacting, a legend naming every run, then one row per contributor (`❯` on the selected one, `·` for a section that arrives per request) reading
331
+ `tokens` and `share`, group headings carrying their own total, the reserve and free space, and an
332
+ On demand list. `space` folds a group, `enter` shows the text a row contributed, `g` regroups rows
333
+ by owner or by kind, `c` compacts after a confirmation, and `v` opens `/harness`. It reads
334
+ `terminal.context` and draws no figure it did not receive.
319
335
 
320
336
  `DialogPanel` takes a `variant` (`block` by default). `ui.select` accepts a harness-owned `page`
321
337
  option, which Pi's own dialogs ignore, so the same extension code runs in either terminal. Selected
@@ -377,10 +393,9 @@ snapshot and compares their text with the latest saved version. No in-place edit
377
393
  is added. Library skills and rules are added through `terminal.components.add`, which commits a
378
394
  validated future version. Directory-backed variants stay read-only.
379
395
 
380
- Skill browsing is independent of the Skill commands setting. Use inserts a leading `$name`
381
- without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
396
+ Skill browsing is independent of the Skill commands setting. Use inserts `$name` without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
382
397
  the existing draft text and attachment labels. Canceling the filter restores that draft. OpenTUI completes
383
- loaded skills for a leading `$`; Enter or Tab inserts the selected skill rather than sending.
398
+ loaded skills for a `$` at any word start; Enter or Tab inserts the selected skill rather than sending.
384
399
  Plugin contributions, settings, attachment and code trust share one detail flow. Package install
385
400
  and removal delegate to existing services; installing never trusts or activates code.
386
401
 
@@ -466,7 +481,8 @@ request-scoped prompt section, which the next ordinary request withdraws.
466
481
  Each mode keeps its own model and effort for the account. Every selection the person makes (the model
467
482
  picker, `/effort`, Shift+Up/Down, Ctrl+P) is saved against the mode it was made in, so Shift+Tab switches to that
468
483
  mode's model and effort, and a new conversation starts on the normal mode's latest choice. A mode with no
469
- choice of its own takes normal's, field by field. A resumed conversation keeps the model in its history,
484
+ choice of its own takes normal's, field by field; when neither has a saved effort, the mode uses Pi's
485
+ default level rather than keeping the level chosen in the other mode. A resumed conversation keeps the model in its history,
470
486
  and a saved model the account cannot use is skipped. The choices live in the account's `choices.json`,
471
487
  and the App reads and writes them through `accounts.choices` and `accounts.choose`.
472
488
 
@@ -485,7 +501,9 @@ dismisses it; the block yields to the composer as soon as the draft has text.
485
501
  Implement leaves plan mode, so the normal tools and the mode's own model and effort come back, and sends
486
502
  `Implement the plan: <title>`; the plan itself is already in the conversation. Edit the plan stays in plan
487
503
  mode and focuses the composer, so the next message revises the plan and offers a new choice. A plan run
488
- that was interrupted, failed, or had work queued behind it is not offered.
504
+ that was interrupted, failed, or had work queued behind it is not offered. If a completed plan run still
505
+ has no complete block after the harness's one repair attempt, the terminal shows a warning notice instead
506
+ of a plan choice; the plan request can be sent again.
489
507
 
490
508
  A recognized leading slash command uses the selected theme's link color while typing and in its
491
509
  user-message bubble. Only the command token is accented; arguments and unknown slash tokens keep the
@@ -652,12 +670,14 @@ second key once with `control.claim`, before plugin code loads. [`control.ts`](.
652
670
  retains it in a process-local promise shared with the bridge; it is never written to disk or
653
671
  placed in the environment. It survives `/new`, resume, fork and reload.
654
672
 
655
- The private key is required for `terminal.policy`, `terminal.approval`, `terminal.pending`,
673
+ The private key is required for `terminal.policy`, `terminal.approval`, `terminal.pending`, `terminal.pending.wait`,
656
674
  `terminal.approve`, `terminal.answer`, `terminal.draft`, `terminal.interrupt` and
657
675
  `terminal.resources`, as well as existing account and plugin mutations. A model-spawned shell with
658
676
  only the environment token cannot submit policy or approval decisions, change permissions, or
659
677
  answer its own pending questions. The application renders decisions obtained from the existing
660
678
  controller and returns the person's answer through these calls.
679
+ The frontend waits on revisioned decision snapshots instead of polling continuously; a bounded wait
680
+ and reconnect resynchronize the inbox after a lost connection.
661
681
 
662
682
  Approval prompts offer **Allow once**, **Always allow this tool everywhere** when the host policy
663
683
  marks the decision rememberable, and **Deny**. A tool grant covers every call with that tool name
@@ -768,9 +788,12 @@ file size separated by ` · `. One blank line separates each session. Enter resu
768
788
  session; account and folder scope checks
769
789
  remain enforced. Supplying an explicit path continues directly without opening the picker.
770
790
  The `$` palette completes enabled skill invocations using the same two-column palette as slash
771
- commands; `/skills` always browses skills. Choosing a skill inserts `$name ` without submitting.
772
- A recognized leading `$name` uses the blue accent in the composer, while its arguments, unavailable
773
- names and ordinary currency text keep the normal color. `/help` renders the command list as one
791
+ commands, at any word start in the draft; `/skills` always browses skills. Choosing a skill inserts
792
+ `$name` at the caret without submitting. Every recognized `$name` that names a loaded skill uses the
793
+ blue accent in the composer, while its arguments, unavailable names and ordinary currency text keep
794
+ the normal color. Sending a message that contains `$name` makes that skill required for the request:
795
+ the terminal appends its text and the requirement as a hidden request-scoped message, and the
796
+ person's wording is sent unchanged. `/help` renders the command list as one
774
797
  transcript entry, grouped under Core, Run, Model, Session, Inspect, Harness, Plugins and Prompts;
775
798
  command names and descriptions wrap in aligned columns, with no blank rows between choices. `/plugins`
776
799
  opens the focused local manager; its Packages tab installs, updates and removes packages with protected
@@ -781,8 +804,10 @@ terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/shar
781
804
  `/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
782
805
  main run's effective instructions, visible conversation and redacted public tool inputs/results.
783
806
  Hidden reasoning and image bytes are excluded; the side run has no tools. Its block puts the
784
- question after `/btw`, shows the normal animated spinner while answering, and separates the answer
785
- and hint by one blank row; it has no status labels. PageUp/PageDown browse a long answer and Ctrl+X
807
+ question after `/btw`, shows the normal animated spinner while answering, renders the answer as
808
+ Markdown, and separates the answer and hint by one blank row; it has no status labels. Headings,
809
+ emphasis, lists, quotes, links, tables and fenced code keep the theme's markdown colours, and a
810
+ streaming answer re-renders as it grows. PageUp/PageDown browse a long answer and Ctrl+X
786
811
  copies the full answer. Escape or either command with no question dismisses the dock and interrupts
787
812
  only that side run; the main reply continues. `/stop` interrupts the current main reply. The `/accounts` page handles sign-in
788
813
  and sign-out. `/components` browses reusable skills, prompts and rules; a confirmed skill or rule addition
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xingular/harness",
3
- "version": "1.3.1-unstable.2",
3
+ "version": "1.3.1-unstable.4",
4
4
  "type": "module",
5
5
  "description": "Xingular Harness — a Pi agent harness built on recursive harnessing (Harness²): versioned eight-component variants, refinement from evidence, multi-account sessions, a compiled prompt, project notes, tools, and MCP",
6
6
  "repository": {
@@ -54,7 +54,9 @@
54
54
  "solid-js": "^1.9.12",
55
55
  "turndown": "^7.2.4",
56
56
  "turndown-plugin-gfm": "^1.0.2",
57
+ "tweetnacl": "1.0.3",
57
58
  "typebox": "^1.3.7",
59
+ "uqr": "0.1.3",
58
60
  "yaml": "^2.8.1",
59
61
  "zod": "^4.1.11"
60
62
  },