@xingular/harness 1.0.0 → 1.2.0

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 (397) hide show
  1. package/CHANGELOG.md +46 -5
  2. package/README.md +75 -21
  3. package/dist/cli.js +17421 -8711
  4. package/dist/sdk/accounts/accounts.d.ts +27 -3
  5. package/dist/sdk/accounts/accounts.js +78 -24
  6. package/dist/sdk/accounts/secrets.d.ts +12 -0
  7. package/dist/sdk/accounts/secrets.js +114 -7
  8. package/dist/sdk/accounts/store.d.ts +26 -1
  9. package/dist/sdk/accounts/store.js +1 -1
  10. package/dist/sdk/agents/builtin.d.ts +2 -0
  11. package/dist/sdk/agents/builtin.js +48 -0
  12. package/dist/sdk/agents/narrow.d.ts +13 -0
  13. package/dist/sdk/agents/narrow.js +29 -0
  14. package/dist/sdk/agents/planResearch.d.ts +5 -0
  15. package/dist/sdk/agents/planResearch.js +19 -0
  16. package/dist/sdk/agents/profiles.d.ts +81 -0
  17. package/dist/sdk/agents/profiles.js +226 -0
  18. package/dist/sdk/annotations/bridge.d.ts +42 -0
  19. package/dist/sdk/annotations/bridge.js +264 -0
  20. package/dist/sdk/annotations/capture.d.ts +116 -0
  21. package/dist/sdk/annotations/capture.js +308 -0
  22. package/dist/sdk/annotations/delivery.d.ts +72 -0
  23. package/dist/sdk/annotations/delivery.js +130 -0
  24. package/dist/sdk/annotations/inspect.d.ts +10 -0
  25. package/dist/sdk/annotations/inspect.js +33 -0
  26. package/dist/sdk/annotations/isolated.d.ts +6 -0
  27. package/dist/sdk/annotations/isolated.js +51 -0
  28. package/dist/sdk/annotations/pageScript.d.ts +28 -0
  29. package/dist/sdk/annotations/pageScript.js +871 -0
  30. package/dist/sdk/annotations/part.d.ts +10 -0
  31. package/dist/sdk/annotations/part.js +155 -0
  32. package/dist/sdk/annotations/queue.d.ts +4 -0
  33. package/dist/sdk/annotations/queue.js +40 -0
  34. package/dist/sdk/annotations/serverMethods.d.ts +3 -0
  35. package/dist/sdk/annotations/serverMethods.js +62 -0
  36. package/dist/sdk/annotations/store.d.ts +167 -0
  37. package/dist/sdk/annotations/store.js +394 -0
  38. package/dist/sdk/browser/backend.d.ts +16 -0
  39. package/dist/sdk/browser/backend.js +17 -0
  40. package/dist/sdk/browser/contracts.d.ts +19 -0
  41. package/dist/sdk/browser/contracts.js +116 -0
  42. package/dist/sdk/browser/index.d.ts +14 -3
  43. package/dist/sdk/browser/index.js +11 -4
  44. package/dist/sdk/browser/serverMethods.d.ts +3 -0
  45. package/dist/sdk/browser/serverMethods.js +7 -0
  46. package/dist/sdk/browser/session.d.ts +1 -0
  47. package/dist/sdk/browser/session.js +45 -9
  48. package/dist/sdk/browser/tools.d.ts +1 -4
  49. package/dist/sdk/browser/tools.js +14 -91
  50. package/dist/sdk/cli.js +24 -15
  51. package/dist/sdk/commands/list.d.ts +3 -0
  52. package/dist/sdk/commands/list.js +75 -0
  53. package/dist/sdk/commands/registry.d.ts +250 -0
  54. package/dist/sdk/commands/registry.js +47 -0
  55. package/dist/sdk/commands/routes.d.ts +16 -0
  56. package/dist/sdk/commands/routes.js +33 -0
  57. package/dist/sdk/core/bus.js +1 -1
  58. package/dist/sdk/core/commandBudget.d.ts +23 -0
  59. package/dist/sdk/core/commandBudget.js +57 -0
  60. package/dist/sdk/core/env.d.ts +1 -1
  61. package/dist/sdk/core/env.js +1 -1
  62. package/dist/sdk/core/index.js +17 -1
  63. package/dist/sdk/core/interactiveProfile.d.ts +46 -0
  64. package/dist/sdk/core/interactiveProfile.js +143 -0
  65. package/dist/sdk/core/workspace.d.ts +13 -0
  66. package/dist/sdk/core/workspace.js +88 -0
  67. package/dist/sdk/core/workspaceBashTool.d.ts +4 -0
  68. package/dist/sdk/core/workspaceBashTool.js +36 -0
  69. package/dist/sdk/core/workspaceSandbox.d.ts +31 -0
  70. package/dist/sdk/core/workspaceSandbox.js +320 -0
  71. package/dist/sdk/core/workspaceWriteOperations.d.ts +22 -0
  72. package/dist/sdk/core/workspaceWriteOperations.js +206 -0
  73. package/dist/sdk/doctor/serverMethods.d.ts +3 -0
  74. package/dist/sdk/doctor/serverMethods.js +8 -0
  75. package/dist/sdk/doctor/types.d.ts +2 -2
  76. package/dist/sdk/harness.d.ts +22 -0
  77. package/dist/sdk/harness.js +84 -5
  78. package/dist/sdk/history/recall.js +8 -8
  79. package/dist/sdk/history/serverMethods.d.ts +3 -0
  80. package/dist/sdk/history/serverMethods.js +8 -0
  81. package/dist/sdk/hub/cli.d.ts +1 -1
  82. package/dist/sdk/hub/cli.js +1 -1
  83. package/dist/sdk/hub/schema.d.ts +1 -1
  84. package/dist/sdk/hub/serverMethods.d.ts +3 -0
  85. package/dist/sdk/hub/serverMethods.js +11 -0
  86. package/dist/sdk/index.d.ts +16 -1
  87. package/dist/sdk/index.js +10 -0
  88. package/dist/sdk/mcp/connections.js +14 -7
  89. package/dist/sdk/mcp/serverMethods.d.ts +3 -0
  90. package/dist/sdk/mcp/serverMethods.js +22 -0
  91. package/dist/sdk/pi/runtime.d.ts +2 -1
  92. package/dist/sdk/pi/runtime.js +2 -2
  93. package/dist/sdk/plugins/builtin.d.ts +1 -0
  94. package/dist/sdk/plugins/builtin.js +145 -33
  95. package/dist/sdk/plugins/builtinRegistry.d.ts +60 -0
  96. package/dist/sdk/plugins/builtinRegistry.js +71 -0
  97. package/dist/sdk/plugins/catalogue.js +2 -1
  98. package/dist/sdk/plugins/cli.d.ts +1 -1
  99. package/dist/sdk/plugins/cli.js +4 -3
  100. package/dist/sdk/plugins/commandPrefix.d.ts +8 -0
  101. package/dist/sdk/plugins/commandPrefix.js +21 -0
  102. package/dist/sdk/plugins/firstParty.d.ts +1 -1
  103. package/dist/sdk/plugins/firstParty.js +8 -2
  104. package/dist/sdk/plugins/inventory.js +4 -3
  105. package/dist/sdk/plugins/manifest.d.ts +2 -0
  106. package/dist/sdk/plugins/manifest.js +2 -1
  107. package/dist/sdk/plugins/surfaces.d.ts +5 -0
  108. package/dist/sdk/plugins/surfaces.js +11 -0
  109. package/dist/sdk/plugins/types.d.ts +15 -0
  110. package/dist/sdk/prompt/compile.d.ts +19 -2
  111. package/dist/sdk/prompt/compile.js +79 -26
  112. package/dist/sdk/prompt/standard.d.ts +17 -0
  113. package/dist/sdk/prompt/standard.js +21 -0
  114. package/dist/sdk/refine/cli.d.ts +1 -1
  115. package/dist/sdk/refine/cli.js +2 -2
  116. package/dist/sdk/refine/serverMethods.d.ts +3 -0
  117. package/dist/sdk/refine/serverMethods.js +20 -0
  118. package/dist/sdk/server/methods.js +27 -86
  119. package/dist/sdk/server/params.d.ts +4 -0
  120. package/dist/sdk/server/params.js +11 -0
  121. package/dist/sdk/server/remote.js +36 -11
  122. package/dist/sdk/sessions/compactionCheckpoint.d.ts +11 -0
  123. package/dist/sdk/sessions/compactionCheckpoint.js +79 -0
  124. package/dist/sdk/sessions/continuation.d.ts +3 -0
  125. package/dist/sdk/sessions/continuation.js +5 -1
  126. package/dist/sdk/sessions/contracts.d.ts +185 -0
  127. package/dist/sdk/sessions/contracts.js +101 -4
  128. package/dist/sdk/sessions/control.d.ts +72 -0
  129. package/dist/sdk/sessions/control.js +158 -0
  130. package/dist/sdk/sessions/initialBash.d.ts +7 -0
  131. package/dist/sdk/sessions/initialBash.js +7 -0
  132. package/dist/sdk/sessions/planMode.d.ts +18 -4
  133. package/dist/sdk/sessions/planMode.js +82 -16
  134. package/dist/sdk/sessions/reasoningSummaries.d.ts +2 -2
  135. package/dist/sdk/sessions/reasoningSummaries.js +3 -3
  136. package/dist/sdk/sessions/registry.d.ts +2 -1
  137. package/dist/sdk/sessions/registry.js +6 -3
  138. package/dist/sdk/sessions/runIndex.js +7 -7
  139. package/dist/sdk/sessions/runStore.d.ts +14 -0
  140. package/dist/sdk/sessions/runStore.js +38 -1
  141. package/dist/sdk/sessions/runner.d.ts +40 -2
  142. package/dist/sdk/sessions/runner.js +163 -15
  143. package/dist/sdk/sessions/sessions.d.ts +40 -8
  144. package/dist/sdk/sessions/sessions.js +279 -27
  145. package/dist/sdk/sessions/sideQuestionServerMethods.d.ts +3 -0
  146. package/dist/sdk/sessions/sideQuestionServerMethods.js +19 -0
  147. package/dist/sdk/sessions/sideQuestions.d.ts +66 -0
  148. package/dist/sdk/sessions/sideQuestions.js +290 -0
  149. package/dist/sdk/sessions/subagentServerMethods.d.ts +3 -0
  150. package/dist/sdk/sessions/subagentServerMethods.js +41 -0
  151. package/dist/sdk/sessions/subagentService.d.ts +22 -2
  152. package/dist/sdk/sessions/subagentService.js +93 -16
  153. package/dist/sdk/sessions/subagents.d.ts +9 -1
  154. package/dist/sdk/sessions/subagents.js +19 -0
  155. package/dist/sdk/sessions/workSlice.d.ts +103 -0
  156. package/dist/sdk/sessions/workSlice.js +297 -0
  157. package/dist/sdk/sessions/workspaceBoundary.d.ts +15 -0
  158. package/dist/sdk/sessions/workspaceBoundary.js +46 -0
  159. package/dist/sdk/terminal/browser.d.ts +62 -0
  160. package/dist/sdk/terminal/browser.js +41 -0
  161. package/dist/sdk/terminal/browserControl.d.ts +29 -0
  162. package/dist/sdk/terminal/browserControl.js +187 -0
  163. package/dist/sdk/terminal/commandHelp.d.ts +17 -0
  164. package/dist/sdk/terminal/commandHelp.js +20 -0
  165. package/dist/sdk/terminal/controller.d.ts +15 -1
  166. package/dist/sdk/terminal/controller.js +67 -8
  167. package/dist/sdk/terminal/opentui/subagentsWidget.d.ts +28 -0
  168. package/dist/sdk/terminal/opentui/subagentsWidget.js +52 -0
  169. package/dist/sdk/terminal/opentui/theme.d.ts +43 -0
  170. package/dist/sdk/terminal/opentui/theme.js +87 -0
  171. package/dist/sdk/terminal/piExtension.d.ts +6 -1
  172. package/dist/sdk/terminal/piExtension.js +169 -84
  173. package/dist/sdk/terminal/socket.d.ts +6 -3
  174. package/dist/sdk/terminal/socket.js +40 -9
  175. package/dist/sdk/terminal/standalone.d.ts +9 -0
  176. package/dist/sdk/terminal/standalone.js +118 -19
  177. package/dist/sdk/terminal/subagentMonitor.d.ts +47 -0
  178. package/dist/sdk/terminal/subagentMonitor.js +152 -0
  179. package/dist/sdk/terminal/terminals.d.ts +60 -7
  180. package/dist/sdk/terminal/terminals.js +598 -47
  181. package/dist/sdk/terminal/trajectory.js +2 -2
  182. package/dist/sdk/terminal/tui/annotateCommand.d.ts +3 -0
  183. package/dist/sdk/terminal/tui/annotateCommand.js +22 -0
  184. package/dist/sdk/terminal/tui/commandPages.d.ts +7 -1
  185. package/dist/sdk/terminal/tui/commandPages.js +57 -6
  186. package/dist/sdk/terminal/tui/commands.d.ts +10 -4
  187. package/dist/sdk/terminal/tui/commands.js +269 -65
  188. package/dist/sdk/terminal/tui/dialogGeometry.d.ts +2 -2
  189. package/dist/sdk/terminal/tui/dialogGeometry.js +4 -2
  190. package/dist/sdk/terminal/tui/dialogs.d.ts +6 -1
  191. package/dist/sdk/terminal/tui/dialogs.js +9 -2
  192. package/dist/sdk/terminal/tui/list.d.ts +14 -1
  193. package/dist/sdk/terminal/tui/list.js +96 -14
  194. package/dist/sdk/terminal/tui/modelPicker.js +1 -6
  195. package/dist/sdk/terminal/tui/page.d.ts +3 -0
  196. package/dist/sdk/terminal/tui/pageOverlay.js +27 -7
  197. package/dist/sdk/terminal/tui/pages/accountsPage.d.ts +26 -4
  198. package/dist/sdk/terminal/tui/pages/accountsPage.js +264 -36
  199. package/dist/sdk/terminal/tui/pages/agentsPage.d.ts +74 -0
  200. package/dist/sdk/terminal/tui/pages/agentsPage.js +190 -0
  201. package/dist/sdk/terminal/tui/pages/annotatePage.d.ts +94 -0
  202. package/dist/sdk/terminal/tui/pages/annotatePage.js +341 -0
  203. package/dist/sdk/terminal/tui/pages/browserPage.d.ts +87 -0
  204. package/dist/sdk/terminal/tui/pages/browserPage.js +738 -0
  205. package/dist/sdk/terminal/tui/pages/doctorPage.d.ts +2 -0
  206. package/dist/sdk/terminal/tui/pages/doctorPage.js +103 -15
  207. package/dist/sdk/terminal/tui/pages/notesPage.d.ts +75 -0
  208. package/dist/sdk/terminal/tui/pages/notesPage.js +201 -0
  209. package/dist/sdk/terminal/tui/pages/pluginsPage.d.ts +0 -5
  210. package/dist/sdk/terminal/tui/pages/pluginsPage.js +9 -3
  211. package/dist/sdk/terminal/tui/pages/settingsPage.d.ts +8 -0
  212. package/dist/sdk/terminal/tui/pages/settingsPage.js +16 -1
  213. package/dist/sdk/terminal/tui/pages/subagentsPage.d.ts +24 -0
  214. package/dist/sdk/terminal/tui/pages/subagentsPage.js +152 -0
  215. package/dist/sdk/terminal/tui/pages/trajectoryPage.d.ts +12 -5
  216. package/dist/sdk/terminal/tui/pages/trajectoryPage.js +156 -83
  217. package/dist/sdk/terminal/tui/pages/usagePage.d.ts +43 -0
  218. package/dist/sdk/terminal/tui/pages/usagePage.js +370 -0
  219. package/dist/sdk/terminal/tui/pages/worktreesPage.d.ts +72 -0
  220. package/dist/sdk/terminal/tui/pages/worktreesPage.js +203 -0
  221. package/dist/sdk/terminal/tui/piAdapter.d.ts +1 -2
  222. package/dist/sdk/terminal/tui/piAdapter.js +3 -5
  223. package/dist/sdk/terminal/tui/planMode.d.ts +1 -1
  224. package/dist/sdk/terminal/tui/planMode.js +1 -1
  225. package/dist/sdk/terminal/tui/pluginCommands.d.ts +16 -0
  226. package/dist/sdk/terminal/tui/pluginCommands.js +31 -0
  227. package/dist/sdk/terminal/tui/questions.d.ts +2 -0
  228. package/dist/sdk/terminal/tui/runtime.js +27 -5
  229. package/dist/sdk/terminal/tui/sessionPicker.d.ts +40 -0
  230. package/dist/sdk/terminal/tui/sessionPicker.js +141 -0
  231. package/dist/sdk/terminal/tui/settingsModel.d.ts +2 -0
  232. package/dist/sdk/terminal/tui/settingsModel.js +32 -2
  233. package/dist/sdk/terminal/tui/sideQuestion.d.ts +26 -26
  234. package/dist/sdk/terminal/tui/sideQuestion.js +131 -98
  235. package/dist/sdk/terminal/tui/ui.d.ts +2 -0
  236. package/dist/sdk/terminal/tui/ui.js +1 -0
  237. package/dist/sdk/tools/askUser.js +26 -8
  238. package/dist/sdk/tools/checklist.js +3 -2
  239. package/dist/sdk/tools/checkpoint.d.ts +27 -0
  240. package/dist/sdk/tools/checkpoint.js +154 -0
  241. package/dist/sdk/tools/getCapabilities.d.ts +31 -0
  242. package/dist/sdk/tools/getCapabilities.js +34 -0
  243. package/dist/sdk/tools/harnessTools.d.ts +2 -0
  244. package/dist/sdk/tools/harnessTools.js +1 -1
  245. package/dist/sdk/tools/spawnSubagent.js +14 -4
  246. package/dist/sdk/usage/analytics.d.ts +20 -0
  247. package/dist/sdk/usage/analytics.js +151 -0
  248. package/dist/sdk/usage/ledger.d.ts +38 -0
  249. package/dist/sdk/usage/ledger.js +142 -0
  250. package/dist/sdk/usage/limits/adapters.d.ts +11 -0
  251. package/dist/sdk/usage/limits/adapters.js +349 -0
  252. package/dist/sdk/usage/limits/capture.d.ts +8 -0
  253. package/dist/sdk/usage/limits/capture.js +47 -0
  254. package/dist/sdk/usage/limits/http.d.ts +12 -0
  255. package/dist/sdk/usage/limits/http.js +51 -0
  256. package/dist/sdk/usage/limits/normalize.d.ts +15 -0
  257. package/dist/sdk/usage/limits/normalize.js +211 -0
  258. package/dist/sdk/usage/limits/service.d.ts +30 -0
  259. package/dist/sdk/usage/limits/service.js +176 -0
  260. package/dist/sdk/usage/limits/types.d.ts +65 -0
  261. package/dist/sdk/usage/limits/types.js +1 -0
  262. package/dist/sdk/usage/serverMethods.d.ts +3 -0
  263. package/dist/sdk/usage/serverMethods.js +22 -0
  264. package/dist/sdk/usage/service.d.ts +32 -0
  265. package/dist/sdk/usage/service.js +66 -0
  266. package/dist/sdk/usage/settings.d.ts +7 -0
  267. package/dist/sdk/usage/settings.js +28 -0
  268. package/dist/sdk/usage/types.d.ts +60 -0
  269. package/dist/sdk/usage/types.js +4 -0
  270. package/dist/sdk/web/part.d.ts +10 -0
  271. package/dist/sdk/web/part.js +6 -0
  272. package/dist/sdk/web/serverMethods.d.ts +3 -0
  273. package/dist/sdk/web/serverMethods.js +7 -0
  274. package/dist/sdk/wiki/serverMethods.d.ts +3 -0
  275. package/dist/sdk/wiki/serverMethods.js +26 -0
  276. package/dist/sdk/worktrees/cli.d.ts +11 -0
  277. package/dist/sdk/worktrees/cli.js +146 -0
  278. package/dist/sdk/worktrees/copy.d.ts +9 -0
  279. package/dist/sdk/worktrees/copy.js +111 -0
  280. package/dist/sdk/worktrees/git.d.ts +16 -0
  281. package/dist/sdk/worktrees/git.js +81 -0
  282. package/dist/sdk/worktrees/serverMethods.d.ts +3 -0
  283. package/dist/sdk/worktrees/serverMethods.js +30 -0
  284. package/dist/sdk/worktrees/service.d.ts +73 -0
  285. package/dist/sdk/worktrees/service.js +483 -0
  286. package/dist/sdk/worktrees/setup.d.ts +23 -0
  287. package/dist/sdk/worktrees/setup.js +65 -0
  288. package/dist/sdk/worktrees/types.d.ts +91 -0
  289. package/dist/sdk/worktrees/types.js +1 -0
  290. package/dist/sdk/world/cli.d.ts +2 -2
  291. package/dist/sdk/world/cli.js +6 -6
  292. package/dist/sdk/world/world.d.ts +3 -1
  293. package/dist/sdk/world/world.js +8 -9
  294. package/dist/terminal-opentui.js +16456 -5966
  295. package/dist/terminal-pi.js +1579 -573
  296. package/docs/README.md +22 -2
  297. package/docs/architecture/00-overview.md +28 -16
  298. package/docs/architecture/02-sessions-and-runs.md +184 -25
  299. package/docs/architecture/03-variants.md +10 -2
  300. package/docs/architecture/04-prompt.md +65 -7
  301. package/docs/architecture/06-plugins-and-capabilities.md +57 -4
  302. package/docs/architecture/07-tools-and-gate.md +112 -17
  303. package/docs/architecture/08-memory-and-history.md +4 -2
  304. package/docs/architecture/09-accounts-and-connectors.md +39 -1
  305. package/docs/architecture/10-server-protocol.md +168 -4
  306. package/docs/architecture/11-terminal.md +251 -8
  307. package/docs/architecture/12-storage.md +45 -3
  308. package/docs/architecture/13-world-tools.md +49 -6
  309. package/docs/architecture/14-surfaces-and-parity.md +136 -0
  310. package/docs/architecture/README.md +17 -4
  311. package/docs/architecture/proposals/PROP-0006-run-checklist.md +4 -2
  312. package/docs/architecture/proposals/PROP-0013-resource-browser.md +58 -0
  313. package/docs/architecture/proposals/PROP-0014-fullscreen-browser-tabs.md +58 -0
  314. package/docs/architecture/proposals/PROP-0015-one-capability-surface.md +88 -0
  315. package/docs/architecture/proposals/PROP-0016-managed-worktrees.md +156 -0
  316. package/docs/architecture/proposals/PROP-0017-page-annotations.md +131 -0
  317. package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md +179 -0
  318. package/docs/architecture/proposals/PROP-0019-contextual-side-questions.md +122 -0
  319. package/docs/architecture/proposals/PROP-0020-builtin-feature-plugins.md +105 -0
  320. package/docs/architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md +99 -0
  321. package/docs/architecture/proposals/PROP-0022-plan-only-questions.md +102 -0
  322. package/docs/architecture/proposals/PROP-0023-xagent-cli-name.md +61 -0
  323. package/docs/architecture/proposals/PROP-0024-question-sketch-previews.md +130 -0
  324. package/docs/architecture/proposals/PROP-0025-contextual-question-wireframes.md +49 -0
  325. package/docs/architecture/proposals/PROP-0026-connected-sketch-display.md +94 -0
  326. package/docs/architecture/proposals/PROP-0027-xingular-agent-product-identity.md +60 -0
  327. package/docs/architecture/proposals/PROP-0028-normalize-question-wireframes.md +55 -0
  328. package/docs/architecture/proposals/PROP-0029-agent-profiles.md +124 -0
  329. package/docs/architecture/proposals/PROP-0030-subagent-title.md +86 -0
  330. package/docs/architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md +54 -0
  331. package/docs/architecture/proposals/PROP-0032-planning-quality.md +196 -0
  332. package/docs/architecture/proposals/PROP-0033-compaction-plan-checkpoints.md +75 -0
  333. package/docs/architecture/proposals/PROP-0034-conversation-fast-mode.md +120 -0
  334. package/docs/architecture/proposals/PROP-0035-retain-subagent-status.md +47 -0
  335. package/docs/architecture/proposals/PROP-0036-first-class-harness-commands.md +59 -0
  336. package/docs/architecture/proposals/PROP-0037-workspace-write-boundary.md +63 -0
  337. package/docs/architecture/proposals/PROP-0038-annotate-open-shadow-roots.md +73 -0
  338. package/docs/architecture/proposals/PROP-0039-workspace-boundary-hardening.md +139 -0
  339. package/docs/architecture/proposals/PROP-0040-one-launch-path.md +87 -0
  340. package/docs/architecture/proposals/PROP-0041-bounded-work-slices.md +247 -0
  341. package/docs/architecture/proposals/PROP-0042-usage-and-provider-limits.md +127 -0
  342. package/docs/architecture/proposals/PROP-0043-read-only-plan-bash.md +74 -0
  343. package/docs/architecture/proposals/README.md +39 -0
  344. package/docs/decisions/ADR-0001-owned-terminal.md +1 -1
  345. package/docs/decisions/ADR-0009-xharness-command.md +6 -5
  346. package/docs/decisions/ADR-0014-public-release-baseline.md +3 -2
  347. package/docs/decisions/ADR-0015-resource-browser.md +28 -0
  348. package/docs/decisions/ADR-0016-fullscreen-browser-tabs.md +31 -0
  349. package/docs/decisions/ADR-0017-one-capability-surface.md +34 -0
  350. package/docs/decisions/ADR-0018-builtin-feature-plugins.md +35 -0
  351. package/docs/decisions/ADR-0019-managed-git-worktrees.md +31 -0
  352. package/docs/decisions/ADR-0020-page-annotations.md +37 -0
  353. package/docs/decisions/ADR-0021-required-command-namespaces.md +40 -0
  354. package/docs/decisions/ADR-0022-plan-only-question-tools.md +34 -0
  355. package/docs/decisions/ADR-0023-contextual-side-question-runs.md +35 -0
  356. package/docs/decisions/ADR-0024-xagent-command.md +40 -0
  357. package/docs/decisions/ADR-0025-question-choice-sketches.md +49 -0
  358. package/docs/decisions/ADR-0026-contextual-question-wireframes.md +58 -0
  359. package/docs/decisions/ADR-0027-connected-sketch-display.md +60 -0
  360. package/docs/decisions/ADR-0028-xingular-agent-product-identity.md +56 -0
  361. package/docs/decisions/ADR-0029-normalized-question-wireframe-borders.md +33 -0
  362. package/docs/decisions/ADR-0030-agent-profiles.md +43 -0
  363. package/docs/decisions/ADR-0031-plugin-command-owner-namespaces.md +37 -0
  364. package/docs/decisions/ADR-0032-compaction-run-checkpoints.md +33 -0
  365. package/docs/decisions/ADR-0033-plan-mode-research-delegation.md +47 -0
  366. package/docs/decisions/ADR-0034-first-class-harness-terminal-commands.md +25 -0
  367. package/docs/decisions/ADR-0035-one-launch-path.md +40 -0
  368. package/docs/decisions/ADR-0036-workspace-write-operation-boundary.md +54 -0
  369. package/docs/decisions/ADR-0037-usage-ledger-and-provider-limits.md +44 -0
  370. package/docs/decisions/ADR-0038-plan-bash-os-read-only.md +29 -0
  371. package/docs/doctor.md +10 -4
  372. package/docs/experiments/EXP-0003-performance-audit/data/session-runtime-replication.json +420 -0
  373. package/docs/experiments/EXP-0003-performance-audit/data/session-runtime.json +420 -0
  374. package/docs/experiments/EXP-0003-performance-audit/data/terminal-compact.json +376 -0
  375. package/docs/experiments/EXP-0003-performance-audit/data/terminal-history.json +422 -0
  376. package/docs/experiments/EXP-0003-performance-audit/data/terminal-question.json +95 -0
  377. package/docs/experiments/EXP-0003-performance-audit/data/terminal-wide.json +1036 -0
  378. package/docs/experiments/EXP-0003-performance-audit/plan.md +109 -0
  379. package/docs/experiments/EXP-0003-performance-audit/results.md +151 -0
  380. package/docs/features/README.md +26 -0
  381. package/docs/features/interfaces/README.md +1 -1
  382. package/docs/future-work.md +48 -0
  383. package/docs/handoff-2026-10-25-app-parity-and-solo-tabs.md +202 -0
  384. package/docs/parity.md +134 -0
  385. package/docs/releases/1.0.0.md +2 -2
  386. package/docs/releases/1.1.1.md +28 -0
  387. package/docs/releases/1.2.0.md +49 -0
  388. package/docs/releases/4.0.0.md +47 -0
  389. package/docs/releases/README.md +37 -27
  390. package/docs/study/00-index.md +8 -0
  391. package/docs/study/STUDY-0003-long-horizon-runs.md +210 -0
  392. package/docs/study/autonomous-engineering-sources.md +277 -0
  393. package/docs/study/autonomy-sources.md +147 -0
  394. package/docs/study/proactive-autonomy.md +408 -0
  395. package/docs/study/tui-resource-browser.md +78 -0
  396. package/docs/terminal-tui.md +386 -113
  397. package/package.json +6 -5
