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

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 (116) hide show
  1. package/CHANGELOG.md +29 -1
  2. package/README.md +16 -12
  3. package/builtin/skills/plugin-authoring/SKILL.md +34 -0
  4. package/dist/cli.js +2334 -1715
  5. package/dist/sdk/agents/profiles.d.ts +13 -4
  6. package/dist/sdk/agents/profiles.js +59 -7
  7. package/dist/sdk/annotations/bridge.d.ts +2 -0
  8. package/dist/sdk/annotations/bridge.js +4 -0
  9. package/dist/sdk/annotations/capture.d.ts +44 -2
  10. package/dist/sdk/annotations/capture.js +104 -3
  11. package/dist/sdk/annotations/delivery.d.ts +24 -17
  12. package/dist/sdk/annotations/delivery.js +82 -49
  13. package/dist/sdk/annotations/inspect.js +7 -6
  14. package/dist/sdk/annotations/pageScript.js +4 -4
  15. package/dist/sdk/annotations/part.d.ts +0 -2
  16. package/dist/sdk/annotations/part.js +4 -33
  17. package/dist/sdk/annotations/queue.d.ts +2 -2
  18. package/dist/sdk/annotations/queue.js +12 -7
  19. package/dist/sdk/annotations/serverMethods.js +11 -7
  20. package/dist/sdk/annotations/store.d.ts +13 -21
  21. package/dist/sdk/annotations/store.js +47 -37
  22. package/dist/sdk/commands/list.js +2 -0
  23. package/dist/sdk/core/links.d.ts +51 -0
  24. package/dist/sdk/core/links.js +155 -0
  25. package/dist/sdk/harness.d.ts +5 -0
  26. package/dist/sdk/harness.js +11 -6
  27. package/dist/sdk/index.d.ts +1 -0
  28. package/dist/sdk/index.js +1 -0
  29. package/dist/sdk/plugins/builtin.js +11 -6
  30. package/dist/sdk/plugins/builtinRegistry.d.ts +3 -1
  31. package/dist/sdk/plugins/builtinRegistry.js +9 -3
  32. package/dist/sdk/plugins/discover.d.ts +7 -1
  33. package/dist/sdk/plugins/discover.js +41 -2
  34. package/dist/sdk/plugins/identity.js +1 -1
  35. package/dist/sdk/plugins/inventory.js +1 -1
  36. package/dist/sdk/plugins/manifest.d.ts +2 -0
  37. package/dist/sdk/plugins/manifest.js +21 -4
  38. package/dist/sdk/plugins/plugins.d.ts +2 -0
  39. package/dist/sdk/plugins/plugins.js +1 -0
  40. package/dist/sdk/plugins/proposals.d.ts +17 -0
  41. package/dist/sdk/plugins/proposals.js +147 -0
  42. package/dist/sdk/plugins/types.d.ts +1 -1
  43. package/dist/sdk/plugins/types.js +1 -1
  44. package/dist/sdk/prompt/compile.d.ts +11 -2
  45. package/dist/sdk/prompt/compile.js +32 -4
  46. package/dist/sdk/prompt/standard.d.ts +1 -1
  47. package/dist/sdk/prompt/standard.js +1 -1
  48. package/dist/sdk/server/methods.js +10 -0
  49. package/dist/sdk/sessions/sessionState.d.ts +13 -0
  50. package/dist/sdk/sessions/sessionState.js +31 -0
  51. package/dist/sdk/sessions/sessions.d.ts +7 -0
  52. package/dist/sdk/sessions/sessions.js +45 -5
  53. package/dist/sdk/sessions/subagentService.js +3 -3
  54. package/dist/sdk/terminal/opentui/theme.d.ts +2 -0
  55. package/dist/sdk/terminal/opentui/theme.js +1 -0
  56. package/dist/sdk/terminal/piExtension.js +71 -2
  57. package/dist/sdk/terminal/terminals.d.ts +9 -0
  58. package/dist/sdk/terminal/terminals.js +46 -14
  59. package/dist/sdk/terminal/tui/annotateCommand.d.ts +5 -1
  60. package/dist/sdk/terminal/tui/annotateCommand.js +21 -7
  61. package/dist/sdk/terminal/tui/annotateSend.d.ts +30 -0
  62. package/dist/sdk/terminal/tui/annotateSend.js +40 -0
  63. package/dist/sdk/terminal/tui/commandPages.d.ts +1 -1
  64. package/dist/sdk/terminal/tui/commandPages.js +2 -7
  65. package/dist/sdk/terminal/tui/commands.js +4 -2
  66. package/dist/sdk/terminal/tui/dialogs.js +1 -0
  67. package/dist/sdk/terminal/tui/keybindings.d.ts +1 -1
  68. package/dist/sdk/terminal/tui/keybindings.js +1 -1
  69. package/dist/sdk/terminal/tui/pageOverlay.d.ts +3 -0
  70. package/dist/sdk/terminal/tui/pageOverlay.js +12 -1
  71. package/dist/sdk/terminal/tui/pages/agentsPage.js +5 -2
  72. package/dist/sdk/terminal/tui/pages/annotatePage.d.ts +70 -16
  73. package/dist/sdk/terminal/tui/pages/annotatePage.js +349 -115
  74. package/dist/sdk/terminal/tui/pages/pluginsPage.d.ts +6 -0
  75. package/dist/sdk/terminal/tui/pages/pluginsPage.js +99 -1
  76. package/dist/sdk/terminal/tui/pages/usagePage.d.ts +4 -2
  77. package/dist/sdk/terminal/tui/pages/usagePage.js +39 -12
  78. package/dist/sdk/terminal/tui/pluginCommands.d.ts +1 -1
  79. package/dist/sdk/terminal/tui/pluginCommands.js +13 -3
  80. package/dist/sdk/tools/defaultSkills.d.ts +4 -0
  81. package/dist/sdk/tools/defaultSkills.js +20 -0
  82. package/dist/sdk/tools/definitions.d.ts +3 -1
  83. package/dist/sdk/tools/definitions.js +17 -1
  84. package/dist/sdk/tools/dispatch.js +12 -0
  85. package/dist/sdk/tools/harnessTools.js +1 -1
  86. package/dist/sdk/tools/sessionName.d.ts +7 -0
  87. package/dist/sdk/tools/sessionName.js +53 -8
  88. package/dist/sdk/world/world.d.ts +0 -2
  89. package/dist/terminal-opentui.js +2019 -1269
  90. package/dist/terminal-pi.js +106 -7
  91. package/docs/README.md +3 -0
  92. package/docs/architecture/02-sessions-and-runs.md +11 -5
  93. package/docs/architecture/03-variants.md +1 -3
  94. package/docs/architecture/04-prompt.md +16 -7
  95. package/docs/architecture/06-plugins-and-capabilities.md +36 -4
  96. package/docs/architecture/07-tools-and-gate.md +20 -5
  97. package/docs/architecture/10-server-protocol.md +52 -7
  98. package/docs/architecture/11-terminal.md +50 -19
  99. package/docs/architecture/12-storage.md +1 -0
  100. package/docs/architecture/13-world-tools.md +8 -6
  101. package/docs/architecture/README.md +3 -1
  102. package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md +6 -2
  103. package/docs/architecture/proposals/PROP-0048-simple-annotate.md +85 -0
  104. package/docs/architecture/proposals/README.md +1 -0
  105. package/docs/decisions/ADR-0044-annotations-pending-or-sent.md +24 -0
  106. package/docs/decisions/ADR-0045-default-plugin-authoring-skill.md +9 -0
  107. package/docs/decisions/ADR-0046-hash-bound-plugin-proposals.md +20 -0
  108. package/docs/decisions/ADR-0047-links-open-with-the-os-handler.md +47 -0
  109. package/docs/parity.md +7 -4
  110. package/docs/releases/1.3.1-unstable.1.md +8 -0
  111. package/docs/releases/1.3.1-unstable.2.md +11 -0
  112. package/docs/releases/README.md +7 -4
  113. package/docs/terminal-tui.md +62 -23
  114. package/package.json +1 -1
  115. package/dist/sdk/terminal/tui/pages/notesPage.d.ts +0 -75
  116. package/dist/sdk/terminal/tui/pages/notesPage.js +0 -201