@@ -1,9 +1,14 @@
1
1
  # Harness terminal frontend
2
2
 
3
- Status: release candidate `@xingular/harness` 4.0.0; npm publication blocked by registry authorization. Last updated: 2026-10-22.
3
+ Status: current terminal behavior, checked against `@xingular/harness` 1.2.0. Last updated: 2026-11-19.
4
4
  Decision: [ADR-0001](decisions/ADR-0001-owned-terminal.md),
5
5
  [ADR-0006](decisions/ADR-0006-opentui-only-terminal.md),
6
- [ADR-0009](decisions/ADR-0009-xharness-command.md).
6
+ [ADR-0009](decisions/ADR-0009-xharness-command.md),
7
+ [ADR-0021](decisions/ADR-0021-required-command-namespaces.md),
8
+ [ADR-0024](decisions/ADR-0024-xagent-command.md),
9
+ [ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md),
10
+ [ADR-0027](decisions/ADR-0027-connected-sketch-display.md),
11
+ [ADR-0028](decisions/ADR-0028-xingular-agent-product-identity.md).
7
12
 
8
13
  ## OpenTUI terminal
9
14
 
@@ -24,19 +29,26 @@ overrides the Bun executable.
24
29
  `TerminalRuntime`, session replacement, commands, decisions, account pinning and run records. It
25
30
  projects the runtime's snapshot and transcript into an OpenCode-inspired view, with a native
26
31
  OpenTUI textarea for the prompt, `Ctrl+K` for the command palette, `Return` to send (or to queue behind a running reply),
27
- `Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline. With an
28
- empty composer, unmodified Up recalls the latest non-empty user message from the active session.
29
- After recall, unmodified Up/Down are available for normal editor movement and do not browse history
30
- while the draft is non-empty. Ctrl+Up/Down remain explicit history shortcuts; Down past the newest
31
- entry restores a blank draft. History comes from the active Pi session's saved messages, so `/new`
32
- and `/resume` switch to that session's history. Steering needs a terminal that reports Cmd with the
32
+ `Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline. Typing `/` or `$` filters
33
+ matching commands or skills; `Tab` inserts the selected entry and leaves the cursor at the end of the inserted text.
34
+ With an empty composer, unmodified Up recalls the latest non-empty user message from the active session.
35
+ With a draft, unmodified Up browses older history and Down browses newer history when the caret is at
36
+ either absolute draft endpoint (start or end). Down past the newest entry restores the draft, cursor
37
+ and attachments that were present when history browsing began. At non-endpoint positions, Up on the
38
+ first visual line moves the cursor to the first character and Down on the last visual line moves it
39
+ to the final character; elsewhere, Up/Down move the caret normally. Ctrl+Up/Down remain explicit
40
+ history shortcuts from anywhere. History includes
41
+ user messages and Bash commands from the active Pi session; recalled Bash commands return to `!`
42
+ mode. Executed slash commands from this terminal instance are included too, across session switches.
43
+ `/new` and `/session` (also `/resume`) switch the saved-message and Bash history to that session.
44
+ Steering needs a terminal that reports Cmd with the
33
45
  kitty keyboard protocol; elsewhere `Alt+Return` steers. In the composer, `Tab` opens up to eight matching filesystem entries for the path token at the cursor, or current-folder entries when the token is empty. The list has no heading or hint row. Up/Down select; Enter or Tab inserts the selection; Escape closes the list. Directories end in `/`, and Bash mode escapes shell-special characters. Use `/effort` or Shift+Up/Down to change effort. The command palette opens above the composer under a muted (`dim`) top rule, and has no other border. Its rows align slash commands and descriptions in two columns: the command column sizes to the widest visible name, bounded to preserve description space, and both columns wrap instead of truncating. The plan-choice rule, question block's top-only divider, and `/btw` block's top rule use the same muted color as the normal composer divider. The console has no background of its own: the renderer, root surface