@@ -48,7 +48,14 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
48
48
  shared tool alongside its read-only set and restores the normal set on success, failure or
49
49
  interruption. There is no terminal-only question alias (PROP-0040).
50
50
  - A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
51
- (PROP-0043). A user `!` command is refused while a plan request runs.
51
+ (PROP-0043). A user `!` command submitted during a plan request waits as a separate turn; it
52
+ cannot run inside the plan's read-only request.
53
+ - The terminal message-delivery contract is Enter to send or steer an active reply, and
54
+ Cmd/Ctrl/Alt+Enter to queue a follow-up. Pending steering, follow-up and deferred plan/Bash
55
+ inputs are projected above the working line from Pi's queues and the deferred barrier. Pi's
56
+ projection may briefly include an item already taken for delivery. A queued plan or Bash command
57
+ runs separately after the active reply, and later inputs cannot bypass it through Pi's native
58
+ queues. Modified shortcuts require terminal support.
52
59
  - Current standalone source defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
53
60
  `~/.xingular-harness-dev/{data,state}`. The standalone development launch uses a file SecretStore
54
61
  under its resolved development state directory, even when its profile names a host backend; it
@@ -77,14 +84,18 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
77
84
  leaves the main conversation untouched. The dock streams, scrolls and copies the complete answer.
78
85
  Aliases remain callable and searchable, but help and palette show only the canonical
79
86
  entry. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
80
- opens its Limits tab (PROP-0042); both are plugin-owned namespaced routes. The usage page is a
81
- centered dialog: each window is a label and reset line above a quota-left bar coloured green at
87
+ opens its Limits tab (PROP-0042); `/usage:accounts` opens the All accounts limits tab. These are plugin-owned namespaced routes. All-account refresh reads due providers using their own account credentials without switching the session account. The usage page is a
88
+ full-screen page with a top tab strip: each window is a label and reset line above a quota-left bar coloured green at
82
89
  50% or more left, amber from 20–49%, and red below 20%. `commands.list`
83
90
  publishes the effective routes; the browser-safe core catalogue is `commands/registry.ts`. First-class Harness commands are unprefixed and live in that registry,
84
91
  independently of plugin command metadata. Every plugin-owned command uses
85
92
  `/<owner-prefix>:<command>`; the namespace root is offered only by plugins that declare a default
86
93
  command. Prompt templates and `/skill:<name>` keep their existing forms.
87
94
 
95
+ The `/plugins` Proposals tab previews the complete stored files and generated manifest before
96
+ confirmation. Accept and reject pass the preview hash through the control-key-protected socket;
97
+ the proposal service checks it again. Acceptance leaves the package switched off and untrusted.
98
+
88
99
  ## Invariants
89
100
 
90
101
  - **INV-TUI-1** OpenTUI is the only terminal frontend. Pi's `InteractiveMode` is never constructed