34
46
  and transcript are transparent, so the terminal's own background shows through, while panels,
35
47
  dialogs and the scrim stay opaque. The composer has no panel background: it is bounded by a top and
36
48
  a bottom rule, with the working status and spinner above it and a wrapping status bar below it. Its
37
49
  fixed-width left gutter shows `❯` on the first input row and leaves continuation rows blank, including
38
50
  explicit newlines and soft wraps; Bash mode shows `!` on the first row instead. In plan mode,
39
- `plan mode` is right-aligned within the top rule, followed by exactly one divider character. The status bar shows the working folder's name, the Git branch, the account, model and effort separated by spaces, and input (`↑`) and output (`↓`) token counts with each glyph adjacent to its count; `|` separates the groups. Token counts
51
+ `plan mode` is right-aligned within the top rule, followed by exactly one divider character. The status bar shows the working folder's name and Git branch together as `<repo>:<branch>`, followed by the account, model and effort separated by spaces, and input (`↑`) and output (`↓`) token counts with each glyph adjacent to its count; `|` separates the groups. Token counts
40
52
  below 1,000 show as whole numbers and larger counts use K/M/B suffixes. A leading `!`
41
53
  enters Bash mode: the chevron becomes `!`, and the marker and both rules use the `bashMode` colour.
42
54
  In plan mode, the marker and rules use the plan blue and `plan mode` is right-aligned within the
@@ -50,29 +62,51 @@ never receive an OpenTUI renderable or a second account. A theme an extension se
50
62
  its own components, while the OpenTUI chrome keeps the fixed OpenCode-inspired palette. Component
51
63
  UI is supported; an extension that draws only by writing raw ANSI through the TUI terminal is not.
52
64
 
53
- Pages become centered dialogs. The page commands `/accounts`, `/permissions`, `/plugins`,
54
- `/hub`, `/components`, `/settings`, `/trajectory` and `/log`, the `/model` and `/tree` pickers, and
65
+ Most pages become centered dialogs. The page commands `/permissions`, `/log`, the `/model` and
66
+ `/history` pickers, and
55
67
  the `select`, `confirm`, `input` and `editor` dialogs (such as `/effort` and the Thinking setting),
56
68
  take 80% of the terminal, capped at 100 columns by 30 rows, on a flat panel in the console's panel
57
69
  colour. A full-screen scrim dims the console behind the panel so the transcript stays faintly
58
70
  visible. Centered Harness dialogs fit their rendered content, capped by the available dialog
59
71
  height, with four columns of horizontal padding and two rows of vertical padding to account for
60
72
  the terminal's taller-than-wide cells. They use a plain title with a muted `Esc` hint and
61
- omit divider rules and footer hints. Shortcut behavior remains available. Searchable lists share
73
+ omit divider rules and footer hints. Shortcut behavior remains available. Bracketed paste and the
74
+ clipboard-paste shortcut insert text into the active dialog input or search field, using that
75
+ component's input semantics; images and file attachments remain composer-only. Searchable lists share
62
76
  the same glyph, placeholder, spacing, and muted result note, with search context included on that
63
77
  row. A terminal too small for a 30-column by
64
78
  12-row dialog falls back to the full-screen page chrome. A plugin's full-screen surface stays full
65
- screen.
79
+ screen. `/settings` fills the terminal with its category tabs, search, settings list and full-screen
80
+ page chrome. `/accounts` also fills the terminal with Accounts/Pools tabs and search. Wide terminals
81
+ show selected-account details beside the list; opening an account reveals grouped actions in that
82
+ inspector. On compact terminals, opening an account replaces the list with a full-page detail view
83
+ and its grouped actions. `Enter` opens the selected account; `Esc` returns to the list. Tab and
84
+ Shift+Tab move focus between tabs, the list and (when open) actions; Left/Right changes a focused
85
+ tab and Up/Down moves the focused list or action list. Search, section and account selection survive
86
+ returning and resizing.
87
+ Account actions are grouped by Session, Account, Sign-in and Remove; pool
88
+ actions are grouped by Manage and Remove. Existing confirmations and account-service calls remain
89
+ unchanged. The Harness resource browser and all its shortcuts use a full-screen page with persistent
90
+ resource-section tabs.
66
91
 
67
92
  The frontend is verified with a real isolated PTY and a loopback provider. Run
68
- `python3 scripts/verify-terminal.py --composer-only` for explicit-newline and soft-wrap checks of
69
- both prompt gutters plus normal/plan/Bash mode exclusivity, `--file-completion-only` for filesystem
70
- completion and insertion,
71
- `--history-only` for active-session history across `/new` and `/resume`, `--help-only` for `/help` replacing the welcome screen, `--questions-only` for recommended choices,
93
+ `python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
94
+ welcome, product label, accent colors and `/help` transition. Run
95
+ `python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
96
+ and a user bubble, unknown-command and argument colors, explicit-newline and soft-wrap checks of both
97
+ prompt gutters, and normal/plan/Bash mode exclusivity. Run it with `--sizes 40x20,80x24,120x40` for
98
+ compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
99
+ input dialog, `--file-completion-only` for filesystem completion and insertion,
100
+ `--history-only` for active-session history across `/new` and `/session`, `--resume-only` for the full-screen searchable, unnumbered two-line saved-session picker, `--help-only` for `/help` replacing the welcome screen with grouped two-column output that wraps without per-command gaps, `--questions-only` for multi-select marker glyphs, recommended choices,
72
101
  selected-row and Continue/Submit colors, `--jump-latest-only` for scroll-away badge visibility and click-to-latest (screen-level click assertions use optional `pyte`), and choice-backed “Something else” answers, or `--thinking-only` for `/thinking` visibility toggles. The full suite covers a complete turn, `read`, `bash` approval, `ask_user_question` approval and picker, plugin overlay/widget/status
73
102
  disposal, a completed run record with usage and decision events, `/help`, `/permissions`,
74
- `/settings`, `/model`, palette selection, confirm cancel, and Ctrl+D exit. Live-provider behavior,
75
- exact OpenCode parity and concurrent session tabs are not established.
103
+ `/settings`, `/model`, palette selection, confirm cancel, and Ctrl+D exit. `--questions-only` checks
104
+ recommended choices, bounded literal ASCII sketch previews, focus-driven preview changes and answer
105
+ colors; run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. At 80 columns and
106
+ above it also checks wrapped notes and free-text; the narrowest run keeps the sketch and answer
107
+ interaction compact. The normal turn omits question tools; plan-mode flows exercise `ask_user` batches
108
+ and `ask_user_question` cancellation. Live-provider behavior, exact OpenCode parity and concurrent
109
+ session tabs are not established.
76
110
 
77
111
  ## Native subagents (2026-10-18)
78
112
 
@@ -85,8 +119,30 @@ The terminal joins outstanding children before its final reply, projects child a
85
119
  with their original run IDs, and stops descendants when interrupted or disposed. Connected apps
86
120
  need not be enabled. `TerminalPrepareInput.subagents: null` disables the capability.
87
121
 