@@ -96,7 +107,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
96
107
  their existing layers. The terminal adds no second path for any of them; its runs are written
97
108
  through the controller and the run store.
98
109
  - **INV-TUI-4** Changes made through the session socket (`plugins.attach|detach|trust|untrust|configure`,
99
- `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
110
+ `plugins.proposals.*`, `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
100
111
  `terminal.annotations.*`, `terminal.sideQuestions.*`) require the control key the trusted terminal process claimed once
101
112
  (`control.claim`). The session's shell can read the session token, so the token alone is never
102
113
  enough.
@@ -144,6 +155,13 @@ The native `session_info_changed` event invalidates the frontend's cached snapsh
144
155
  refreshes the working line. Both the active and retained completion line append
145
156
  ` – <name>` after duration and token rate, for example
146
157
  `Working (2m, 50 tok/s) – Add web browser integrations`. Unnamed sessions omit the suffix.
158
+ A substantive first turn also receives a provisional name through the terminal policy; a refused
159
+ or failed name leaves the session unnamed.
160
+
161
+ Each user turn appends a hidden `xingular-session-state` custom message with the current name,
162
+ this run's empty todo, and the previous run's todo as context. The message is request-only and
163
+ never changes the compiled stable pack. A first turn is marked as such; later turns say the todo
164
+ list resets for each run.
147
165
  Names use the existing terminal text sanitization, remain outside the verb shimmer, and
148
166
  truncate at the right edge. Manual `/name` and existing long names remain supported.
149
167
 
@@ -176,7 +194,7 @@ The browser uses the full terminal with persistent section tabs (PROP-0014); wid
176
194
  inventory beside details, actions and content, while compact screens keep inline details under
177
195
  the same tabs. The separate `/plugins` and `/hub` pages also use full-screen layouts with persistent
178
196
  section tabs, responsive inventory/details panes and their existing protected operations. Other
179
- command pages remain centered except `/settings`, `/accounts`, `/plugins` and `/hub`, which use
197
+ command pages remain centered except `/settings`, `/accounts`, `/plugins`, `/hub` and `/usage:`, which use
180
198
  full-screen page layouts.
181
199
  Accounts keeps Accounts/Pools tabs, search and account-service operations.
182
200
  Wide terminals show selected-account details beside the list; Enter or a primary click opens grouped