88
- Real scripted Pi execution over the actual terminal socket verifies result delivery and decision
89
- routing. It does not establish live-provider behavior or new visual UI parity. See
122
+ The terminal also projects the latest parent's subagent descendants into rows under the status line
123
+ and a searchable `/subagents` page. The rows poll a private monitor route once per second
124
+ during a turn and make a final read at settlement. They sit one blank row below the status line, with
125
+ no heading, and each reads: the status mark, the agent profile name in its colour (`subagent` for a
126
+ copy of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` from the
127
+ child's own checklist. At most three show, active first, then `+N more · /subagents`. The
128
+ `/subagents` page uses a colored profile and normal-color title on the first line, then muted account,
129
+ effective model, effort and cumulative usage metadata on the second. One blank row separates each
130
+ two-line entry. The page also shows status, elapsed time and the latest tool name. Runtime metadata
131
+ stays in the private terminal projection.
132
+ Usage contains safe token/cache/cost/context totals, not per-request payloads or reasoning summaries.
133
+ The projection is read-only, flat across nested descendants, and scoped to the latest parent run in
134
+ this terminal session; finished rows remain visible until the next parent run starts. It is cleared
135
+ on session replacement or terminal disposal. It never includes tool arguments (beyond the title),
136
+ output or checklist item text.
137
+
138
+ `/agents` opens the Agents page (PROP-0029): built-in, global, project and variant profiles with
139
+ their tools, plugins, variant, model and instructions. Enter on a row edits a person's own profile
140
+ in `$VISUAL`/`$EDITOR`, copies one, or deletes one after confirmation; New profile writes a template
141
+ in the project or global folder and opens it.
142
+
143
+ Real scripted Pi execution over the actual terminal socket verifies result delivery, decision
144
+ routing, and the monitor's parent scoping and summary redaction. It does not establish live-provider
145
+ behavior. See
90
146
  [ADR-0003](decisions/ADR-0003-shared-asynchronous-subagents.md) for recovery and lifecycle details.
91
147
 
92
148
  ## Ownership and process boundary
@@ -95,7 +151,7 @@ Harness owns its interactive terminal application in
95
151
  [`src/terminal/opentui/`](../src/terminal/opentui/). [`app.ts`](../src/terminal/opentui/app.ts)
96
152
  owns terminal lifecycle, submission, commands, decisions and run records;
97
153
  [`root.tsx`](../src/terminal/opentui/root.tsx) owns composition, the transcript, the composer,
98
- palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.2.0 supplies the
154
+ palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.4.0 supplies the
99
155
  persistent agent session, model and auth runtime, native JSONL history, tool execution and rich
100
156
  content components.
101
157
 
@@ -132,24 +188,42 @@ unattended execution path.
132
188
  ## Screen layout
133
189
 
134
190
  [`root.tsx`](../src/terminal/opentui/root.tsx) draws the terminal on OpenTUI's alternate screen.
135
- An empty conversation shows the centered product mark and a short hint; once a message exists, a
136
- scrollable transcript fills the space above the composer. Single-line notices can appear with the
137
- welcome, while multiline notices such as `/help` switch to the transcript layout so their output
138
- cannot overlap it. The composer is a single top and bottom rule, with the right-aligned `plan mode` label followed by one divider character in the top rule,
191
+ An empty conversation shows a centered welcome. The default `Xingular Agent` identity appears as
192
+ an orange block `X` and blue letter-spaced `A G E N T`, followed by `Welcome.`, the tagline
193
+ `One run, done well.`, and a blue `/help` hint. Explicit host product names use the same generic mark and
194
+ subline formatting. The current model and thinking level remain available in dim text. Once a message
195
+ exists, a scrollable transcript fills the space above the composer. Single-line notices can appear
196
+ with the welcome, while multiline notices such as `/help` switch to the transcript layout so their
197
+ output cannot overlap it. The composer is a single top and bottom rule, with the right-aligned `plan mode` label followed by one divider character in the top rule,
139
198
  and the textarea in the middle.
140
199
  The working status row shows the active verb with a soft, warm glint that feathers across it and
141
200
  fades past its edges, followed by run duration and the latest completed assistant response's output
142
201
  rate, formatted as `(time, tok/s)`; the spinner and metrics stay steady, and duration updates during a run.
143
202
  Until response usage is available, the rate shows `— tok/s`. On settlement, the completion verb and
144
203
  final run statistics stay in that row until the next run replaces them; they do not become a transcript
145
- entry. Notifications, queue announcements, compaction-start and retry updates—including retries
146
- while summarizing context or branches—are one-line transcript entries at the point they occur, so
147
- subsequent chat moves them up rather than keeping them pinned at the bottom. A completed context
148
- compaction adds a first-class card from Pi's persisted session history, showing the token count and
149
- an expandable Markdown summary; click the card or use Ctrl+O to toggle its details.
150
- A successful transcript-selection copy instead shows a temporary, opaque toast at the top-right of the
151
- terminal. Interactive blocks and widgets remain docked above the composer. A wrapping status bar
152
- below the composer shows the working folder, branch, account, model, effort and token totals. After
204
+ entry. Notifications, queue announcements and retry updates—including retries while summarizing
205
+ context or branches—are one-line transcript entries at the point they occur, so subsequent chat
206
+ moves them up rather than keeping them pinned at the bottom.
207
+
208
+ While context compaction runs, the working line shows `Compacting context` (or `Retrying
209
+ compaction`) with the same spinner, in place of the working verb. During a run it keeps the run's
210
+ clock; a `/compact` while idle shows the spinner with its own clock. Compaction does not start a new
211
+ session or hide earlier chat. After it, the transcript shows, in order: the whole conversation from
212
+ before the compaction (rebuilt from Pi's session history, kept messages included); a rule labelled
213
+ `Context compacted · <tokens> tokens`; the summary printed as a normal reply; an `End of summary`
214
+ rule; then the work that followed. The summary is shown by default. Clicking either rule hides or
215
+ shows it, and Ctrl+O shows every summary again. On a narrow screen the rule drops the click hint, then
216
+ the token count. Earlier compactions in the same session keep their own rules and summary in place.
217
+ Notices stay after the message they followed. The model sees the summary and recent messages plus a
218
+ bounded, hidden checkpoint of the active request, checklist and plan instructions when available;
219
+ the checkpoint is regenerated for each post-compaction request until the run settles. The visible
220
+ transcript remains a presentation of the full history, not the model context.
221
+ Transcript entry ids follow positions in the displayed message list, so when a rebuilt list moves a
222
+ different kind of entry onto an id, the renderer builds a new component for it instead of reusing the
223
+ old layout, and each entry draws inside its own error boundary. A run therefore keeps updating live
224
+ through a compaction; it does not need `/resume` to show its later output.
225
+ A successful copy shows a temporary, opaque toast anchored at the terminal's top-right. Interactive blocks and widgets remain docked above the composer. A wrapping status bar
226
+ below the composer shows `<repo>:<branch>`, account, model, effort and token totals, with `|` between groups. After
153
227
  the input token count it shows cache hit rate as `R<percentage>%`, calculated from cache reads divided
154
228
  by total input tokens. The footer shows status messages without a shortcut-hint row. Press `?` with an empty
155
229
  composer to open the shortcut reference. Transcript entries include
@@ -165,15 +239,17 @@ their content; other entries have no internal vertical padding. Bubble padding i
165
239
  inter-entry gap. Internal lines within an entry stay together. The transcript stays pinned to the
166
240
  latest message until you scroll away. While scrolled away, a `↓ Jump to latest` badge overlays the
167
241
  transcript's lower-right corner; clicking it returns to the newest message and hides the badge.
168
- `Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty welcome area focuses the composer. Dragging to select
169
- transcript text copies the selected plain text when the selection is released; a simple click does
170
- not copy. `/copy` and `Ctrl+X` continue to copy the latest assistant reply.
242
+ `Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty
243
+ welcome area focuses the composer. Dragging to select text anywhere in the TUI—including the
244
+ composer, transcript, widgets, dialogs and pages—copies the selected plain text when selection ends;
245
+ a simple click does not copy. `/copy` and `Ctrl+X` continue to copy the latest assistant reply.
171
246
 
172
247
  Mouse movement highlights the row under the pointer in the command palette, plan choices, question
173
248
  dock, searchable dialogs and Harness page lists; the highlight uses the same selection style as
174
249
  keyboard navigation. A primary click activates the row, and clicks on page tabs switch that page's
175
- section. Question choices still stage their answer until the question's action is clicked. Dialogs
176
- preserve their existing confirmation safeguards. OpenTUI enables terminal mouse-motion reporting for
250
+ section. In `/accounts`, clicking an account opens its inspector or compact detail view, and clicking
251
+ an action runs the existing account flow. Question choices still stage their answer until the
252
+ question's action is clicked. Dialogs preserve their existing confirmation safeguards. OpenTUI enables terminal mouse-motion reporting for
177
253
  hover; terminals or multiplexers that do not report motion retain keyboard navigation. ANSI-only
178
254
  custom UI without a mouse handler remains keyboard-driven.
179
255
 
@@ -192,6 +268,16 @@ OSC 8 support. Inline and fenced code use a subtle panel fill with syntax colors
192
268
  list markers, tables, dividers and task-list markers use the existing titanium palette. Images
193
269
  display their alt text and are not fetched or rendered as image files.
194
270
 
271
+ ## Checklist block
272
+
273
+ `checklist_write` is registered in terminal sessions (PAR-001). Each call renders in the
274
+ transcript as a checklist block: a status mark, `Checklist · n of m done`, then one line per item
275
+ with `✓` (done, success colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim).
276
+ Each row reserves a one-cell status column and one-cell gap; item text and wrapped lines share the
277
+ same starting column. A call whose arguments are not a checklist, or that failed, stays an ordinary
278
+ tool row. The prompt's Progress group asks the model to keep the list current and write a final
279
+ update before replying; unfinished work remains unfinished rather than being marked complete.
280
+
195
281
  ## Blocks and pages
196
282
 
197
283
  In Pi's own terminal UI, [`chrome.ts`](../src/terminal/tui/chrome.ts) gives terminal surfaces one
@@ -203,9 +289,10 @@ of two rule-based shapes, using the 2-cell composer gutter on each side and a di
203
289
  Approvals, questions, and the `select`, `confirm`, `input` and `editor` dialogs use this shape
204
290
  there. OpenTUI renders Harness-managed centered dialogs with the inset header treatment below.
205
291
  - A **page** is a header row (title left, position or status right), a neutral rule, the body,
206
- a neutral rule, and the hint row. `/settings`, `/trajectory`, `/log`, `/permissions`, and the
207
- `/accounts`, `/plugins` and `/hub` menus are pages. Section labels inside a page are plain bold
208
- headings, never text set into a rule.
292
+ a neutral rule, and the hint row. `/settings`, `/log`, `/permissions`, and the `/accounts`,
293
+ `/plugins` and `/hub` menus are pages. Section labels inside a page are plain bold headings, never
294
+ text set into a rule. `/trajectory` is a full-screen page with searchable Runs and Events
295
+ tabs; its Events view keeps the event list beside the selected event's JSON on wide terminals.
209
296
 
210
297
  `DialogPanel` takes a `variant` (`block` by default). `ui.select` accepts a harness-owned `page`
211
298
  option, which Pi's own dialogs ignore, so the same extension code runs in either terminal. Selected
@@ -214,24 +301,82 @@ frontends draw that field from the same muted-blue selection palette (`selection
214
301
  explicit high-contrast text on it instead of the accent colour, so a choice reads the same in every
215
302
  list. Rules use the theme's `warning` and `dim` colors, so a custom theme restyles them.
216
303
 
217
- Each page command owns a separate page and its own tab strip: `/accounts` has Accounts
218
- and Pools; `/permissions` has Overview and Tools; `/plugins` has Plugins and Trust; `/hub` has
219
- Catalog and Installed; `/components` has Skills, Prompts and Rules; `/settings` has the available
220
- settings categories; `/trajectory` has Runs and Events; and `/log` has Diagnostics and Run Events.
221
- Commands never share one cross-page tab strip. Tab and Shift+Tab move between the current page's
222
- tabs; in centered dialogs, Left and Right move between those tabs too. Up and Down move through
223
- rows, while PageUp/PageDown, Home and End move through rows or details. Trajectory keeps `[` and
224
- `]` for run navigation; its Up and Down arrows select events. The `/model` scope tabs and `/tree`
225
- filter tabs also respond to Left and Right. Every list and picker places the same `⌕ Type to
226
- search` row immediately under its title or strip, with its result count at the right. Compact pickers
227
- such as `/model`, `/tree`, `/resume` and `/fork` do not show a page strip. Escape clears a non-empty
228
- search before closing. Left and right are passed to the current page and do not switch commands.
229
-
230
- `/components` browses skills, prompts and rules in the component library. After confirmation, a skill
231
- or rule is added to the attached Harness scope as a new variant version for future sessions; the current
232
- terminal stays pinned to the version it started with. Prompts remain browse-only, and terminals without
233
- a writable scope can browse but cannot add items. These changes go through the extension's private
234
- control key, so model-issued shell commands cannot add a component.
304
+ The Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills, Plugins,
305
+ Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/plugins`, `/connections`
306
+ (`/mcp`) and `/tools` open sections. `/hub` selects Discover and `/components` selects Library.
307
+ The existing Accounts, Permissions, Settings, Trajectory and Log pages retain their own tabs.
308
+
309
+ `/settings` includes a Browser tab with the device-local **Private address access** setting. It is
310
+ off by default. Enabling it asks for confirmation and allows agent browsing and annotation capture
311
+ to reach localhost and private networks.
312
+
313
+ Resource sections share Installed/Discover and source filters. Installed includes locally present
314
+ resources; current-session availability comes only from the runtime loader and active tool registry.
315
+ Discover uses the existing Hub with All/Community/Official filtering and an explicit remote refresh.
316
+ No matching community entries is an empty result, never replaced with built-in resources.
317
+ The view preserves search across source switches and restores section selection on return.
318
+
319
+ The browser fills the terminal (PROP-0014), with Overview, Foundation, Variant, Skills, Plugins,
320
+ Connections, Tools and Library as persistent top tabs. The section dropdown and sidebar are removed.
321
+ When the strip cannot fit, it shows the active tab and its position with previous/next navigation.
322
+ At 88 content columns, inventory sits beside an inspector containing metadata, actions and readable
323
+ content. Enter focuses the inspector. Its action rows group related tasks under Use, Inspect, Manage,
324
+ Access and Remove. Compact terminals show details/content within the active tab; resizing preserves
325
+ the selected resource and content position, clamped to the available height.
326
+
327
+ Tab/Shift+Tab focuses tabs, source, filter, toolbar actions, list and (when available) inspector.
328
+ Left/Right changes the focused tab or control; Enter on the tab strip returns to the inventory.
329
+ Ctrl+F focuses search. Escape returns from content to actions, returns to the list, clears search,
330
+ then closes. Mouse clicks select tabs directly, activate resource actions and focus filters;
331
+ wheel scrolling targets the list or inspector under the pointer. Other command pages keep their
332
+ centered presentation; `/settings` and `/accounts` use full-screen page layouts. Closing the browser preserves
333
+ the composer draft and attachments.
334
+
335
+ Foundation explains fixed runtime ownership; it is read-only. Variant shows c1–c8 with the
336
+ prepared version and current head separately. It previews pinned files from the preparation
337
+ snapshot and compares their text with the latest saved version. No in-place editing or adoption
338
+ is added. Library skills and rules are added through `terminal.components.add`, which commits a
339
+ validated future version. Directory-backed variants stay read-only.
340
+
341
+ Skill browsing is independent of the Skill commands setting. Use inserts a leading `$name`
342
+ without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
343
+ the existing draft text and attachment labels. Canceling the filter restores that draft. OpenTUI completes
344
+ loaded skills for a leading `$`; Enter or Tab inserts the selected skill rather than sending.
345
+ Plugin contributions, settings, attachment and code trust share one detail flow. Package install
346
+ and removal delegate to existing services; installing never trusts or activates code.
347
+
348
+ Connections supports local stdio and remote HTTP forms, masked credentials, explicit scope,
349
+ saved disabled defaults, explicit testing and OAuth sign-in. Browsing never starts an MCP process.
350
+ Saved test results show timestamps rather than claiming a live connection. A Hub connector document
351
+ is inert: a separate setup action validates supported remote-definition fields before opening the
352
+ normal connection form. Other document kinds stay inspectable data. Tools show their owner,
353
+ parameters, active state and saved approval; each call still passes the gate.
354
+
355
+ The typed model is `terminal/browser.ts`; the protected adapter is `terminal/browserControl.ts`.
356
+ The browser accepts resource IDs for bounded regular-file previews, not arbitrary paths. Local
357
+ skill import rejects symbolic links and limits bytes, files and traversal. See
358
+ [source study and wireframes](study/tui-resource-browser.md),
359
+ [PROP-0013](architecture/proposals/PROP-0013-resource-browser.md) and
360
+ [ADR-0015](decisions/ADR-0015-resource-browser.md).
361
+
362
+ ## Annotate pane (PROP-0018)
363
+
364
+ `/annotate:` opens the full-screen capture pane (equivalent to `/annotate:annotate`) beside the window being inspected. Add a page address with `/annotate:annotate [url]`. The target window is one of:
365
+ - the visible capture browser
366
+ - an app's own windows attached over its DevTools port (`--app`)
367
+ - app windows that loaded the page bridge script (`--bridge`)
368
+
369
+ The header shows the target and window and whether the inspector is on. The list has three groups: Queue, Sent and fixed, and Saved. While the inspector is on, the page polls for the next popover comment every 400 ms, shows the result as a notice, and refreshes the list.
370
+
371
+ | Key | Action |
372
+ |---|---|
373
+ | `i` | inspector on/off |
374
+ | `s` | send the queue |
375
+ | `x` | unqueue the selected note |
376
+ | `t` | choose a window |
377
+ | `Enter` | the note menu |
378
+
379
+ The page has no search row, so these letters are free for actions. `/annotate:notes` opens the searchable Web annotations list.
235
380
 
236
381
  ## Plan mode and thinking keys
237
382
 
@@ -239,10 +384,16 @@ Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi'
239
384
  queue until the active response settles, then runs by itself. Later messages remain behind it, even
240
385
  when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
241
386
  (`read`, `grep`, `find`, `ls`), web search/page reading, questions (`ask_user`, `ask_user_question`)
242
- and recall (history and Wiki reads, `memory_facts`). Providers may mark individual calls as safe for
243
- research; every other call is blocked before approval. Edits, writes, shell commands, memory writes,
244
- subagents and connected-app tools remain unavailable. The plan instructions arrive as a
245
- request-scoped prompt section, which the next ordinary request withdraws.
387
+ and recall (history and Wiki reads, `memory_facts`). It may also delegate bounded research to a
388
+ named profile whose effective tool and plugin allowlists qualify for research; the child inherits
389
+ plan mode and receives only the intersection of the parent's frozen capabilities, profile and
390
+ plan-research set. Children cannot write, run commands, ask the user, use connectors or spawn more
391
+ children. Normal mode omits both question tools from the active set; the plan request enables
392
+ registered questions and research delegation temporarily and restores the normal set when it settles,
393
+ including on failure or interruption. Providers may mark individual calls as safe for research; every
394
+ other call is blocked before approval. Edits, writes, shell commands, memory writes and connected-app
395
+ tools remain unavailable to the parent and child. The plan instructions arrive as a request-scoped
396
+ prompt section, which the next ordinary request withdraws.
246
397
 
247
398
  Each mode keeps its own model and effort for the account. Every selection the person makes (the model
248
399
  picker, `/effort`, Shift+Up/Down, Ctrl+P) is saved against the mode it was made in, so Shift+Tab switches to that
@@ -254,7 +405,7 @@ and the App reads and writes them through `accounts.choices` and `accounts.choos
254
405
  A bare `/plan` toggles plan mode, and Shift+Tab cycles between normal and plan mode. Normal, plan
255
406
  and Bash are mutually exclusive composer modes. While plan mode is on, each submitted message is sent
256
407
  as a plan request through that same queue, and the composer's top and bottom rules take the plan colour.
257
- Commands still run as commands. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
408
+ Commands still run as commands. The model may run Bash during a plan request, only in the read-only sandbox scope (PROP-0043); your own `!` commands are not part of the plan. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
258
409
  switches to plan mode and keeps the draft text. Turning plan mode off returns to normal mode. The old
259
410
  on/off/toggle forms are rejected; a bare `/plan` is the switch.
260
411
 
@@ -268,9 +419,11 @@ Implement leaves plan mode, so the normal tools and the mode's own model and eff
268
419
  mode and focuses the composer, so the next message revises the plan and offers a new choice. A plan run
269
420
  that was interrupted, failed, or had work queued behind it is not offered.
270
421
 
271
- While typing, a recognized leading slash command uses the selected theme's link color. This
272
- includes built-in commands, loaded extension and prompt commands, and enabled skill invocations
273
- written as `/skill:name`. Unknown slash tokens keep the normal text color.
422
+ A recognized leading slash command uses the selected theme's link color while typing and in its
423
+ user-message bubble. Only the command token is accented; arguments and unknown slash tokens keep the
424
+ normal text color. Recognition follows the active command registry, including built-in commands and
425
+ aliases, loaded extension and prompt commands, and enabled skill invocations written as
426
+ `/skill:name`.
274
427
 
275
428
  SDK session runs receive plan instructions as a dynamic context update, leaving the stable system
276
429
  prompt unchanged; their session gate refuses calls outside the read-only set. The standalone
@@ -287,13 +440,17 @@ the marker and rules blue; in the normal prompt, the marker matches the divider
287
440
  an empty Bash body returns to the normal prompt. Submitting while a reply is active queues
288
441
  the command as a standalone turn; it does not steer the current model request.
289
442
 
290
- The terminal extension checks Bash policy and requests approval before using Pi's native
291
- `executeBash`. Output streams into the transcript while the command runs, so browser-login URLs are
292
- visible before the command finishes; the running item shows that Escape stops the command. The
293
- native result is recorded in run activity and session history before the model is prompted to read
294
- and explain it. This does not attach interactive stdin to the shell. SDK callers may opt into this
295
- behavior with `SessionRunInput.initialBashCommand`; it is restricted to a new interactive user turn
296
- and the session runner applies the same Bash gate.
443
+ The terminal checks Bash policy before using Pi's native `executeBash`. Ordinary `!command` runs
444
+ workspace-scoped; `!outside <command>` explicitly requests human-only approval before the command
445
+ runs once with broader filesystem access. The complete command is shown as escaped, scrollable
446
+ approval details; if the terminal is too small to show both details and choices, the request is
447
+ denied. Shell output never triggers approval or replay. Output streams into the transcript while the
448
+ command runs, so browser-login URLs are visible before the
449
+ command finishes; the running item shows that Escape stops the command. The native result is
450
+ recorded in run activity and session history before the model is prompted to read and explain it.
451
+ This does not attach interactive stdin to the shell. SDK callers may opt into this behavior with
452
+ `SessionRunInput.initialBashCommand`; it is restricted to a new interactive user turn and the
453
+ session runner applies the same Bash gate and explicit outside-scope request.
297
454
 
298
455
  ## Reference and reproduced presentation
299
456
 
@@ -311,8 +468,8 @@ not an arbitrary checkout of upstream main. The source repository is
311
468
  In the extracted `pi-tui` package, `src/theme/defaults/titanium.json` establishes the titanium
312
469
  palette and its indexed-color fallbacks. Harness adapts these into
313
470
  [`theme.ts`](../src/terminal/tui/theme.ts) and
314
- [`opentui/theme.ts`](../src/terminal/opentui/theme.ts). The OpenTUI status bar shows the project name,
315
- branch, account, model, context use and current-session input/output totals. Input totals add cache
471
+ [`opentui/theme.ts`](../src/terminal/opentui/theme.ts). The OpenTUI status bar shows the project name and
472
+ branch together as `<repo>:<branch>`, followed by account, model, context use and current-session input/output totals. Input totals add cache
316
473
  reads and exclude cache writes; its `R<percentage>%` hit rate is cache reads divided by total input.
317
474
  Token counts below 1,000 show as whole numbers; larger counts use floor-rounded K/M/B suffixes
318
475
  without decimals.
@@ -337,7 +494,7 @@ Full upstream copyright and MIT permission notices are in [NOTICE.md](../NOTICE.
337
494
  ## Runtime compatibility adapter
338
495
 
339
496
  Most integration uses public Pi exports. [`piAdapter.ts`](../src/terminal/tui/piAdapter.ts)
340
- contains the remaining presentation dependencies and requires exactly Pi **1.2.0** before
497
+ contains the remaining presentation dependencies and requires exactly Pi **1.4.0** before
341
498
  loading them. The shared [`runtime.ts`](../src/pi/runtime.ts) loader imports Pi first, then invokes
342
499
  the same HTTP dispatcher hook as Pi's CLI before any Harness Pi runtime is used. This reapplies
343
500
  the process `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` settings after Pi's bundled Undici has
@@ -347,7 +504,7 @@ concurrent initialization.
347
504
 
348
505
  | Internal dependency | Reason |
349
506
  |---|---|
350
- | `dist/bundle/chunks/chunk-TJXZSVTD.js:configureHttpDispatcher` | Restore Pi's environment-aware HTTP proxy dispatcher after the SDK import |
507
+ | `dist/bundle/chunks/chunk-MM3LKT73.js:configureHttpDispatcher` | Restore Pi's environment-aware HTTP proxy dispatcher after the SDK import |
351
508
  | `dist/extensions/index.js` builtin inventory | Preserve selected `llama.cpp`, `codemode`, `tool-search` and MCP builtins with the CLI's replacement semantics |
352
509
  | `dist/modes/interactive/theme/theme.js:setThemeInstance` | Keep public native rich components on the same active theme as the Harness screen |
353
510
  | `dist/core/tools/renderers/index.js:withBuiltInRenderers` | Preserve existing read/edit/bash/write formatting without replacing tool execution |
@@ -403,7 +560,7 @@ personal Pi profile. Provider authentication and model catalogs use that account
403
560
  The selected account stays pinned. The existing `/accounts` command requests a parent-managed
404
561
  restart to use a different account while resuming the conversation.
405
562
 
406
- An initial `--session` or `/resume` target must resolve inside the prepared history directory,
563
+ An initial `--session` option or `/session` target (also accepted as `/resume`) must resolve inside the prepared history directory,
407
564
  including symlink targets, and its stored absolute working folder must match the terminal's
408
565
  canonical working folder. `/import` may copy an explicitly selected external native JSONL file
409
566
  only when its recorded working folder matches. A caller cannot override a foreign recorded
@@ -450,22 +607,74 @@ a tool waiting forever on a question after the screen has closed. Native `sessio
450
607
  clears controller readiness and stops that session's poller; the replacement's `session_start`
451
608
  restores readiness while retaining the same process control claim.
452
609
 
453
- The bridge exposes the shared `ask_user` batch tool alongside the existing single-question
454
- `ask_user_question` contract. Every question must include at least one choice and at least one
455
- recommended choice; recommendations remain visual and never preselect. Choice-based questions also
456
- retain a free-text “Something else” answer. A pending question appears in a flat block immediately above the
457
- composer, not in a modal. It has only a muted top divider and separates its hint from the content by
458
- one blank line. The block shows one batch question at a time with previous/next navigation and batch
459
- progress, choices and descriptions, a numbered free-text answer row after the choices, and a Continue
460
- or Skip action. Selected choices fill the whole row with subtle dark green; Continue and Submit uses
461
- a green-filled button, while Skip remains neutral. The regular composer remains below it for a direct message to the waiting session.
462
- Tab and Shift+Tab move focus through the available controls; Tab from a focused selected choice opens
463
- its inline note field. In multi-select questions, Tab can open a note for each selected choice; notes
464
- are submitted by choice label and cleared when that choice is deselected. While the block is active,
465
- Tab takes precedence over the normal thinking and plan-mode shortcuts. Up and Down navigate choices;
466
- Left and Right navigate the batch while choices or the action are focused. Enter selects a choice,
467
- activates the focused action, or submits the answer or note field. Escape interrupts the pending
468
- question. Press `x` from the choices or action to collapse the block; Tab reopens it.
610
+ The bridge registers the shared `ask_user` batch tool alongside the single-question
611
+ `ask_user_question` contract; only plan requests activate them. Each question has a concise 1–2 word
612
+ label, at least one choice, and at least one recommended choice; recommendations remain visual and
613
+ never preselect. Choice-based questions also retain a free-text “Something else” answer. A pending
614
+ question occupies the composer position in a flat block, not a modal, with the chat transcript
615
+ above it. The dock fits its content and grows to at most two-thirds of the terminal height; each
616
+ question tab is sized from its own content. When content overflows, its body scrolls while tabs and
617
+ answer/action controls stay outside that region.
618
+ The final choice sits one blank row above “Something else”. The block has only a muted top divider
619
+ and separates its hint from the content by one blank line; below 60 terminal columns, it uses a
620
+ compact hint. While the dock is active, PageUp/PageDown scroll its body and Ctrl+Home/End jump to
621
+ its beginning/end instead of the transcript. Focused choices and note fields are brought into view.
622
+ A tab strip shows each question label above the active question title, with one blank row below the tabs
623
+ and below the title;
624
+ clicking a tab or using Left/Right changes questions without discarding staged answers. The header has
625
+ no pager controls, and the block cannot be collapsed. Choices and descriptions appear above the numbered free-text answer and Continue or Skip
626
+ action. Selected choices fill the whole row with subtle dark green; Continue and Submit uses a
627
+ green-filled button, while Skip remains neutral. While the block is active, the chat composer and
628
+ its lower status bar are hidden. Tab and Shift+Tab move through the available controls; `n` opens a
629
+ note for the focused selected choice. Its editor appears below that choice, aligned with the description
630
+ column, and begins with an accent-colored `Note:` label. Tab only visits note fields that are already
631
+ open. Notes are submitted by choice label and cleared when that choice is deselected. Notes and
632
+ free-text answers wrap across lines. Tab takes precedence over normal thinking and plan-mode shortcuts. Up
633
+ and Down navigate choices. Enter selects a choice, activates the focused action, or submits the
634
+ answer or note field. Escape cancels the pending question and interrupts the run.
635
+
636
+ Questions may set `uiSketch: true` to enable a choice sketch preview. Every choice must then include
637
+ an ASCII sketch of 1–24 LF-separated lines, no more than 80 printable ASCII characters per line
638
+ (1,943 bytes maximum), and at least one visible character. Tabs, CR, controls, escape sequences and
639
+ non-ASCII text are rejected. Without the flag, choice sketches are rejected. Tool guidance asks for
640
+ contextual UI wireframes with actual panel/table structure and neighboring elements, consistent
641
+ across alternatives, rather than isolated decorative diagrams; quality is not a schema guarantee.
642
+
643
+ The dock uses one shared measured layout for all choices: marker gutter, one-third label cell,
644
+ two-cell gap, and remaining description cell. Boundaries align across rows at every width, including
645
+ compact terminals; both cells wrap independently, missing descriptions keep their cell, and columns
646
+ never stack. Recommendation text becomes `(Rec.)` when the label column is fewer than 14 cells.
647
+ Multi-select choices use `✓` when selected and `○` when unselected, matching checklist glyphs;
648
+ single-choice options remain numbered.
649
+
650
+ One shared border-only monospace preview below the choices follows the hovered choice, falling
651
+ back to keyboard focus. It has no visible caption or extra left rule. Under the approved
652
+ [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md) /
653
+ [ADR-0027](decisions/ADR-0027-connected-sketch-display.md) and
654
+ [PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) /
655
+ [ADR-0029](decisions/ADR-0029-normalized-question-wireframe-borders.md) amendments,
656
+ the terminal display uses a bounded structural projection in
657
+ `src/terminal/opentui/sketchPanel.ts`: recognized ASCII table-border rows—including title-bearing
658
+ top rules—and enclosed vertical table edges become connected box-drawing glyphs. Internal framed
659
+ tables keep their original widths and positions. Within a high-confidence frame, a missing side
660
+ edge may be filled or a displaced edge moved only through whitespace to matched corner columns;
661
+ interior text and ambiguous rows remain literal. Bare standalone hyphen divider rows expand to
662
+ `max(panel viewport width, original sketch widest line)` and attach to the outer single-line frame
663
+ with `├` and `┤`. Prose, content operators, ordinary pipes and unrecognized rows remain literal;
664
+ there is no global `+|-` substitution. The original validated ASCII source, including whitespace,
665
+ is persisted untouched; normalization and projected glyphs are display-only.
666
+
667
+ A bounded two-axis viewport exposes all overflow without wrapping, reflow, truncation or
668
+ Markdown/ANSI interpretation. Shift+arrows pan the sketch; ordinary arrows retain question/choice
669
+ navigation. Hosts may keep literal previews of that same source. The preview does not change the
670
+ selected answer, and sketch metadata is not included in the answer event. The 80×24 source bounds
671
+ and dock layout remain as specified by
672
+ [PROP-0025](architecture/proposals/PROP-0025-contextual-question-wireframes.md) and
673
+ [ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md). Isolated production PTY evidence
674
+ for [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md) and
675
+ [PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) is retained under
676
+ `docs/evidence/terminal-wireframe-normalization/`; it does not claim every-emulator rendering or
677
+ live-model sketch quality.
469
678
 
470
679
  Recommended choices appear first with a warning-colored marker, without changing their labels or
471
680
  preselecting them; every question requires at least one recommendation. A single-choice question
@@ -480,22 +689,40 @@ event subscriptions and custom transcript components detach before native invali
480
689
  Cleanup failures cannot prevent terminal restoration. Fatal asynchronous errors restore the
481
690
  terminal and exit with failure; startup failures and suspend/resume use the same lifecycle.
482
691
 
483
- The command registry supplies help and completion for Harness commands, loaded extensions,
484
- prompts and enabled skills. `/plugins` includes the protected code trust workflow. A plugin with
485
- settings has a **Settings** row under it on the Plugins tab; Enter opens its settings as a subpage
486
- (`Plugins › <title>`), where Enter flips an on/off setting or asks for a whole number inside the
487
- setting's range, and Esc returns to the list. Settings are saved with `plugins.configure` and read
488
- when the plugin next uses them, so they need no restart. The standalone
692
+ The command registry supplies help and slash completion for Harness commands, loaded extensions
693
+ and prompts. `/session` selects a saved session (`/resume` remains an alias), and `/history` navigates
694
+ branches in the current session (`/tree` remains an alias). `/btw <question>` asks a side question;
695
+ `/side` is its alias. Help and the slash-command palette show each pair once, as `/session (resume)`,
696
+ `/history (tree)` and `/btw (side)`; aliases still match palette searches.
697
+ With no path argument, `/session` opens a full-screen searchable page. Each unnumbered row shows a
698
+ normal-color title and a muted second line with relative activity time, `<project>:<branch>` and JSONL
699
+ file size separated by ` · `. One blank line separates each session. Enter resumes the selected
700
+ session; account and folder scope checks
701
+ remain enforced. Supplying an explicit path continues directly without opening the picker.
702
+ The separate `$` palette completes enabled skill invocations; `/skills` always browses skills. `/help`
703
+ renders the command list as one transcript entry, grouped under Core, Run, Model, Session, Inspect,
704
+ Harness, Plugins and Prompts; command names and descriptions wrap in aligned columns, with no
705
+ blank rows between choices. `/plugins` opens the browser with protected code trust and plugin settings actions. Settings use
706
+ `plugins.configure`; on/off settings and bounded whole-number settings keep their existing ranges.
707
+ Saved settings are read when the plugin next uses them and do not require a restart. The standalone
489
708
  terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/share`, `/scoped-mode` or
490
- `/import` commands. `/btw <question>` asks a short side question in a separate tool-free session. Its block puts the question after `/btw`, shows the normal animated spinner while answering, and separates the answer and hint by one blank row; it has no status labels. Escape closes the block without interrupting the main reply, and `/btw` also dismisses it. `/stop` interrupts the current reply. The `/accounts` page handles sign-in
709
+ `/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
710
+ main run's effective instructions, visible conversation and redacted public tool inputs/results.
711
+ Hidden reasoning and image bytes are excluded; the side run has no tools. Its block puts the
712
+ question after `/btw`, shows the normal animated spinner while answering, and separates the answer
713
+ and hint by one blank row; it has no status labels. PageUp/PageDown browse a long answer and Ctrl+X
714
+ copies the full answer. Escape or either command with no question dismisses the dock and interrupts
715
+ only that side run; the main reply continues. `/stop` interrupts the current main reply. The `/accounts` page handles sign-in
491
716
  and sign-out. `/components` browses reusable skills, prompts and rules; a confirmed skill or rule addition
492
717
  creates a variant version for future sessions while the current terminal keeps its pinned version. `/reload` applies trusted resource and keybinding changes.
493
718
 
494
719
  `/trajectory` opens the newest recorded run for the current native conversation; `/trajectory <run-id>`
495
- opens a selected run from that conversation. Tab switches between Runs and Events; `[` and `]` change
496
- runs, up/down selects recorded events, PageUp/PageDown scrolls event details, and `c` copies the
497
- selected event. Active runs refresh while the overlay is open. The protected terminal socket scopes both the run list and event
498
- reads to the current terminal and native session file.
720
+ opens a selected run from that conversation. The full-screen page keeps searchable Runs and Events
721
+ tabs. In Events, the list sits beside the selected event's JSON on wide terminals and stacks above it
722
+ on compact terminals. Type to search run IDs, goals, event types, timestamps, summaries and payload
723
+ text; `[` and `]` change runs, up/down selects events, PageUp/PageDown scrolls event details, and
724
+ `Shift+C` copies the selected event JSON. Active runs refresh while the page is open. The protected
725
+ terminal socket scopes both the run list and event reads to the current terminal and native session file.
499
726
 
500
727
  `/log` opens a centered page dialog with separate Harness diagnostics and current-conversation
501
728
  run-event views. The diagnostic file is read at its captured size in bounded socket chunks. Tab/Shift+Tab
@@ -504,6 +731,21 @@ diagnostics retain available error stacks and safe request metadata, while the v
504
731
  and URL queries and omits response bodies, prompts and message contents. Embedded hosts without a
505
732
  `harness.log` still show the conversation's recorded run events.
506
733
 
734
+ ## Slash command ownership
735
+
736
+ Harness core commands are unprefixed and live in the core terminal command registry, independently
737
+ of feature-plugin command metadata: `/doctor`, `/worktree`, `/trajectory`, `/subagents`, and `/agents`.
738
+ `/history` (also `/tree`) continues to navigate session branches. `/mcp` and `/connections` open the
739
+ Connections browser. Feature descriptors and their services remain registered; only these terminal
740
+ routes move out of the plugin command registry. Other plugin-owned commands continue to use
741
+ `/<owner-prefix>:<command>`. The annotations plugin uses `/annotate:annotate` and `/annotate:notes`;
742
+ `/annotate:` opens its default capture pane. Pi package extensions use their normalized package name
743
+ as owner prefix unless `harness.commandPrefix` overrides it; loose extensions use their normalized
744
+ extension name. A plugin prefix collision or a duplicate command within one owner is rejected with
745
+ owner paths in the diagnostic. The former owner-qualified and `/plugin:<command>` routes of promoted
746
+ Harness commands remain hidden compatibility aliases for one release, omitted from help and
747
+ completion. Prompt templates and `/skill:<name>` keep their existing forms.
748
+
507
749
  ## Input performance profile
508
750
 
509
751
  `npm run profile:terminal-latency` (`scripts/profile-terminal-latency.py`) types into the real
@@ -529,8 +771,8 @@ How the frontend keeps typing fast:
529
771
  results change; session statistics refresh at most every 250 ms during a run.
530
772
  - **Kept connections.** Session-socket requests ask to `keep` their connection, so the two 100 ms
531
773
  polls and per-key draft updates reuse a connection instead of opening one each.
532
- - **No swallowed keys.** A character the question dock does not use moves focus to the composer and
533
- is typed there.
774
+ - **No swallowed keys.** While a question is active, an unused printable character moves focus to
775
+ “Something else” and is typed there when free text is allowed; it never creates a hidden chat draft.
534
776
 
535
777
  ## Verification and remaining limits
536
778
 
@@ -665,7 +907,38 @@ truncate trailing text. Renaming refreshes the line through Pi's existing metada
665
907
  ## `/doctor`
666
908
 
667
909
  Checks accounts/models, tools, MCP, plugins/skills, variant/prompt validity, runtime assets, storage
668
- and startup recovery. Every finding says whether it is local readiness or live verification.
669
- `r` refreshes, `t` retries one local finding, `l` selects live checks, `c` cancels, arrows scroll,
670
- and Escape closes/cancels. Live checks show their costs and isolated resources before confirmation.
671
- Providers without diagnostic callbacks are reported unverified. See [Doctor](doctor.md).
910
+ and startup recovery. The summary keeps mode, progress, account/model and status counts visible above
911
+ the findings. Wide layouts use aligned Status, Check, Category and Verification columns, with evidence
912
+ and any next step beneath each finding; narrow layouts stack those fields. Status colors follow the
913
+ active theme: pass is success, warning/blocked warning, fail error, disabled dim and unverified muted.
914
+
915
+ `r` refreshes, `t` retries one local finding, `l` selects live checks, `c` cancels, Up/Down scroll by
916
+ line, PgUp/PgDn or the mouse wheel by page, and Home/End jump to the first/last finding. Escape
917
+ closes/cancels. Live
918
+ checks show their costs and isolated resources before confirmation. Providers without diagnostic
919
+ callbacks are reported unverified. See [Doctor](doctor.md).
920
+
921
+ ## Resource browser verification (2026-10-22)
922
+
923
+ The [retained evidence](evidence/terminal-resource-browser/README.md) records three-size PTY
924
+ acceptance, pointer/filter and resize behavior, skill completion/insertion and preserved drafts,
925
+ with zero model requests. Isolated idle/history/stream input profiling reported no missed keys
926
+ and p95 14.81/14.27/17.32 ms. The manifest binds both the CLI and OpenTUI bundle to their digests.
927
+ Live external connector authentication and community package installation were not exercised.
928
+
929
+
930
+ ## Full-screen browser verification (2026-10-23)
931
+
932
+ [PROP-0014](architecture/proposals/PROP-0014-fullscreen-browser-tabs.md) and
933
+ [ADR-0016](decisions/ADR-0016-fullscreen-browser-tabs.md) replace the browser's centered layout
934
+ with full-screen section tabs and a responsive inventory/inspector. The
935
+ [retained PTY evidence](evidence/terminal-fullscreen-browser/README.md) covers 40×20, 80×24 and
936
+ 120×40, keyboard and pointer tab selection, filter interaction, resizing and draft preservation,
937
+ with zero model requests. The manifest binds the CLI, OpenTUI bundle and verification script.
938
+
939
+ Harness typecheck, full tests (893 passing, three platform skips), build and standalone proof
940
+ passed. The final focused browser/page/command run passed 75 tests. Agent app typecheck, layer
941
+ checks, frontend tests, all 40 sidecar tests and 240 Rust tests passed (one Rust test ignored).
942
+ Sidecar tests were rerun with two workers and a 30-second timeout after four five-second timeouts
943
+ under concurrent load. Socket-backed Harness and PTY checks required sandbox escalation;
944
+ verification used local fixtures and disposable session data.