@@ -253,24 +271,37 @@ contract is unchanged. See [PROP-0025](proposals/PROP-0025-contextual-question-w
253
271
  PTY verification is retained in `docs/evidence/terminal-wireframe-normalization/`; it establishes
254
272
  cell topology for bounded fixtures, not every emulator/font or live-model sketch quality.
255
273
 
256
- ## Web annotations commands (PROP-0017)
274
+ ## Web annotations commands (PROP-0017, PROP-0018, PROP-0048)
257
275
 
258
- `/annotate:notes` lists the Web annotations kept in the data root, with search, and offers reveal, edit, resolve or
259
- reopen, share with this session or stop sharing, and delete. `/annotate:` opens the default capture pane;
260
- `/annotate:annotate [url]` is its explicit command form. It opens a visible capture browser (its own window and profile, separate from the agent's browser), where the person can annotate the whole page,
261
- select text, or click an element there. An annotation is private until shared; this session's agent then reads it with `page_notes_list`
262
- and `page_notes_read`.
276
+ `/annotate:` opens the annotate page, a full-screen page with two tabs. `/annotate:notes` opens it on
277
+ **All annotations**: every annotation in the data root, with search, and reveal, edit, resolve or
278
+ reopen, share with this session or stop sharing, and delete. An annotation is private until shared;
279
+ this session's agent then reads it with `page_notes_list` and `page_notes_read`.
263
280
 
264
- The annotate pane (PROP-0018) is a full-screen page beside the window being inspected.
281
+ The **Annotate** tab is the panel beside the window being inspected.
265
282
 
266
283
  - **Ways to start it:**
267
- - `/annotate:` or `/annotate:annotate [url]`: the capture browser
268
- - `/annotate:annotate --app <DevTools address | port> [name]`: an app's own windows over its DevTools port
269
- - `/annotate:annotate --bridge [name]`: app windows that load the page bridge script, which the pane shows
270
- - **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in the page with Create annotation, Ask agent to fix, and Proceed now.
271
- - **Sections:** Queue, Sent and fixed (with the agent's summary), and Saved.
272
- - **Other keys:** `s` sends the queue as one run of this session, confirming notes that came from a page-world script first; `x` takes a note out of the queue; `t` picks a window.
273
- - **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|queue|dequeue|confirm|send` act only on this terminal's session and need the control key.
284
+ - `/annotate: [url]`: the capture browser (its own window and profile, separate from the agent's
285
+ browser). With no address, the page returns to the window that is still open, with its URL and
286
+ the inspector on, and asks for one in its own inline field only when no window is open.
287
+ - `/annotate: --app [port | address] [name]`: an app's own windows over its DevTools port. With no
288
+ port, the page lists the apps answering on one (`annotations.capture.discover`).
289
+ - `/annotate: --bridge [name]`: app windows that load the page bridge script, which the page shows.
290
+ - **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in
291
+ the page with **Annotate** and **Annotate & send**. Every annotation is shared with this session
292
+ at once.
293
+ - **Groups:** Unsent (n) and Sent, for this session.
294
+ - **Other keys:** `s` sends every unsent annotation as one run of this session, confirming the
295
+ page-origin ones once first; `o` types a page address; `a` lists apps with a DevTools port, with
296
+ *Start an app with a DevTools port*, *Type a DevTools port*, *Use the page bridge*; `t` picks a
297
+ window; `Tab` switches tab. A key pressed while the page is busy gets a notice, never nothing.
298
+ - **Commands:** `/annotate:submit <request>` sends the unsent annotations with the request after
299
+ them; `/annotate:clear` resolves the unsent ones and stops sharing them.
300
+ - **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|confirm|confirmAll|send|clear|discover|launch`
301
+ act only on this terminal's session and need the control key.
302
+
303
+ A page that opens a dialog as it starts gets it above itself: `PageOverlay` starts its page when the
304
+ host reports the overlay mounted.
274
305
 
275
306
  ## Todo list (PROP-0006, PROP-0045, PAR-001)
276
307
 
@@ -23,6 +23,7 @@ index.
23
23
  legacy/ an earlier Wiki's data, moved once (08)
24
24
  registry/ skills/, prompts/, rules/: the component library (03)
25
25
  plugins/<name>/ packages kept with the data (06)
26
+ plugin-proposals/<id>.json pending and decided proposal text, hash and status; owned by plugins/proposals.ts (06)
26
27
  trash/plugins/ removed packages (06)
27
28
  hub/ installed documents and provenance (09)
28
29
  runs/<id>/ run.json (including optional legacy-compatible workspaceRoot), events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json (02)
@@ -48,19 +48,21 @@ it. A tool returns only notes a person shared with the calling session or agent;
48
48
  and element names are marked untrusted. Capture happens in a visible capture browser in the
49
49
  terminal, or in a host's own web view running the same page helper (`annotations.pageScript`).
50
50
 
51
- **Inspector, queue and app targets (PROP-0018).**
51
+ **Inspector, sending and app targets (PROP-0018, PROP-0048).**
52
52
 
53
- - **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with three choices: save, queue for the agent, or send now.
54
- - A queued note is shared with its session.
55
- - `annotations/delivery.ts` sends a batch as one instruction, and sends notes the person asked for while the session was busy when its run ends.
56
- - The agent reports a fix with `page_notes_mark_fixed`, the only page-note tool that writes. It never resolves a note or changes grants.
53
+ - **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with two choices: Annotate and Annotate & send.
54
+ - With a session, every note is shared with it at once and is pending (unsent) until sent.
55
+ - `annotations/delivery.ts` sends all of a session's pending notes as one message, with the
56
+ person's request last when given, and sends notes held back while the session was busy when its
57
+ run ends, trying again while the session still answers busy.
58
+ - The page-note tools are read-only. Only the person resolves a note.
57
59
  - **Targets.** Element targets prefer semantic role/name/text. A visually empty element may still be
58
60
  annotated when it has a specific CSS selector (ID, test ID, classes, and a structural path when
59
61
  needed); bare tag selectors are not enough. Reveal checks for one live match and preserves any
60
62
  captured semantic/context evidence, otherwise reporting ambiguous or unresolved. Text annotations
61
63
  continue to use quote plus context, not screen coordinates.
62
64
  - Besides the browser window, capture can use an app's own windows:
63
- - **DevTools port:** an app started with a DevTools port, on a loopback address only. It uses the app's existing windows, routes nothing, and never closes the app.
65
+ - **DevTools port:** an app started with a DevTools port, on a loopback address only. It uses the app's existing windows, routes nothing, and never closes the app. `discover` probes loopback ports 9222–9230 and ports used before (a Node inspector is skipped); `launchApp` starts a program (the one inside a macOS `.app`) with `--remote-debugging-port` on a free loopback port and attaches. A started app keeps running.
64
66
  - **Page bridge:** a loopback server whose script an app loads while it is developed (`annotations/bridge.ts`), for web views without a DevTools port.
65
67
  - **Web components (PROP-0038).** The helper walks the composed tree: open shadow roots and slotted content can be picked, selected and revealed, and such targets carry `tree: 'composed'`. Targets without it resolve by the document-only rules as before. Closed shadow roots and frames stay out of reach, and the inspector says why it refuses something.
66
68
  - **Trust.** In Chromium targets the helper runs in an isolated script world, so the page cannot forge a comment. A send from the bridge, or from a host web view without isolation, waits for the person to confirm it.
@@ -109,7 +109,7 @@ resolve relevant drift by updating the implementation and specification together
109
109
  | ID | Where | What disagrees |
110
110
  |---|---|---|
111
111
  | 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. |
112
- | D-2 | `README.md` "Plugins" | Describes a `plugin_propose` tool and an Inbox for proposed plugins. No such tool exists in `src/`. |
112
+ | D-2 | Plugin proposal review surfaces | `plugin_propose` and hash-bound proposal APIs now exist; a terminal review UI is pending and no App review UI is claimed. See [PAR-017](../parity.md#gaps). |
113
113
  | D-3 | `README.md` "External curation" | Describes `externalMaintenance`, `vaultAccess`, `MAINTENANCE_PLUGIN`, `maintenance.*` methods and tools. None exist in `src/`. |
114
114
  | D-4 | `INV-BND-2` | Several names carry an application's name: the context message type `xingular-context`, the approval extension `xagent-approvals`, the MCP client name `xagent`, and the terminal commands `xagent-wiki` / `xagent-mcp`. The default product name `Xingular Agent` is allowed; these are not. |
115
115
  | D-5 | `INV-BND-2` | `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts. They are stored and returned, never read, and are documented as the application's fields. Since PROP-0016 (2026-10-23) `worktreeId` has Harness meaning when it names a registered worktree; only `handoffId` remains an application field. |
@@ -125,4 +125,6 @@ resolve relevant drift by updating the implementation and specification together
125
125
  | 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. |
126
126
  | 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. |
127
127
  | 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. |
128
+ | D-20 | Terminal pending queues, page 11 — resolved | The terminal now projects native and deferred pending messages above the working line. |
129
+ | D-19 | Provider limits layout | Page 09 describes a centered Limits dialog; page 11 and `src/terminal/tui/pages/usagePage.ts` describe and implement a full-screen page. |
128
130
  | D-18 | `core/index.ts` migration 5 | The `run_stats` table has no writer in the Harness. PROP-0042's `usage_requests` ledger is the analytics source; whether to drop the older table is open. |
@@ -1,14 +1,18 @@
1
1
  ---
2
2
  id: PROP-0018
3
3
  title: Inspector-style page notes, a fix queue to the agent, and app windows as capture targets
4
- status: Implemented
4
+ status: Implemented; queue, three-button popover and page_notes_mark_fixed superseded by PROP-0048
5
5
  created: 2026-10-23
6
- updated: 2026-10-23
6
+ updated: 2026-10-27
7
7
  affects: [INV-STO-3, INV-SRV-1, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
8
8
  ---
9
9
 
10
10
  # PROP-0018: Inspector, fix queue and app targets for page notes
11
11
 
12
+ > The fix queue, its three-button popover and `page_notes_mark_fixed` were replaced by
13
+ > [PROP-0048](PROP-0048-simple-annotate.md): a note is pending or sent, and the popover has Annotate
14
+ > and Annotate & send.
15
+
12
16
  Requested by the owner on 2026-10-23. They chose these four things:
13
17
  - the popover's three choices: Save, Queue, Send now
14
18
  - the popover drawn inside the page
@@ -0,0 +1,85 @@
1
+ ---
2
+ id: PROP-0048
3
+ title: One annotate page, two actions, and easy app attach
4
+ status: Implemented
5
+ created: 2026-10-27
6
+ updated: 2026-10-27
7
+ affects: [PROP-0018, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 13-world-tools.md, terminal-tui.md, parity.md]
8
+ ---
9
+
10
+ # PROP-0048: One annotate page, two actions, and easy app attach
11
+
12
+ ## Problem
13
+
14
+ People testing `/annotate:` found it hard to use:
15
+
16
+ - `/annotate:annotate` duplicated `/annotate:` in every command list.
17
+ - With no address, the page asked for one in a dialog that opened *behind* the full-screen page.
18
+ `PageOverlay` started its page in its constructor, before `dialogs.custom` mounted the overlay,
19
+ so any dialog the page opened as it started was stacked below it.
20
+ - While that hidden dialog waited, the page's single-action guard dropped every key (`s`, `i`)
21
+ without a word: "send queue sometimes doesn't work".
22
+ - A send held back while the agent was busy was tried once, 250 ms after the run ended. If the
23
+ terminal still reported its turn as active, the notes waited forever.
24
+ - `/annotate:notes` was a separate centred dialog with its own capture flow.
25
+ - The popover had three choices (save, ask the agent to fix, proceed now), the page had a queue, a
26
+ confirm step, an unqueue key and a "fixed" status reported by the agent's `page_notes_mark_fixed`.
27
+ - Attaching an Electron app needed its DevTools address typed by hand.
28
+
29
+ ## Design
30
+
31
+ **Delivery.** A note is either **pending** (shared with the session, unsent) or **sent**.
32
+ `NoteDelivery.state` is `pending | sent`; records written before this read `queued` as `pending`
33
+ and `fixed` as `sent`, without a migration write. Every annotation made in the inspector with a
34
+ session is shared with it at once. The popover has two buttons: **Annotate** (`save`) and
35
+ **Annotate & send** (`send`, also Cmd/Ctrl+Enter); `send` sends *all* the session's pending notes
36
+ as one message. Any other action the page reports is a save. Page-origin notes (DevTools or
37
+ bridge, untrusted) still wait for the person's confirmation; the terminal asks once for all of
38
+ them, and an `empty` send reports how many still wait.
39
+
40
+ `NoteDeliveries.runEnded` now tries a held-back send again (250 ms, 1 s, 3 s, 8 s) while the
41
+ session answers `busy`, and starts over if another run ends meanwhile.
42
+
43
+ `/annotate:submit <request>` sends the pending notes with the person's request after them
44
+ (`compose(notes, prompt)`). With no pending notes it sends nothing. A request is not kept while
45
+ the agent is busy; the notes stay pending and the person submits again. `/annotate:clear` resolves
46
+ the session's pending notes and withdraws their grant to it; they can be reopened from
47
+ `/annotate:notes`.
48
+
49
+ `page_notes_mark_fixed` is removed; the agent's page-note tools are read-only again. Only the
50
+ person resolves a note.
51
+
52
+ **Commands.** A built-in command may be `rootOnly`: it is the namespace root (`/annotate:`) and has
53
+ no named route, is not listed, and is not reachable as `/plugin:<name>`. The annotations plugin has
54
+ `/annotate: [url | --app [port] | --bridge]`, `/annotate:notes`, `/annotate:submit` and
55
+ `/annotate:clear`.
56
+
57
+ **One page.** `AnnotatePage` is one full-screen page with an **Annotate** tab and an **All
58
+ annotations** tab (`/annotate:notes` opens on the second). The Annotate tab takes the page address,
59
+ a DevTools port or an app path in an inline field, never a dialog. `a` opens a list of the apps
60
+ answering on a DevTools port on this computer, with *Start an app with a DevTools port*, *Type a
61
+ DevTools port*, *Use the page bridge* and *Annotate a web page instead*. The notes are grouped
62
+ **Unsent (n)** and **Sent**. A key pressed while the page is busy is answered with a notice.
63
+
64
+ `PageOverlay` starts its page when the host reports it mounted (`mounted()`, called by
65
+ `dialogs.custom` after `showOverlay`), or on the next turn for a host that does not. Dialogs a page
66
+ opens as it starts now stack above it, on every page.
67
+
68
+ **DevTools apps.** `AnnotationCapture.discover()` probes `127.0.0.1` on ports 9222–9230 and any port
69
+ used before, reading `/json/version` and `/json/list` with a short timeout. A Node inspector
70
+ (`node.js/…`) is skipped. `launchApp(key, path, args)` starts the program (the one inside a macOS
71
+ `.app` bundle) with `--remote-debugging-port=<free loopback port>`, waits for its DevTools port, and
72
+ attaches. The app keeps running after the capture ends. The loopback-only rule for `cdp` targets
73
+ is unchanged.
74
+
75
+ **Protocol.** Removed: `annotations.queue`, `annotations.dequeue`, `annotations.queued`. Added:
76
+ `annotations.pending`, `annotations.markPending`, `annotations.confirmAll`, `annotations.clear`,
77
+ `annotations.capture.discover`, `annotations.capture.launch`. `annotations.createAndAct` takes
78
+ `save | send`; `annotations.compose` and `annotations.send` take an optional `prompt`. Terminal
79
+ routes: `terminal.annotations.confirmAll|clear|discover|launch`; `queue` and `dequeue` are gone.
80
+
81
+ ## Consequences
82
+
83
+ The App's Annotate panel used `queue`, `fixed` and `createAndAct('queue')` and follows in its own
84
+ change. The prompt's Annotations group no longer names `page_notes_mark_fixed`, which changes the
85
+ stable prefix once.
@@ -77,6 +77,7 @@ it to the index and update its status as the work progresses.
77
77
  | [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
78
78
  | [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
79
79
  | [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
80
+ | [PROP-0048](PROP-0048-simple-annotate.md) | One annotate page, two actions, and easy app attach | Implemented; ADR-0044 | PROP-0018, 07, 10, 11, 13, terminal-tui.md, parity.md | 2026-10-27 |
80
81
 
81
82
  Numbers are four digits, start at `0001`, and are never reused.
82
83
 
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: ADR-0044
3
+ title: An annotation is pending or sent; the agent's page-note tools are read-only
4
+ status: Accepted
5
+ created: 2026-10-27
6
+ ---
7
+
8
+ # ADR-0044: An annotation is pending or sent
9
+
10
+ ## Decision
11
+
12
+ - Every annotation a person makes in the inspector with a session is shared with that session at
13
+ once and is **pending** until sent. There is no queue to add to or take out of, and no "fixed"
14
+ state. Records written before keep working: `queued` reads as `pending`, `fixed` as `sent`.
15
+ - The popover has two actions, Annotate and Annotate & send. A send sends every pending note of
16
+ the session as one message, optionally followed by the person's request (`/annotate:submit`).
17
+ - `page_notes_mark_fixed` is removed. The agent reads annotations; only the person resolves them.
18
+ - A held-back send is retried while the session is still busy after a run ends.
19
+ - Built-in plugin commands may be `rootOnly`, so a namespace root is not listed twice.
20
+
21
+ ## Why
22
+
23
+ People found three actions, a queue and a fix status too much to control, and the extra state is
24
+ what made sends fail silently. See [PROP-0048](../architecture/proposals/PROP-0048-simple-annotate.md).
@@ -0,0 +1,9 @@
1
+ # ADR-0045: Release-owned plugin-authoring skill
2
+
3
+ ## Decision
4
+
5
+ Ship plugin-authoring guidance as an on-demand Harness resource, selected for both structured and terminal sessions without changing variant versions. A pinned variant's skill of the same name takes precedence. The release supplies the resource in the package; the normal skill loader and Pi resource loader expose it. The guidance grants no trust or permissions.
6
+
7
+ ## Consequences
8
+
9
+ Existing variants receive the guidance without migration. Its release-owned content can change with the installed Harness version rather than with a variant fingerprint. Only its name and description are advertised until requested; the body does not enter the always-on variant text. Proposal creation and hash-bound review are separate from the skill and are recorded in [ADR-0046](ADR-0046-hash-bound-plugin-proposals.md).
@@ -0,0 +1,20 @@
1
+ # ADR-0046: Hash-bound plugin proposal review
2
+
3
+ ## Decision
4
+
5
+ Keep model-authored plugin proposals as inert, bounded text in the data root. The model may create
6
+ one through the gated `plugin_propose` tool; only a trusted caller may accept or reject it. Both
7
+ decisions require the hash of the current revalidated preview. The hash binds the name, description,
8
+ generated manifest and sorted file contents, not a person's identity or an authorization grant.
9
+ Acceptance publishes a new package switched off, does not run its code or grant trust, and refuses
10
+ an existing package name or identical already-trusted package code. Normal attachment, code trust,
11
+ capability and approval checks remain separate.
12
+
13
+ ## Consequences
14
+
15
+ Reviewers can inspect exactly the content a decision names, and stale or already-decided reviews
16
+ are refused. Text can itself contain hostile instructions and may load when enabled without code
17
+ trust; review must cover every contribution. Proposal records, including rejected ones, remain in
18
+ the data root; device-local code trust remains in the state directory. This decision does not claim
19
+ that a terminal or host review UI exists. See [06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
20
+ [10 Server protocol](../architecture/10-server-protocol.md), and [PAR-017](../parity.md#gaps).
@@ -0,0 +1,47 @@
1
+ ---
2
+ id: ADR-0047
3
+ title: A link a person clicks opens with the system's own handler, through one allowlist
4
+ status: Accepted
5
+ created: 2026-11-20
6
+ ---
7
+
8
+ # ADR-0047: A link a person clicks opens with the system's own handler
9
+
10
+ ## Decision
11
+
12
+ - `core/links.ts` holds the one link policy: `linkTarget` classifies a target without touching the
13
+ filesystem (`http`/`https`, `mailto`, `file`, an absolute path, or a relative path under a
14
+ supplied base), and `openableTarget` checks what a path names before anything is launched.
15
+ - A path may be opened only when it is a regular file or a directory, is not an application bundle
16
+ or an installer, is not a launchable script kind (`.command`, `.sh`, `.bat`, `.pkg`, `.dmg`,
17
+ `.app`, …), and has no executable bit set. The last two matter because `xdg-open` runs an
18
+ executable file and `open` launches a bundle.
19
+ - The address reaches `open` (macOS), `xdg-open` (Linux and the BSDs) or `rundll32.exe
20
+ url.dll,FileProtocolHandler` (Windows) as one argument, never through a shell.
21
+ - `links.open` is a server method, so a host presents the same capability, and the terminal is the
22
+ reference surface: hovering a link recolours it, and the gesture the platform uses opens it —
23
+ Ctrl+click where a terminal reports the modifier, and the primary click on macOS, whose ⌘ the
24
+ terminal mouse protocol cannot carry. The opener is `HarnessOptions.linkOpener`, so a host with
25
+ its own native opener replaces the spawn and keeps the policy.
26
+ - A link is a person's action. Nothing here is in `HARNESS_TOOLS`, so the gate, standing approvals
27
+ and redaction are not involved, exactly as with `variants.save`.
28
+ - Both front ends show the hover state: the terminal repaints the hovered link's spans in
29
+ `theme.linkHover`, and the App uses the shared `--link-hover` token on `a:hover`. The App's
30
+ modifier is the platform's own: ⌘ on macOS, Ctrl elsewhere.
31
+
32
+ ## Rationale
33
+
34
+ The terminal opened web links only, and the App opened web pages and stored documents in its
35
+ sidebar while silently swallowing everything else — `mailto:`, folders, relative paths and unknown
36
+ kinds. The allowlist existed three times (a terminal module, the App's TypeScript, and the App's
37
+ Rust), which is the drift the parity rules exist to prevent. One policy in the Harness, used by
38
+ both surfaces, is the smallest thing that makes a link behave the same everywhere.
39
+
40
+ ## Consequences
41
+
42
+ A refused link is reported, never ignored: the terminal posts a notice and the App reports an
43
+ error. Opening a document still hands its bytes to whichever application the system has associated
44
+ with that kind, which is inherent to the request; the deny list and the executable-bit check are
45
+ the boundary, not a sandbox. A host that wants different kinds to open replaces `linkOpener`, and
46
+ an architecture change would be needed to let a model open a link on its own, because that would
47
+ put an operating-system action inside the gate's reach.
package/docs/parity.md CHANGED
@@ -28,9 +28,10 @@ implemented is not a parity claim; acceptance is tracked per command.
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
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 | — |
30
30
  | Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
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 | — |
31
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 | — |
32
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 | — |
33
- | Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
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 |
34
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 |
35
36
  | Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
36
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 |
@@ -38,10 +39,11 @@ implemented is not a parity claim; acceptance is tracked per command.
38
39
  | Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
39
40
  | Skills | `plugins/`, `tools/dispatch.ts` | `skill_load` | `$name`, `/skill:name`, browser Skills tab | Capability, composer | parity | — |
40
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
+ | 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 |
41
43
  | Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
42
44
  | Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
43
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 |
44
- | Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` pane (also `/annotate:annotate`), `/annotate:notes` saved list | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | parity in the working tree; native WKWebView gestures unaccepted | PAR-011 |
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 |
45
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 |
46
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 |
47
49
  | History and trajectory (model tools) | `history/` | `history_*`, `trajectory_*` | `Terminals.ownTools` registers model tools through the session socket; `/trajectory` page; `/history` navigates session branches | structured tools and trajectory views | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
@@ -51,7 +53,7 @@ implemented is not a parity claim; acceptance is tracked per command.
51
53
  | Doctor | `doctor/` | `doctor.*` | `/doctor` | diagnostics | parity | — |
52
54
  | Run inspection | `sessions/runStore.ts` | `runs.*` | `/trajectory`, `/log` | run views, analytics | parity | — |
53
55
  | Usage analytics | `usage/` (PROP-0042) | `usage.summary`, `usage.sync` | `/usage:`, `/usage:analysis` page (Analysis tab) | not wired | terminal implemented; host planned | PAR-016 |
54
- | Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` page (Limits tab) | not wired | terminal implemented; host planned | PAR-016 |
56
+ | Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
55
57
  | 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 |
56
58
  | 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 |
57
59
  | Computer control | — | `computer_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
@@ -116,6 +118,7 @@ or live-model sketch quality.
116
118
 
117
119
  | ID | Gap | Planned change |
118
120
  |---|---|---|
121
+ | PAR-017 | Plugin proposal review surfaces | The terminal provides hash-bound review in `/plugins`; the App has no proposal review UI yet. |
119
122
  | 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. |
120
123
  | 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. |
121
124
  | PAR-003 | Continuation unused | `/resume` lists interrupted runs and continues one with `continueFrom`; the App offers Continue. |
@@ -126,7 +129,7 @@ or live-model sketch quality.
126
129
  | 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. |
127
130
  | 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. |
128
131
  | 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`. |
129
- | PAR-011 | Web annotations | Harness, terminal and App source done (PROP-0017, PROP-0018, 2026-10-24): the App calls `annotations.*`, imports its old notes once, uses the `page_notes_*` tools, and has the Annotate panel. Open: acceptance of the inspector and selection gestures in the running App's WKWebView. PROP-0038 (2026-10-25): both front ends share the page helper, so open shadow roots work in the terminal's capture browser and the App's tabs alike; composed text capture, save, resolve and reveal were exercised in an isolated App WKWebView, inspector clicks were not. |
132
+ | PAR-011 | Web annotations | Harness, terminal and App source done (PROP-0017, PROP-0018, 2026-10-24): the App calls `annotations.*`, imports its old notes once, uses the `page_notes_*` tools, and has the Annotate panel. Open: acceptance of the inspector and selection gestures in the running App's WKWebView. PROP-0038 (2026-10-25): both front ends share the page helper, so open shadow roots work in the terminal's capture browser and the App's tabs alike; composed text capture, save, resolve and reveal were exercised in an isolated App WKWebView, inspector clicks were not. PROP-0048 (2026-10-27): Harness and terminal moved to pending/sent with two popover actions, send-all with an optional request, clear, read-only page-note tools, and DevTools app discovery and launch; the App's Annotate panel still uses the removed queue methods and must follow. |
130
133
  | PAR-012 | Managed worktree management in Solo | Harness and terminal provide full worktree operations (PROP-0016). Solo `/worktree` lists records only: its renderer adapter does not wire typed `worktrees.create`, `status` or `remove` calls, and Solo session creation stays at the project folder with no worktree level. Handoff, branch, prune, restore and setup-trust actions are also absent from this Solo surface. |
131
134
  | 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. |
132
135
  | 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. |
@@ -0,0 +1,8 @@
1
+ # Xingular Harness 1.3.1-unstable.1
2
+
3
+ Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
4
+
5
+ - Import agent profiles from compatible plugins and continue stopped subagents across interruptions and restarts.
6
+ - Improve Windows shell, workspace write and edit support, with explicit per-call approval where an OS write-boundary sandbox is unavailable.
7
+ - Extend Doctor to check the active shell and exercise its workspace boundary with a fixed, no-network probe.
8
+ - Improve terminal subagent progress and plugin management, plus work-slice and plan-research behavior.
@@ -0,0 +1,11 @@
1
+ # Xingular Harness 1.3.1-unstable.2
2
+
3
+ Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
4
+
5
+ - Swap the OpenTUI send keys back. `Return` sends, or steers a running reply, and `Cmd+Return`,
6
+ `Ctrl+Return` or `Alt+Return` queues a follow-up. The `app.message.followUp` action replaces
7
+ `app.message.steer`, so a `keybindings.json` entry under that name needs renaming.
8
+ - Show pending steering, follow-up and deferred plan/Bash inputs above the working line, each with
9
+ its delivery type. A queued plan or `!` command is a barrier: it runs as a standalone turn and
10
+ later inputs wait behind it instead of entering Pi's native queues.
11
+ - Restore queued text to the draft with `Alt+Up`. Queued images are dropped; deferred images warn.
@@ -2,12 +2,14 @@
2
2
 
3
3
  1. Review and commit the completed Harness changes on the active release branch. Review App
4
4
  compatibility changes separately. Preserve old tags and exclude outputs, external references,
5
- and caches.
5
+ and caches. Stable versions use `X.Y.Z`; unstable previews use `X.Y.Z-unstable.N` and publish
6
+ to npm's `unstable` dist-tag. Use a new, unused version for every publication.
6
7
  2. Run `npm run ci` and the required App checks. Require green CI on Ubuntu and macOS; install Bun
7
8
  1.4.2 and use Node 22.19.0. Do not waive failing checks.
8
9
  3. Run `npm run release:pack` and inspect the candidate inventory, SHA-256 and npm integrity. Run
9
10
  `npm run release:smoke -- <tarball> --terminal` for a fresh-install SDK/server/terminal check;
10
- `--offline` is only a local smoke check, not fresh-install acceptance.
11
+ `--offline` is only a local smoke check, not fresh-install acceptance. Unstable candidates go
12
+ through the same checks as stable releases.
11
13
  4. Run `npm run release:preflight`. Verify npm scope ownership and trusted-publisher settings for
12
14
  `tanntnny/xingular-harness` and `release.yml`, with direct publishing enabled. Configure the
13
15
  GitHub `npm-publish` environment with required reviewers. No login is started automatically; an
@@ -20,8 +22,9 @@
20
22
  the protected `npm-publish` environment, compare the uploaded candidate's commit, SHA-256 and npm
21
23
  integrity with the approved local candidate; stop if they differ. This environment approval is a
22
24
  separate publication gate. The publish job publishes that same tarball with OIDC provenance and
23
- `--tag latest`, then verifies registry integrity/provenance and creates a GitHub release. No local
24
- publishing token is needed. Inspect registry state before retrying any failed publication.
25
+ `--tag latest` for stable versions or `--tag unstable` for unstable previews, then verifies the
26
+ matching registry dist-tag, integrity and provenance and creates a GitHub release (marked
27
+ prerelease for unstable versions). No local publishing token is needed. Inspect registry state before retrying any failed publication.
25
28
 
26
29
  A published version cannot be replaced. Corrections require a later version. This package's
27
30
  intentional 1.0.0 reset does not rewrite historical decisions or claim an ordering above older