@firstpick/pi-package-webui 0.11.1 → 0.11.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 (309) hide show
  1. package/DEVELOPMENT.md +151 -12
  2. package/README.md +34 -6
  3. package/TECHNICAL.md +75 -8
  4. package/bin/pi-webui.mjs +5390 -11423
  5. package/index.ts +10 -3
  6. package/lib/component-update-state.mjs +2 -2
  7. package/lib/git-workflow-preference-values.mjs +122 -0
  8. package/lib/git-workflow-preferences.mjs +35 -563
  9. package/lib/package-updates.mjs +260 -0
  10. package/lib/rpc-supervisor-client.mjs +8 -4
  11. package/lib/server/app-runners.mjs +1667 -0
  12. package/lib/server/codex-fast-mode.mjs +161 -0
  13. package/lib/server/conversation-mode.mjs +218 -0
  14. package/lib/server/conversation-voice.mjs +318 -0
  15. package/lib/server/extension-ui-requests.mjs +114 -0
  16. package/lib/server/git-generation.mjs +459 -0
  17. package/lib/server/git-mutations.mjs +1827 -0
  18. package/lib/server/git-reads.mjs +608 -0
  19. package/lib/server/git-worktree-sessions.mjs +408 -0
  20. package/lib/server/helper-requests.mjs +82 -0
  21. package/lib/server/no-project-workspaces.mjs +103 -0
  22. package/lib/server/rpc-transports.mjs +394 -0
  23. package/lib/server/settings-store.mjs +544 -0
  24. package/lib/server/sse-delivery.mjs +138 -0
  25. package/lib/server/workspace-files.mjs +563 -0
  26. package/lib/update/supervisor.mjs +4 -0
  27. package/lib/webui-workspaces.mjs +2 -0
  28. package/package.json +4 -4
  29. package/public/activity-agents-controller.mjs +269 -0
  30. package/public/activity-events-controller.mjs +236 -0
  31. package/public/activity-intercom-controller.mjs +627 -0
  32. package/public/activity-queue-controller.mjs +534 -0
  33. package/public/activity-todo-view.mjs +89 -0
  34. package/public/activity-usage-controller.mjs +589 -0
  35. package/public/app.js +3761 -3886
  36. package/public/conversation-overview.css +84 -0
  37. package/public/conversation-overview.mjs +193 -0
  38. package/public/draft-conversations.mjs +135 -0
  39. package/public/focused-composer-controls.css +111 -0
  40. package/public/focused-composer-controls.mjs +143 -0
  41. package/public/focused-composer-disclosure.mjs +223 -0
  42. package/public/focused-shell-adapter.css +264 -0
  43. package/public/focused-shell-adapter.mjs +257 -0
  44. package/public/index.html +137 -80
  45. package/public/model-catalog-order.mjs +63 -0
  46. package/public/platform-event-stream.mjs +64 -0
  47. package/public/project-artifact-controller.mjs +218 -0
  48. package/public/project-file-viewer-controller.mjs +383 -0
  49. package/public/project-git-tools-controller.mjs +181 -0
  50. package/public/project-runners-controller.mjs +220 -0
  51. package/public/service-worker.js +52 -1
  52. package/public/session-attention-scheduler.mjs +182 -0
  53. package/public/session-composer-store.mjs +56 -0
  54. package/public/session-context.mjs +51 -0
  55. package/public/session-extension-requests.mjs +63 -0
  56. package/public/session-shelf-state.mjs +151 -0
  57. package/public/session-shelves.css +171 -0
  58. package/public/session-shelves.mjs +95 -0
  59. package/public/settings-navigation-controller.mjs +249 -0
  60. package/public/settings-navigation.css +61 -0
  61. package/public/settings-resource-controller.mjs +232 -0
  62. package/public/settings-workspace.css +19 -0
  63. package/public/settings-workspace.mjs +175 -0
  64. package/public/shell-actions.mjs +87 -0
  65. package/public/shell-attention-inbox.css +72 -0
  66. package/public/shell-attention-inbox.mjs +198 -0
  67. package/public/shell-context-actions.css +61 -0
  68. package/public/shell-context-actions.mjs +168 -0
  69. package/public/shell-inspector-resize.mjs +124 -0
  70. package/public/shell-navigation-resize.mjs +107 -0
  71. package/public/shell-navigation.mjs +127 -0
  72. package/public/shell-preferences.mjs +108 -0
  73. package/public/shell-surfaces.mjs +99 -0
  74. package/public/shell-tools-launcher.css +97 -0
  75. package/public/shell-tools-launcher.mjs +222 -0
  76. package/public/shell-view-host.mjs +115 -0
  77. package/public/shell-workspace.css +266 -0
  78. package/public/shell-workspace.mjs +402 -0
  79. package/public/sidebar-update-menu.css +190 -0
  80. package/public/sidebar-update-menu.mjs +512 -0
  81. package/public/styles.css +320 -169
  82. package/public/subagent-launch-slot-state.mjs +2 -2
  83. package/public/themed-selects.css +156 -0
  84. package/public/workspace-choices.mjs +104 -0
  85. package/tests/activity-agents-controller.test.mjs +652 -0
  86. package/tests/activity-events-controller.test.mjs +511 -0
  87. package/tests/app-runner-terminal-static.test.mjs +3 -3
  88. package/tests/append-system-http.test.mjs +7 -6
  89. package/tests/append-system-selector-static.test.mjs +6 -6
  90. package/tests/aur-review-widget-static.test.mjs +11 -3
  91. package/tests/boot-failure-diagnostics.test.mjs +8 -3
  92. package/tests/browser/activity-intercom-controller.spec.mjs +457 -0
  93. package/tests/browser/activity-navigation-integration.spec.mjs +45 -0
  94. package/tests/browser/activity-owner-integration.spec.mjs +201 -0
  95. package/tests/browser/activity-queue-controller.spec.mjs +405 -0
  96. package/tests/browser/activity-section-picker.spec.mjs +294 -0
  97. package/tests/browser/activity-todo-view.spec.mjs +60 -0
  98. package/tests/browser/activity-usage-controller.spec.mjs +416 -0
  99. package/tests/browser/compact-layout-integration.spec.mjs +58 -0
  100. package/tests/browser/composer-action-grid-reorder.spec.mjs +16 -0
  101. package/tests/browser/composer-disclosure.spec.mjs +389 -0
  102. package/tests/browser/composer-toolbar-polish.spec.mjs +343 -0
  103. package/tests/browser/control-deck-component-updates.spec.mjs +5 -14
  104. package/tests/browser/control-deck-side-panels.spec.mjs +27 -12
  105. package/tests/browser/control-visibility.spec.mjs +5 -0
  106. package/tests/browser/controls-layout.spec.mjs +21 -2
  107. package/tests/browser/conversation-overview.spec.mjs +251 -0
  108. package/tests/browser/draft-conversations.spec.mjs +276 -0
  109. package/tests/browser/empty-startup-fixture.mjs +135 -0
  110. package/tests/browser/empty-startup.spec.mjs +282 -0
  111. package/tests/browser/events-tree-context-menu.spec.mjs +1 -0
  112. package/tests/browser/focused-composer-more.spec.mjs +127 -0
  113. package/tests/browser/focused-model-shortcuts.spec.mjs +120 -0
  114. package/tests/browser/focused-navigation-fixture.mjs +32 -0
  115. package/tests/browser/focused-project-activity.spec.mjs +111 -0
  116. package/tests/browser/focused-shell-integration.spec.mjs +208 -0
  117. package/tests/browser/folder-picker-layout-fixture.mjs +13 -0
  118. package/tests/browser/folder-picker-layout.spec.mjs +302 -0
  119. package/tests/browser/footer-model-advanced-layout.spec.mjs +27 -14
  120. package/tests/browser/git-setup-cancel.spec.mjs +251 -0
  121. package/tests/browser/guided-git-fallback.spec.mjs +40 -21
  122. package/tests/browser/inspector-header.spec.mjs +221 -0
  123. package/tests/browser/inspector-overview-integration.spec.mjs +104 -0
  124. package/tests/browser/inspector-resize.spec.mjs +227 -0
  125. package/tests/browser/inspector-topic-overflow.spec.mjs +56 -0
  126. package/tests/browser/interaction-action-discovery.spec.mjs +332 -0
  127. package/tests/browser/interaction-attention-inbox.spec.mjs +364 -0
  128. package/tests/browser/interaction-attention-integration.spec.mjs +53 -0
  129. package/tests/browser/interaction-composer-controls.spec.mjs +267 -0
  130. package/tests/browser/interaction-composer-integration.spec.mjs +175 -0
  131. package/tests/browser/interaction-continuity.spec.mjs +50 -26
  132. package/tests/browser/interaction-model-picker.spec.mjs +86 -0
  133. package/tests/browser/last-terminal-close.spec.mjs +280 -0
  134. package/tests/browser/mobile-foundation.spec.mjs +172 -20
  135. package/tests/browser/model-catalog-groups.spec.mjs +104 -0
  136. package/tests/browser/more-row-menus.spec.mjs +258 -0
  137. package/tests/browser/new-tab-hit-target.spec.mjs +228 -0
  138. package/tests/browser/no-project-conversation.spec.mjs +113 -0
  139. package/tests/browser/optimistic-prompt.spec.mjs +3 -0
  140. package/tests/browser/overhaul-w7-accessibility.spec.mjs +227 -0
  141. package/tests/browser/overhaul-w7-capabilities.spec.mjs +298 -0
  142. package/tests/browser/overhaul-w7-companions.spec.mjs +290 -0
  143. package/tests/browser/overhaul-w7-focus-repairs.spec.mjs +210 -0
  144. package/tests/browser/overhaul-w7-layout-repairs.spec.mjs +183 -0
  145. package/tests/browser/overhaul-w7-parent-repairs.spec.mjs +97 -0
  146. package/tests/browser/overhaul-w7-pwa.spec.mjs +247 -0
  147. package/tests/browser/overhaul-w7-responsive.spec.mjs +450 -0
  148. package/tests/browser/overhaul-w7-update.spec.mjs +215 -0
  149. package/tests/browser/overhaul-w7-zoom.spec.mjs +243 -0
  150. package/tests/browser/overview-agent-ownership.spec.mjs +45 -0
  151. package/tests/browser/persistent-ui-layout.spec.mjs +3 -0
  152. package/tests/browser/project-artifact-controller.spec.mjs +324 -0
  153. package/tests/browser/project-artifact-integration.spec.mjs +103 -0
  154. package/tests/browser/project-file-buffer-integration.spec.mjs +230 -0
  155. package/tests/browser/project-git-tools-integration.spec.mjs +369 -0
  156. package/tests/browser/session-fixture.mjs +118 -0
  157. package/tests/browser/session-ownership.spec.mjs +175 -0
  158. package/tests/browser/session-shelves-integration.spec.mjs +219 -0
  159. package/tests/browser/session-shelves.spec.mjs +340 -0
  160. package/tests/browser/session-sidebar-resize.spec.mjs +138 -0
  161. package/tests/browser/session-summary.spec.mjs +17 -12
  162. package/tests/browser/settings-complete-home.spec.mjs +463 -0
  163. package/tests/browser/settings-entrypoint.spec.mjs +104 -0
  164. package/tests/browser/settings-navigation-controller.spec.mjs +383 -0
  165. package/tests/browser/settings-navigation-integration.spec.mjs +348 -0
  166. package/tests/browser/settings-resource-lifetime.spec.mjs +349 -0
  167. package/tests/browser/settings-workspace-integration.spec.mjs +132 -0
  168. package/tests/browser/shell-ownership.spec.mjs +398 -0
  169. package/tests/browser/shell-rollout-fixture.mjs +259 -0
  170. package/tests/browser/shell-rollout.spec.mjs +357 -0
  171. package/tests/browser/shell-tools-launcher.spec.mjs +260 -0
  172. package/tests/browser/shell-workspace.spec.mjs +433 -0
  173. package/tests/browser/side-panel-section-reorder.spec.mjs +3 -1
  174. package/tests/browser/sidebar-floating-tooltips.spec.mjs +37 -0
  175. package/tests/browser/sidebar-update-integration.spec.mjs +277 -0
  176. package/tests/browser/sidebar-update-menu.spec.mjs +402 -0
  177. package/tests/browser/sidebar-update-progress.spec.mjs +472 -0
  178. package/tests/browser/stream-output-isolation.spec.mjs +6 -3
  179. package/tests/browser/themed-selects.spec.mjs +297 -0
  180. package/tests/browser/thread-start-flow.spec.mjs +481 -0
  181. package/tests/browser/ui-polish-activity-controls.spec.mjs +177 -0
  182. package/tests/browser/ui-polish-features.spec.mjs +85 -0
  183. package/tests/browser/ui-polish-file-header.spec.mjs +43 -0
  184. package/tests/browser/ui-polish-local-git.spec.mjs +183 -0
  185. package/tests/browser/ui-polish-mobile-recovery.spec.mjs +36 -0
  186. package/tests/browser/ui-polish-navigation.spec.mjs +127 -0
  187. package/tests/browser/ui-polish-session-actions.spec.mjs +282 -0
  188. package/tests/browser/user-noticeable-fixes.spec.mjs +10 -3
  189. package/tests/browser/windows-drive-parent.spec.mjs +4 -2
  190. package/tests/browser/workspace-draft-selection.spec.mjs +266 -0
  191. package/tests/codex-fast-mode-static.test.mjs +16 -11
  192. package/tests/codex-speed-mode-browser-state.test.mjs +6 -3
  193. package/tests/codex-usage-source.test.mjs +4 -3
  194. package/tests/component-update-api-static.test.mjs +2 -2
  195. package/tests/composer-action-grid-reorder-static.test.mjs +3 -3
  196. package/tests/control-deck-component-updates-static.test.mjs +9 -4
  197. package/tests/control-visibility-static.test.mjs +3 -3
  198. package/tests/controls-layout-static.test.mjs +5 -5
  199. package/tests/conversation-overview-adapter.test.mjs +100 -0
  200. package/tests/document-artifact-static.test.mjs +2 -1
  201. package/tests/draft-conversations.test.mjs +205 -0
  202. package/tests/empty-startup-launcher.test.mjs +197 -0
  203. package/tests/events-tree-context-menu-static.test.mjs +22 -18
  204. package/tests/fake-pi-session-ownership.test.mjs +302 -0
  205. package/tests/fast-mode-client-static.test.mjs +1 -1
  206. package/tests/feature-decision-output-popup-static.test.mjs +2 -2
  207. package/tests/feature-system-prompt-optional-feature-static.test.mjs +1 -1
  208. package/tests/file-viewer-image-static.test.mjs +15 -11
  209. package/tests/file-viewer-search-static.test.mjs +5 -5
  210. package/tests/fixtures/fake-pi.mjs +41 -9
  211. package/tests/footer-provider-usage-visual-static.test.mjs +7 -6
  212. package/tests/foreground-transcript-catch-up-static.test.mjs +7 -4
  213. package/tests/git-footer-context-menu-static.test.mjs +1 -1
  214. package/tests/git-panel-file-preview-static.test.mjs +41 -48
  215. package/tests/git-panel-live-updates-static.test.mjs +2 -1
  216. package/tests/git-workflow-dispatch.test.mjs +66 -0
  217. package/tests/git-workflow-preferences.test.mjs +9 -1
  218. package/tests/guided-git-activation-static.test.mjs +14 -11
  219. package/tests/guided-git-fallback-ui-static.test.mjs +8 -5
  220. package/tests/guided-git-message-reliability-static.test.mjs +10 -6
  221. package/tests/guided-git-publication-backend-static.test.mjs +16 -11
  222. package/tests/http-endpoints-harness.test.mjs +21 -9
  223. package/tests/interaction-state-stability-static.test.mjs +4 -3
  224. package/tests/intercom-conversation-viewer-static.test.mjs +29 -17
  225. package/tests/intercom-tag-layout-static.test.mjs +13 -12
  226. package/tests/intercom-tag-overflow-layout.test.mjs +11 -10
  227. package/tests/main-output-loading-static.test.mjs +4 -4
  228. package/tests/middle-button-drag-scroll-static.test.mjs +3 -3
  229. package/tests/mobile-compact-layout.test.mjs +2 -2
  230. package/tests/mobile-continuity-tablet-static.test.mjs +3 -3
  231. package/tests/mobile-foundation-static.test.mjs +10 -7
  232. package/tests/mobile-phone-experience-static.test.mjs +3 -2
  233. package/tests/mobile-static.test.mjs +173 -135
  234. package/tests/model-catalog-order.test.mjs +103 -0
  235. package/tests/native-parity.test.mjs +6 -4
  236. package/tests/native-session-choice-owner.test.mjs +102 -0
  237. package/tests/native-update-lifecycle.test.mjs +10 -5
  238. package/tests/no-project-http-harness.test.mjs +328 -0
  239. package/tests/no-project-navigation.test.mjs +54 -0
  240. package/tests/no-project-workspaces.test.mjs +77 -0
  241. package/tests/open-issue-wizard-static.test.mjs +1 -1
  242. package/tests/optional-feature-migration-frontend.test.mjs +4 -4
  243. package/tests/optional-feature-prompt-impact-static.test.mjs +3 -3
  244. package/tests/package-updates.test.mjs +630 -0
  245. package/tests/persistent-ui-layout-static.test.mjs +3 -3
  246. package/tests/platform-event-stream.test.mjs +253 -0
  247. package/tests/project-file-viewer-controller.test.mjs +652 -0
  248. package/tests/project-git-tools-adapter.test.mjs +103 -0
  249. package/tests/project-git-tools-controller.test.mjs +577 -0
  250. package/tests/project-runners-controller.test.mjs +453 -0
  251. package/tests/prompt-input-vertical-scroll-static.test.mjs +3 -3
  252. package/tests/prompt-routing-input-clear-static.test.mjs +2 -2
  253. package/tests/questionnaire-dialog.test.mjs +6 -6
  254. package/tests/queue-edit-reorder-static.test.mjs +48 -51
  255. package/tests/rpc-supervisor-host.test.mjs +4 -1
  256. package/tests/safety-guard-auto-review-static.test.mjs +1 -1
  257. package/tests/sampling-native-controls-user-flow.test.mjs +7 -1
  258. package/tests/server-app-runners.test.mjs +536 -0
  259. package/tests/server-codex-fast-mode.test.mjs +346 -0
  260. package/tests/server-conversation-mode.test.mjs +386 -0
  261. package/tests/server-conversation-voice.test.mjs +426 -0
  262. package/tests/server-extension-ui-requests.test.mjs +357 -0
  263. package/tests/server-git-generation.test.mjs +558 -0
  264. package/tests/server-git-mutations.test.mjs +729 -0
  265. package/tests/server-git-reads.test.mjs +381 -0
  266. package/tests/server-git-worktree-sessions.test.mjs +502 -0
  267. package/tests/server-helper-requests.test.mjs +364 -0
  268. package/tests/server-rpc-transports.test.mjs +553 -0
  269. package/tests/server-settings-store.test.mjs +132 -0
  270. package/tests/server-shell-rollout.test.mjs +478 -0
  271. package/tests/server-sse-delivery.test.mjs +410 -0
  272. package/tests/server-workspace-files.test.mjs +546 -0
  273. package/tests/session-attention-scheduler.test.mjs +514 -0
  274. package/tests/session-composer-store.test.mjs +153 -0
  275. package/tests/session-context.test.mjs +134 -0
  276. package/tests/session-extension-requests.test.mjs +193 -0
  277. package/tests/session-ownership-adapter.test.mjs +130 -0
  278. package/tests/session-sampling-ui-static.test.mjs +10 -4
  279. package/tests/session-send-lifetime.test.mjs +140 -0
  280. package/tests/session-shelf-state.test.mjs +348 -0
  281. package/tests/session-shelves-adapter.test.mjs +79 -0
  282. package/tests/session-summary-lifetime.test.mjs +54 -0
  283. package/tests/settings-resource-controller.test.mjs +548 -0
  284. package/tests/shell-action-adapter.test.mjs +169 -0
  285. package/tests/shell-actions.test.mjs +182 -0
  286. package/tests/shell-navigation.test.mjs +348 -0
  287. package/tests/shell-preferences.test.mjs +367 -0
  288. package/tests/side-panel-section-height-removal-static.test.mjs +3 -3
  289. package/tests/stream-output-isolation-static.test.mjs +1 -1
  290. package/tests/subagent-gate-visibility.test.mjs +1 -1
  291. package/tests/subagent-launch-slot-state.test.mjs +2 -2
  292. package/tests/subagent-launch-slots-static.test.mjs +1 -1
  293. package/tests/subagent-observability-static.test.mjs +2 -2
  294. package/tests/subagent-reliability-integration.test.mjs +13 -30
  295. package/tests/syntax-highlighting-static.test.mjs +3 -3
  296. package/tests/tab-close-continuity-static.test.mjs +1 -1
  297. package/tests/tab-metadata-ordering.test.mjs +99 -0
  298. package/tests/terminal-cwd-grouping-static.test.mjs +2 -2
  299. package/tests/terminal-tab-prompt-tooltip-static.test.mjs +2 -0
  300. package/tests/terminal-tab-workspace-static.test.mjs +5 -4
  301. package/tests/terminal-tabs-resize-static.test.mjs +1 -1
  302. package/tests/theme-customizer-static.test.mjs +1 -1
  303. package/tests/thread-display-title.test.mjs +44 -0
  304. package/tests/update-api-harness.test.mjs +15 -14
  305. package/tests/update-tab-restore-harness.test.mjs +3 -0
  306. package/tests/webui-settings-locking.test.mjs +2 -2
  307. package/tests/windows-drive-cwd-picker-static.test.mjs +7 -9
  308. package/tests/workspace-choices.test.mjs +114 -0
  309. package/tests/workspace-save-load-static.test.mjs +7 -4
package/DEVELOPMENT.md CHANGED
@@ -4,6 +4,72 @@ Contributor-only implementation, API, architecture, testing, and maintenance inf
4
4
 
5
5
  [Back to README](README.md) · [Advanced user technical reference](TECHNICAL.md)
6
6
 
7
+ ## Compact interaction controls
8
+
9
+ `focused-composer-controls.mjs` projects effective model/effort and busy submission state. `app.js` retains draft, attachment, request-ID and dispatch ownership. Busy normal submissions remain prompt requests with `streamingBehavior`; the UI does not replace that path with direct steer/follow-up calls. Classic controls remain in their original DOM homes.
10
+
11
+ `nativeSessionChoiceOwner` captures the session lifetime and native-dialog generation. It admits one request at a time and prevents late success/error handlers from changing a replacement session or dialog. Effort uses the server's pending-value response; model changes use the existing native RPC. These pickers do not persist global defaults.
12
+
13
+ `shell-context-actions.mjs` renders a bounded selection from the same records used by `shell-tools-launcher.mjs`. More actions changes the initial category without limiting full-catalog search. Native slash aliases share one focused entry, and old alias pins resolve to its canonical ID. Dispatch still recomputes target validity and availability.
14
+
15
+ `shell-attention-inbox.mjs` renders caller-owned snapshots without polling or changing seen state. The adapter moves canonical run controls into the foreground native dialog. The app validates the selected tab lifetime, folder and completion serial, then uses normal tab switching and blocking-request replay. It never constructs response payloads from metadata counts.
16
+
17
+ Run the `interaction-*` browser specs together with existing focused-shell, session-ownership, launcher and mobile coverage. `native-session-choice-owner.test.mjs` exercises deferred responses against the actual application function. Browser fixtures use disposable state and fake Pi; the busy-submission test records HTTP delivery metadata while holding a real fixture stream, because fake Pi does not implement upstream busy prompt delivery.
18
+
19
+ ## No Project lifecycle and compact layout
20
+
21
+ `draft-conversations.mjs` owns versioned browser-only records under `pi-webui-draft-conversations-v1`. `draft:` IDs never enter server tab catalogs, RPC, SSE or restore payloads. The store validates records, rejects oversized writes without truncating memory, and preserves unreadable storage unchanged. Opening No Project selects a client blank; leaving nonempty text saves an Inbox entry. First submission creates a real tab and retires only the captured draft identity, preserving later edits and navigation. Failed dispatch recovers text into that real session. Per-page activation prevents duplicate submissions; durable creation idempotency after a lost response and reload is not provided by the existing endpoint.
22
+
23
+ `POST /api/tabs` accepts `{workspaceKind:"no-project"}` without a client cwd or session selector. `lib/server/no-project-workspaces.mjs` allocates a private exclusive UUID directory under the resolved agent root's `webui/no-project`, validates its canonical identity, and filters inherited session-selection and initial-input arguments before launch. Tab metadata carries `workspaceKind` and `noProjectId` alongside the physical cwd. Supervisor metadata, private restart handoffs and saved workspaces preserve those fields. Resume retains the original directory. Missing or mismatched owned directories fail validation; closing a tab never deletes its directory.
24
+
25
+ For No Project tabs, `/api/new-session` and exact `/new` return `data.nextTabId`, the fresh `data.tab`, all `data.tabs`, and `data.sourceTab`. The outer response tab remains the source request context. The frontend adopts the new tab only while that originating context is current. The source process, session, draft and files remain intact. Normal project resets retain their existing behavior. Concurrent resets, active work, compaction and natural-conversation admission remain guarded. These directories isolate working files, not shell permissions.
26
+
27
+ `shell-inspector-resize.mjs` reports committed widths through the shell callback; the app persists the existing browser-local `inspectorWidth`. Effective viewport clamping does not overwrite the saved value. Cancellation restores the pre-drag width, including Escape after focus moves. `focused-composer-disclosure.mjs` positions the original More tray and Options menu without taking over dispatch or visibility. Tooltip portals keep invisible legacy pseudo-elements from extending the tray. The overview uses natural card height and a two-column layout where needed; constrained windows scroll the whole card host instead of clipping its content.
28
+
29
+ The compact application hides its duplicate model/effort strip and retains the busy submission selector. Footer controls and options have stable focus keys across footer replacement. The effort picker focuses its selected value before falling back to the first enabled option. Classic and mobile retain their established settings controls.
30
+
31
+ Verification lives in `no-project-workspaces.test.mjs`, `no-project-http-harness.test.mjs`, `update-tab-restore-harness.test.mjs`, and the No Project, compact-layout, composer-disclosure, More, footer and inspector-resize browser specs. All use disposable state and fake Pi; they do not establish real-provider or Windows filesystem parity.
32
+
33
+ ## Shell ownership
34
+
35
+ Classic and mobile adapters in `public/app.js` share five flat ES modules:
36
+
37
+ - `shell-actions.mjs` preserves palette matching and checks captured session/project targets before dispatch. Stable action IDs identify entries across catalog refreshes. The app rebuilds the catalog at execution. Captured session identity rejects same-tab replacements without changing stream ownership; successful New session replies invalidate actions before refreshed state arrives. Compact availability includes both authoritative busy state and locally pending requests. Existing handlers retain asynchronous guards and server authorization remains authoritative.
38
+ - `shell-navigation.mjs` owns the browser history listener and writes. Mobile navigation commits history before changing the rendered state, so a failed write leaves the current view intact. Unrelated history fields and URL parameters survive.
39
+ - `shell-preferences.mjs` reads the versioned browser preference without repairing unknown records. The pure effectiveShellPreferences resolver selects Focused only for an absent browser record and exact fresh server cohort; corrupt or unavailable storage stays Classic. Phone and tablet mode choices remain independent; `shell=classic` takes precedence. A valid explicit browser choice always wins, including when cohort metadata arrives after that choice. Pins use bounded printable catalog IDs; inspector navigation keeps its stricter ID grammar.
40
+ - `shell-view-host.mjs` moves canonical DOM nodes and restores their original homes, focus, selection and scroll. The app retains section visibility and disclosure attributes. Moving or restoring a view never owns its session, runner or stream lifetime.
41
+ - `shell-surfaces.mjs` owns one drawer keyboard listener and restores prior attributes. Native modal dialogs retain keyboard ownership. Replacing a drawer invalidates pending focus returns without closing feature resources.
42
+
43
+ The modules ship with the package and participate in the service-worker cache. Keep module imports, cache versions, browser entry URLs and pinned asset tests coherent. Node contracts cover action targets, preferences and history. `tests/browser/shell-ownership.spec.mjs` exercises real DOM ownership; `mobile-foundation.spec.mjs` checks app integration. These checks do not replace the overhaul plan's later parity and platform gates.
44
+
45
+ ## Compact desktop integration
46
+
47
+ Project and Activity are inspector destination tabs. `shell-workspace.mjs` keeps their section selector in the inspector header and exposes a conversation-local overview slot. `conversation-overview.mjs` only renders keyed snapshots; `app.js` reads existing owners, validates tab/session/folder identity and dispatches canonical catalog actions. It introduces no transport or polling owner. `overviewOpen` is an optional boolean browser preference; Home and Settings temporarily hide the card. Closing the card never stops feature resources.
48
+
49
+ `themed-selects.css` uses native customizable-select support behind a CSS feature query. Options, disabled states, optgroups and change events remain browser-owned. Unsupported engines retain a themed native control. Shared styled tooltips use a manual popover when supported so clipped containers and native dialogs cannot cover them; the existing fixed portal remains the fallback. The scoped model picker records whether its opener was the footer or composer and resolves the current button after footer rerenders.
50
+
51
+ `focused-shell-adapter.mjs` places canonical views in `shell-workspace.mjs` and restores them with the shared view host. It moves the existing model/effort rows, footer administration controls and Abort/End buttons; feature controllers retain request targets and resource lifetimes independently of view placement. The original Control Deck visibility and order are retained for Classic. Desktop preview preferences never write the durable layout schema.
52
+
53
+ `shell-tools-launcher.mjs` renders caller-supplied action records, categories and pins in a native dialog. The app rebuilds the catalog and rechecks captured session/project targets before execution. Native modal ownership remains with the browser. History writes precede view changes and preserve unrelated state and URL identity.
54
+
55
+ `tests/browser/focused-shell-integration.spec.mjs` uses the shared disposable `session-fixture.mjs` to exercise actual drafts, controls, history, rollback, responsive mode transitions and Abort inside the launcher. Worker component fixtures cover layout and keyboard contracts; they do not establish whole-app parity. New files ship as flat assets and participate in the PWA cache.
56
+
57
+ ### Session shelves
58
+
59
+ `session-shelf-state.mjs` owns bounded browser-local settlement and expansion under `pi-webui-session-shelves-v1`. The app supplies stable creation/session-file identity, completion serial, and activity with input taking priority over work. Complete metadata snapshots may prune closed IDs; rendering alone never prunes missing IDs. Reconciliation also runs outside the mounted sidebar. Settlement does not mark completion as seen or call any mutation route.
60
+
61
+ `session-shelves.mjs` owns stable headers and body slots. The app owns the rows and renders shelf-qualified group fragments while preserving canonical custom group IDs. Settle/Restore callbacks revalidate session lifetime and identity; group close uses only the fragment's tab IDs. The canonical tablist owns selection controls, separate from action buttons. Classic, top navigation, and mobile use the original list.
62
+
63
+ Run `node --test tests/session-shelf-state.test.mjs` and the Chromium `session-shelves.spec.mjs` and `session-shelves-integration.spec.mjs` scenarios for storage, activity wake, keyboard focus, draft continuity, grouped membership and layout fallback. All actual-app fixtures use fake Pi and isolated settings.
64
+
65
+ ## Settings ownership
66
+
67
+ `settings-workspace.mjs` places the original settings groups in categorized pages through `shell-view-host.mjs`. `settings-navigation-controller.mjs` owns only search, result presentation and keyboard navigation. The app remains the sole history writer and action dispatcher. Settings URLs use the existing `view=settings` and `inspector=settings:<category>` fields plus an optional stable `setting` anchor; invalid entries are dropped and unknown categories recover to Appearance without applying preferences. Existing Theme focus opens its searchable picker. Classic restores original groups and disclosure state.
68
+
69
+ `settings-resource-controller.mjs` owns tools/skills resources, scope and exact provider/model selection. The app supplies existing HTTP calls and captured tab, session lifetime and native-dialog generation guards. Reads and writes retain their original scope; detached controls and late completions cannot target a replacement. Empty enabled lists and inheritance remain distinct. Companion availability comes from the existing catalog and package state; the Settings search index adds placement metadata, not a second package policy.
70
+
71
+ The actual-app `settings-navigation-integration.spec.mjs` and `settings-resource-lifetime.spec.mjs` use disposable servers and test canonical controls, history, drafts, retained selections and deferred HTTP boundaries. The existing `resource-profiles.spec.mjs` complements those intercepted race cases with server persistence checks. The navigator’s component fixtures cover keyboard and accessibility semantics. New modules and styles are included in the package and offline cache.
72
+
7
73
  ## Pi 1.2 theme compatibility
8
74
 
9
75
  Bundled native theme JSON now uses `https://pi.dev/schemas/theme.schema.json`. Pi 1.2 rejects WebUI-only fields inside a native theme's `export` object at startup. The theme bundle publishes those fields separately in `webui-backgrounds.json`, outside its `pi.themes` directory. `readBundledThemes()` reads that optional file next to the themes directory and merges only `WEBUI_THEME_EXPORT_FIELDS` into catalog exports. Native export colors cannot be overridden by this metadata. Older bundles with inline background fields still load through the existing bundled-only compatibility path.
@@ -54,16 +120,43 @@ node tests/append-system-http.test.mjs
54
120
  node tests/append-system-selector-static.test.mjs
55
121
  ```
56
122
 
123
+ ## Shell rollout initialization
124
+
125
+ Immediately after CLI and startup-CWD validation, before service construction, registry initialization or restore reads, the server calls initializeWebuiShellRollout from the canonical settings store. Prior-use evidence includes the default settings root, legacy config root, XDG Web UI state, configured agent Web UI state and explicit fast-pick, optional-feature migration and restore paths. Only absence proven under the bounded sibling initialization lock can qualify a default root as fresh. Custom settings targets and ambiguous evidence cannot establish freshness. The existing settings lock and private atomic writer persist the raw-preserving version-1 shellRollout marker without changing settings schema 8, layout v3 or layout revisions. Generic settings reads never initialize the marker.
126
+
127
+ GET /api/interface-preferences adds only validated shellRolloutCohort metadata. The existing PUT allowlist rejects cohort and marker fields. Browser hydration is outside the layout revision/generation fences and performs no preference write; the original read status remains separate from the effective layout. Late metadata cannot override an explicit choice. Existing startup migration of missing durable layout fields remains independent. Recovery URLs and independent mobile modes retain precedence.
128
+
129
+ The initializer preserves valid markers, leaves invalid/future own markers untouched, migrates applicable legacy data before any marker-only write, and returns unknown after failed proof or persistence. A crash after root creation leaves conservative established state on the next startup. Unit fault/race tests live in server-shell-rollout.test.mjs; whole-app startup, browser hydration and platform acceptance remain separate gates.
130
+
57
131
  ## Web UI settings write lock
58
132
 
133
+ `lib/server/settings-store.mjs` owns generic normalization, migration, locking and atomic persistence. `lib/git-workflow-preference-values.mjs` owns pure Git preference values. The former `lib/git-workflow-preferences.mjs` path retains its Git read/write wrappers and re-exports the same store bindings, so mixed imports share one update queue. The server imports generic settings directly from the store. Storage paths, schema 8 and layout v3 remain unchanged.
134
+
59
135
  `updateWebuiSettings` serializes same-process updates and uses per-writer records under `<settings-file>.lock` for cross-process writes. A process can exit after creating its record but before writing valid JSON, leaving an empty file. Lock acquisition removes incomplete records immediately when their PID is dead. It gives a live writer a one-second grace period, then removes records that are still empty or malformed so one interrupted write cannot block every later settings save.
60
136
 
61
137
  Focused contributor validation:
62
138
 
63
139
  ```bash
140
+ node tests/server-settings-store.test.mjs
64
141
  node tests/webui-settings-locking.test.mjs
65
142
  ```
66
143
 
144
+ ## Backend service ownership
145
+
146
+ `lib/server/workspace-files.mjs` owns workspace containment, tree/search limits, file reads and mutations, strict AUR report reads, and editor selection. The entrypoint retains route authorization, body limits, requested-tab selection and error envelopes. A single factory receives the validated default directory and shared Git read functions.
147
+
148
+ `lib/server/git-reads.mjs` owns bounded Git reads, porcelain parsing, change/commit payloads and Files status/ignore decorations. Its read commands preserve optional-lock suppression and output bounds; mutations and watcher ownership remain separate. Both services retain their previous payloads and error behavior. Focused contracts live in `server-workspace-files.test.mjs` and `server-git-reads.test.mjs`; the HTTP harness and Project browser scenarios verify their integration.
149
+
150
+ `lib/server/app-runners.mjs` owns runner detection, configuration, process execution, stdin, output and context transfer. Its one service instance keeps caches while each real tab retains its run record and timers. HTTP guards and tab/working-directory/shutdown call sites remain in the entrypoint. The service uses the existing process-tree and terminal-reducer modules; hiding a view does not stop a runner. `server-app-runners.test.mjs` covers disposable processes, and `app-runner-process-tree-harness.test.mjs` checks lifecycle integration.
151
+
152
+ `lib/server/git-mutations.mjs` owns staged-content approval hashing, Git/gh command serialization and mutation payloads. `git-worktree-sessions.mjs` owns worktree/session handoffs, staged transfer and live-tab removal refusals. `git-generation.mjs` owns generation reservations, artifact readiness, fallback settlement and replay. The entrypoint awaits each extracted workflow mutation inside its existing error-envelope boundary. Both generation and command cancellation run before their results are combined. The original tab records and explicit RPC event order remain authoritative.
153
+
154
+ `conversation-mode.mjs`, `conversation-voice.mjs` and `codex-fast-mode.mjs` adapt the existing companion command/status contracts. The server retains route authentication, originating-tab selection and body limits. Voice keeps consent checks, provider bounds and command-only shared Piper configuration writes; speed changes require the extension's confirmed status.
155
+
156
+ `rpc-transports.mjs` supplies one stable direct/supervised class pair. `sse-delivery.mjs` owns bounded writes, backpressure and output-mode barriers on the original client records. `helper-requests.mjs` owns correlated helper acknowledgments on real tab maps, and `extension-ui-requests.mjs` owns blocking approval tracking/replay/cancellation with original request IDs. Factories create no processes or listeners until used. Supervisor discovery, replay reconciliation, update admission, shutdown policy, HTTP routing and the explicit event pipeline remain in their existing owners. The upstream helper's resource/subagent hooks are unchanged.
157
+
158
+ The `server-*.test.mjs` suites verify these service contracts. `git-workflow-dispatch.test.mjs` covers asynchronous mutation error envelopes and cancellation ordering. The HTTP, staged-content, durable-supervisor, transport-hardening and SSE-backpressure harnesses verify the composed server. Extraction changes no storage path, wire protocol or browser asset revision.
159
+
67
160
  ## File viewer image contract
68
161
 
69
162
  `GET /api/files/content` keeps workspace-path confinement and the shared 2 MiB `FILE_VIEWER_MAX_BYTES` cap before reading either text or images. Text responses use `kind: "text"` with UTF-8 `content` and `language`. The explicit extension allowlist maps `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, and `.avif` to fixed MIME types; those responses use `kind: "image"`, `mimeType`, and base64 `data` without decoding the bytes as UTF-8. SVG and all unlisted binary formats continue to return `415` through the text/binary guard.
@@ -178,13 +271,23 @@ The separate `WS3 paced cadence and slow-renderer queue pressure remain bounded`
178
271
 
179
272
  `tests/stream-markdown-tail.test.mjs` reference semantics are the authoritative specification of the streaming boundary behavior going forward, anchored by the browser exact-output hash gate.
180
273
 
274
+ ## Project and Activity ownership
275
+
276
+ The app composes flat native modules around the existing HTTP/SSE contracts. Project controllers own file buffers and guarded requests (`project-file-viewer-controller.mjs`), Git tool cache and mutations (`project-git-tools-controller.mjs`), runner data and stdin drafts (`project-runners-controller.mjs`), and the canonical document viewer (`project-artifact-controller.mjs`). Targets capture tab ID, session lifetime and working directory before asynchronous work. Navigation never owns process shutdown.
277
+
278
+ Activity modules own queue presentation and mutation tokens, Agents overview/polling/cancellation selection, Intercom summaries/detail, Events history/filter/unread state, and provider usage refresh/render timers. The queue snapshot cache remains in the app; its controller reads and writes through callbacks. The todo view is a pure parser/renderer with expansion stored by the parent. Agent terminal projections and explicit cancellation remain separate owners.
279
+
280
+ Focused widget placement moves original nodes to their domain host. Hidden heavy widgets retain their nodes and state without full reconstruction; revealing a topic renders current data. Classic restoration rebuilds all applicable widgets at their original home. Lightweight runner output patches may update retained nodes while hidden. Provider visibility suppresses DOM ticks without changing refresh ownership.
281
+
282
+ Actual-app scenarios in `activity-owner-integration.spec.mjs`, `focused-project-activity.spec.mjs`, and the Project integration specs cover canonical navigation, dirty buffers, original request identities, queue mutations, runner continuity and explicit agent cancellation. Controller fixtures cover stale completions, conflict snapshots, disposal and locks. Source-shape tests follow extracted owners rather than retaining duplicate implementations in the app.
283
+
181
284
  ## Intercom conversation projection and viewer
182
285
 
183
286
  `GET /api/intercom/conversations?tab=<tab-id>` projects bounded summaries from `SessionManager.getBranch()` for the selected server-owned session. Adding `conversation=<opaque-id>` returns one sanitized detail. Browser values never select a session path. The pure projector in `lib/intercom-conversations.mjs` accepts only structured generic Intercom records and matched native supervisor request/reply records, deduplicates protocol identities, excludes synthetic relays and attachments, and applies conversation/message/text/response bounds before serialization.
184
287
 
185
288
  `lib/intercom-transcript-filter.mjs` is the separate normal-transcript boundary. Before HTTP delta slicing, it removes structured `intercom_message` records, generic `intercom` tool-call parts, and results paired by explicit call ID or tool name. It copies only changed mixed assistant records and preserves unrelated meaningful content without mutating the RPC response. Live stream and execution guards in `public/app.js` prevent an Intercom card or event-log line from flashing before the filtered authoritative refresh; unrelated supervisor and tool activity keeps the existing path. The conversation endpoint still reads raw active-branch records independently.
186
289
 
187
- `public/app.js` keeps only in-memory per-tab summaries. `refreshIntercomConversationSummaries` uses tab-generation and request-serial guards; `refreshIntercomConversationDetail` adds a separate serial plus a five-second open-dialog refresh. Switching tabs or closing the native dialog invalidates pending detail responses and cancels its timer. The renderer rebuilds message bubbles only from normalized `direction`, participant name/ID, text, and timestamp fields, assigning text with safe DOM APIs. It never renders server records wholesale. The footer tag group uses a reversed inline strip capped at 50 percent of the desktop prompt row, so the newest conversation starts at the right edge and older tags extend toward the middle. Direct tags are capped at 13rem. A `ResizeObserver` measures complete tag widths and reserves space for `+X`; tags that do not fit move into a bounded popup above the composer. Narrow layouts give the strip the full row and keep 44-pixel targets in the popup. Escape, outside clicks, and focus changes close the popup. Each reused direct or popup button stores a compact label/count signature, so unchanged tags retain their children instead of retriggering the polite live region.
290
+ `public/activity-intercom-controller.mjs` owns in-memory per-tab summaries and the single detail selection. Summary requests use captured tab generation and session lifetime; detail requests add a separate serial plus a five-second open-dialog refresh. Activity Conversations and the composer tags open the same native dialog. Switching tabs or closing the native dialog invalidates pending detail responses and cancels its timer. The renderer rebuilds message bubbles only from normalized `direction`, participant name/ID, text, and timestamp fields, assigning text with safe DOM APIs. It never renders server records wholesale. The footer tag group uses a reversed inline strip capped at 50 percent of the desktop prompt row, so the newest conversation starts at the right edge and older tags extend toward the middle. Direct tags are capped at 13rem. A `ResizeObserver` measures complete tag widths and reserves space for `+X`; tags that do not fit move into a bounded popup above the composer. Narrow layouts give the strip the full row and keep 44-pixel targets in the popup. Escape, outside clicks, and focus changes close the popup. Each reused direct or popup button stores a compact label/count signature, so unchanged tags retain their children instead of retriggering the polite live region.
188
291
 
189
292
  ### Tagged local-model thinking
190
293
 
@@ -293,7 +396,7 @@ Run focused validation with `node --check public/app.js`, the static tests above
293
396
 
294
397
  The native update API has two single-target planning requests, `{ "targets": ["pi"] }` and `{ "targets": ["webui"] }`. `POST /api/update/plan` returns an immutable plan with `transactionId`, `digest`, `requested`, `active`, `pathPi`, `context`, `targets`, `refusals` and `warning`. `pathPi` records the independently proven PATH driver's version, package root, executable and CLI, or eligibility/guidance when unproven. Each target carries `id`, `installedRoot`, `effectRoot`, `beforeVersion`, and an absolute `command` with argument array. `POST /api/update/apply` accepts only `{ transactionId, planDigest }` and returns `202` with a running job ID. It revalidates the bound context before launch. No release version or command originates in the browser. `GET /api/update/transactions/<id>` returns phase, bounded per-command receipts, verified targets, outcome and error; a missing completion receipt cannot establish success. A shared private state root fences affected work across server processes. The detached runner writes per-command receipts after native child close, and finalization selectively restarts only verified healthy changed active components after idle. Neither process exit alone nor an exit code alone certifies a healthy installation.
295
398
  The authenticated `GET /api/interface-preferences` response includes normalized `preferences`, versioned `layout`, and an opaque `layoutRevision`. `PUT /api/interface-preferences` remains compatible with width-only `{ "sidePanelWidth": 612 }` writes. Layout patches require the latest revision in `expectedLayoutRevision`, merge only named fields, and are limited to 32 KiB; stale revisions return `409`, unsupported media types `415`, oversized bodies `413`, and invalid or unknown fields `400`. Schema v3 adds `controlVisibility.hiddenIds`: `null` means package defaults, `[]` means explicit show-all, and a bounded sorted string list stores hidden stable catalog IDs while retaining unknown future IDs. The browser applies those IDs through a preference-only CSS class and never mutates capability-owned `hidden` state. The `terminalTabs` layout record owns tab placement, custom groups, and the bounded desktop `sidebarWidth`; the client journals those subfields independently so resizing cannot overwrite concurrent group or placement changes. Browser local storage remains a non-destructive compatibility cache. Semantic file moves, prompt attachments, and follow-up queue mutations are not stored in the interface-layout envelope.
296
- Pi Web UI normally runs Pi RPC tabs under a narrow detached supervisor. Restarting only the HTTP Web UI—through `/webui-start` on the same URL, **Restart**, a verified native update of an affected active component, `POST /api/restart`, or a restart-safe service-manager `SIGTERM`—preserves each managed Pi PID, tab identity, cwd, session file, running state, and active model turn. Output produced while the HTTP server is absent is replayed in supervisor order. The browser rejects duplicate or older replay records; if the bounded live buffer has a gap, it refreshes tabs, state, and the durable transcript from Pi and warns that buffered live output may be incomplete.
399
+ Pi Web UI normally runs Pi RPC tabs under a narrow detached supervisor. Restarting only the HTTP Web UI—through `/webui-start` on the same URL, **Restart**, `POST /api/restart`, or a restart-safe service-manager `SIGTERM`—preserves each managed Pi PID, tab identity, cwd, session file, running state, and active model turn. Output produced while the HTTP server is absent is replayed in supervisor order. The browser rejects duplicate or older replay records; if the bounded live buffer has a gap, it refreshes tabs, state, and the durable transcript from Pi and warns that buffered live output may be incomplete.
297
400
  - Use `/webui-status detailed`, `GET /api/health`, or `GET /api/webui-status?detailed=1` for diagnostics. Public supervisor diagnostics are limited to enabled/attached state and managed-tab count; private credentials and paths are intentionally omitted. A browser warning about incomplete buffered output means authoritative tabs/state/messages were requested, not that missing live deltas were reconstructed.
298
401
  - Use the side-panel **Stop** action or localhost-only `POST /api/shutdown` for an explicit full stop. Explicit tab close terminates only that managed Pi child; explicit shutdown and `SIGINT` terminate the scope's managed Pi children. Do not use restart/update when the intent is to terminate active work.
299
402
  - Normal authenticated shutdown removes the private scope state. Do not manually delete runtime files, sockets, pipes, journals, or PID records while managed tabs may be live. For cleanup, explicitly shut down first, verify the Web UI/scope has no managed tabs, and let normal startup clean stale empty state; removing private state for a live supervisor destroys the safe attachment path and can risk duplicate processes.
@@ -305,7 +408,7 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
305
408
  - `PI_VOICE_TTS_PROVIDER=openai` selects hosted OpenAI TTS when no request provider is supplied; set `OPENAI_API_KEY` server-side.
306
409
  - `PI_VOICE_GROQ_STT_MODEL`, `PI_VOICE_OPENAI_STT_MODEL`, `PI_VOICE_OPENAI_TTS_MODEL`, `PI_VOICE_OPENAI_TTS_VOICE`, `PI_VOICE_OPENAI_TTS_FORMAT`, `PI_VOICE_TTS_VOICE`, and `PI_VOICE_TTS_FORMAT` tune fallback models/voices/formats.
307
410
  - `PI_VOICE_PROVIDER_TIMEOUT_MS` controls outbound fallback-provider timeout. API keys are never sent from the browser; remote/LAN raw-audio STT uploads must include explicit per-request microphone-streaming consent.
308
- - Pathless `pi-webui` startup: the server opens first, then the browser prompts for the first terminal CWD.
411
+ - Default `pi-webui` and `/webui-start` startup: without explicit `--cwd`, managed tabs, or restore descriptors, the server starts with zero tabs and no Pi child. The browser shows an empty No Project conversation. Its first nonempty submission creates an owned No Project tab before dispatching the captured input. Explicit project startup and session restoration retain precedence.
309
412
  - Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, per-tab settings, and a workspace dashboard for common actions.
310
413
  - The Subagents side panel includes a separate **Agent models** editor above the live monitor. It stores WebUI-owned launch slots for the eight builtin roles (`context-builder`, `delegate`, `oracle`, `planner`, `researcher`, `reviewer`, `scout`, and `worker`): every role keeps a non-removable base slot, while added same-role slots copy a model/thinking draft but retain independent stable IDs. Choose **User default** or **This project**; projects inherit user defaults until saved, and **Use user defaults** removes a project override. Select `Default / inherit` to inherit both values, or an active-tab provider-qualified model and its supported thinking levels. Saves are revision-checked and localhost-only; the helper loads one immutable assignment snapshot after **Reload active tab**, never changes running children, and uses a `tool_call` hook to fill omitted model fields on `subagent` and `subagent_gate` launches. Explicit non-reviewer models remain unchanged; explicit reviewer mismatches block unless a matching bounded deviation permit is admitted. `workflowScript` receives an idempotent local `runs` adapter that applies role defaults and reviewer admission to `runs.run` and `runs.all` child params at execution time without parsing call sites. The configuration form has independent load/draft/error state, so its controls are not reset by live subagent monitoring.
311
414
  - Tracked subagent output can open in the existing non-blocking overlay/widget or in a dedicated **Subagent** terminal tab, selected from the Subagents side-panel section and saved in the browser. The side-panel monitor keeps each status dot, agent type, provider/model, thinking effort, and run action on one compact line; a model-less `pi-subagents` workflow controller becomes a collapsible run header with its child-agent rows nested beneath it and excluded from agent counts. Run IDs, source/mode, elapsed state, and current-tool details live in the selected output view instead of being duplicated inline. Subagent tabs are view-only, reuse the bounded live transcript at the normal full terminal width, show the pulsing **Agent is running:** card with current child activity, and close without stopping or interrupting the child run; use the parent terminal for interaction. Dedicated **Subagent** terminal tabs show exactly six telemetry cards: PI, measured token speed, context, model, effort, and input/output tokens from a bounded recent session scan; unavailable or legacy evidence remains `—` or `unknown` rather than an estimate. The package also registers a generic `subagent_gate` tool that launches task slots through pi-subagents RPC v1, enforces a required success quorum, and performs bounded reason-aware retries only when declared safe; the side panel retains gate quorum, attempt, provider, and failure-class history after children finish.
@@ -329,9 +432,9 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
329
432
  - Detected app runner dropdown for the active tab cwd, including Cargo, Bun, npm/npx/pnpm, Python/uv, Go/Golang, Zig, C/C++, Docker Compose, root/dev/scripts shell scripts, and other common project runners with live output pinned at the top of the terminal. Stream chunks pass through a terminal-line reducer: LF/CRLF commit scrollback, bare CR replaces the current live line, backspace edits that line, and ANSI sequences remain intact for the browser's safe SGR renderer. This is line-oriented terminal behavior rather than a full VT100 cursor grid. Running app runners expose line-oriented stdin in the widget for interactive scripts. Projects can add browseable custom runners in `.pi-webui-runners.json` with a command (default `./`) plus a relative path to the file to run. The same dialog also configures project discovery paths: project-relative directories that are scanned one level deep (no subdirectories) for `.sh`, `.bash`, `.zsh`, `.fish`, and `.py` files plus extensionless files with a bash/sh, zsh, fish, or Python shebang. Python candidates use `uv run` and/or the available `python3`/`python` interpreter. Discovered scripts extend the built-in root, `dev/`, `scripts/`, and `dev/scripts/` detection and run from the resolved project root.
330
433
  - Extension-launched Guided Git workflow for existing repos and new repos with persistent model/reasoning preferences, review-first staging, an optional manual staged repository-review gate from `aur-review`, generated or typed commit messages, explicit push/PR confirmation, and optional PR worktrees. `/git-guided-workflow` emits a transient tab-scoped activation request that the browser validates and consumes before generic status rendering; the browser requires the extension-owned native generation commands and has no prompt-only launch fallback. The HTTP server authoritatively rejects the exact command admission while the tab is streaming, compacting, has pending messages, or already has a pending Guided Git launch, bypassing generic compaction queueing. A browser-generated UUID is stored in one short-lived server record and added only to the trusted live event envelope; the canonical four-field extension payload remains unchanged, and only the browser holding the matching one-shot permit can consume the event. When the review extension is loaded/enabled, both `git add .` and accepting the current staged set send `/aur-review start --scope staged --origin guided-git` to the same tab. Only its matching approval advances to message generation. The browser and server recheck the approved domain-separated staged-content hash before message generation, commit, and PR-worktree transfer; drift, missing hashes, or hash-check errors return to Stage and require a new review. A decline returns to staging and rejects an unchanged declined staged hash until corrected content is restaged. Guided Git never stages, commits, or pushes remediation automatically. The extension remains the decision authority; direct API callers are not granted an approval by this browser workflow.
331
434
  - Browser support for Pi extension UI prompts, widgets, status updates, `/btw` side-question output widgets with optional context transfer/live steering, browser notifications when a tab needs an extension UI response, and an optional side-panel toggle for agent-done notifications.
332
- - Localhost-only separate Pi and Web UI native plans with digest-bound confirmation, fail-closed ownership checks, shared effect-root fencing, durable per-command receipts, partial/unknown results, and selective automatic restart after health verification. PATH Pi 0.87.1 is the initially proven command driver. Combined actions, optional-companion sweeps and managed-runtime activation are retired.
435
+ - Localhost-only update choices for Pi, WebUI, or Pi and extensions plus WebUI. Installation detection selects fixed commands; preview tokens bind confirmation to server-held commands. Results report command exits and request a manual restart.
333
436
  - Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
334
- - Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay for ordinary server restart. Native updates use an inline spinner and durable per-job status.
437
+ - Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay for ordinary server restart. Package updates show progress and command results for the lifetime of the server process.
335
438
  Web UI keeps a packaged parity matrix at `lib/WEBUI_TUI_NATIVE_PARITY.json` and exposes it at `GET /api/native-parity`.
336
439
  Discovery-path rules: at most 24 paths and direct children only (no recursive walk). Shell discovery supports `.sh`, `.bash`, `.zsh`, `.fish`, and matching extensionless shebang files. Python discovery supports `.py` and extensionless Python-shebang files, exposing `uv run` and/or the available `python3`/`python` interpreter. Required interpreters must be installed locally; duplicates and built-in overlaps do not duplicate menu entries. Absolute, drive/UNC, `..`, null-byte, missing, non-directory, or symlinked-outside-the-project paths are rejected. Stale or invalid stored paths surface diagnostics in the dialog instead of being scanned. `POST /api/app-runner-config` accepts either `{ "runner": { ... } }` or `{ "searchPaths": [...] }` (not both in one request) and preserves the other field.
337
440
 
@@ -373,7 +476,7 @@ Focused checks are `node tests/session-tree-event-targets.test.mjs`, `node tests
373
476
  - Localhost-only `POST /api/optional-feature-install-batch` for a bounded allowlisted `featureIds` batch. It requires the current audit `revision`, installs sequentially, reports ordered per-feature and aggregate results, and accepts `migration: true` for the combined restore flow.
374
477
  - Localhost-only `POST /api/optional-feature-migration/recheck` for a bounded read-only audit and `POST /api/optional-feature-migration/dismiss` for persisted **Later** state.
375
478
  - `GET /api/git-workflow/staged-content?tab=<tabId>` for the read-only bounded staged-content hash used by Guided Git approval binding.
376
- - `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, and `GET /api/update/transactions/<transactionId>` for exact planning, digest-bound apply, and durable receipts/status. The retired rollback route returns `410 Gone`; native package changes cannot be undone by switching a pointer. Legacy `POST /api/update` and `POST /api/component-update` mutation return `410 Gone`.
479
+ - `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, and `GET /api/update/transactions/<transactionId>` for fixed command previews, token-bound apply, and in-memory command results. The retired rollback route returns `410 Gone`; native package changes cannot be undone by switching a pointer. Legacy `POST /api/update` and `POST /api/component-update` mutation return `410 Gone`.
377
480
  - `GET /api/network`, localhost-only `POST /api/network/open`, localhost-only `POST /api/network/close`, `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for trusted-LAN exposure and optional 4-digit PIN authentication when serving non-local browser clients.
378
481
  On hosts with WebKit's system libraries installed, provision it and include its project explicitly with `npx playwright install webkit && PI_WEBUI_TEST_WEBKIT=1 npm run test:browser`. The browser suite is intentionally separate from `npm test`; it covers browser-only geometry, flag/rollback, and scoped axe checks without making ordinary Node/static tests download browser engines.
379
482
  When enabled, each click obtains a fresh Turnstile token and UUID-v4, then posts only `{ schemaVersion, idempotencyKey, turnstileToken, issue }` to `POST /v1/submissions`. `issue` is the selected structured wizard state (`categoryId`, `componentId`, `templateId`, `summary`, and declared fields); editable canonical title/body, repository, labels, verdicts, callback URLs, and credentials are never sent. The returned status capability remains only in an opaque in-memory refresh handle for the open dialog. Nothing in this flow uses `localStorage`, `sessionStorage`, cookies, or draft persistence.
@@ -461,9 +564,13 @@ The extension launches its JavaScript bootstrap with the current Node executable
461
564
 
462
565
  ### Native Pi and Web UI updates
463
566
 
464
- The browser plans one `pi` or `webui` action, confirms the returned executable/argv, installation roots and frozen execution context, then applies only the ID and digest. It observes `GET /api/update/transactions/<id>` and uses local-only update-status discovery of native jobs after reconnect. Discovery errors block new action controls. Receipts expose `changed`, `unchanged`, `failed`, or `unknown` per command; verified targets and the final phase distinguish completed native commands from healthy active installations and completed restart. A `restart-authorized` phase is waiting for idle, and `restart-pending` has not confirmed successor health. `unknown` retains exclusion for manual recovery; no inferred retry or restart.
567
+ The sidebar menu and existing component buttons share `POST /api/update/plan`, `POST /api/update/apply` and `GET /api/update/transactions/<id>`. A plan accepts exactly one fixed target: `all`, `webui` or `pi`. Selecting an update scope requests the server-generated plan and immediately applies its validated ID and token, without a confirmation dialog. It never sends an arbitrary command. Normal localhost authorization and request validation still apply.
568
+
569
+ The package-update service detects installed WebUI manifests under the global npm root and the Pi agent npm directory. Commands are fixed argument arrays. It runs `pi update --all`, which also covers the Pi-managed copy, followed by an update of any separate global WebUI copy. It does not run version/capability probes, ownership checks, idle admission, context fingerprints, effect locks, health probes or automatic restarts. One job runs per server, with bounded execution and output; receipts report command exit results. Native lifecycle scripts are not sandboxed. Job state belongs to the current server process, so reconnect can recover it but a process restart does not preserve a new job's history.
570
+
571
+ Job snapshots include current-step bounded/redacted output, start timestamps, total and completed step counts. The browser displays these through a persistent update card and labels its elapsed-time heuristic as estimated progress. It never reaches 100 while a command runs or converts an error into completion. Explicit successful Pi/npm no-change summaries produce unchanged receipts; all-unchanged jobs omit restart guidance. Unknown output remains ordinary command success, with no additional version probes. Details shows the same job’s command results and returns to its progress card without opening scope selection. Terminal summaries avoid repeating logs; an unchanged compact card omits output, timing and the completion bar. Read-only installation guidance is derived from failed receipts, not a new preflight check.
465
572
 
466
- Only PATH Pi 0.87.1 has verified initial CLI semantics. npm-global Web UI and Pi user npm sources may update independently. Pi user scope excludes project settings with `--no-approve`; exact pins and unsupported owners are skipped. The detached native runner and receipts live outside mutable installations. Shells use exact bound interpreters and argument arrays, not browser-supplied command strings. On Windows a private detached Node guardian owns ordinary hidden PowerShell: detached PowerShell silently skipped its command on the tested host, and ordinary PowerShell alone did not survive initiator exit. The guardian records a verified pre-shell launch refusal separately from any uncertain post-spawn completion. The context fingerprint includes scoped registries and npm-reported user/global configuration paths. Shared physical-root fences include the selected active Pi root independently of PATH Pi and keep known work idle during mutation and selective restart. Ordinary server restart holds a counted admission lease through handoff; native restart requires bounded RPC readiness and matching saved session files before releasing the fence. Native lifecycle scripts are not sandboxed, and bounded redaction cannot guarantee removal of arbitrary secrets.
573
+ The older native-update modules and their standalone tests remain for historical recovery compatibility. Their executable/context digests, physical-root exclusion, detached runner, verification and selective-restart contracts do not govern new menu jobs. Existing journal files are not deleted or replayed by the new path.
467
574
 
468
575
  The launcher can migrate legacy `current.json` and `previous.json` pointers only to a canonical compatible equal-or-newer installed candidate after an isolated real startup and restored-tab probe. A subsequent candidate upgrade must pass the same probe and advances the accepted version floor atomically without replacing the original pointer backups. Both pointers receive immutable backups; old files and runtimes remain for fallback. An incompatible, unhealthy or older candidate retains legacy startup and needs manual attention. This migration is not native-update rollback. Ordinary tab restoration still uses the retained restart descriptor. Startup retries transient `EADDRINUSE` with bounded backoff.
469
576
 
@@ -582,7 +689,7 @@ Continuity is scoped to the resolved private Pi agent/config root and Web UI por
582
689
 
583
690
  Updates preserve already-running supervised Pi processes, so an active tab continues with the Pi/runtime code it already loaded. Newly created or explicitly reloaded tabs use the newly installed versions. Additive supervisor protocol-minor changes are compatible; a protocol-major mismatch with live children fails closed instead of replacing the supervisor or spawning duplicates. Roll forward to a compatible Web UI rather than killing a healthy supervisor that owns active work.
584
691
 
585
- Continuity deliberately excludes app runners: restart and update stop their process trees, and they must be started again after reconnection. It also does not preserve browser drafts, SSE connections, arbitrary extension memory, or an active request across supervisor failure, OS reboot, power loss, or machine restart. Session files can still restore durable transcript history after those failures, but they cannot resume the same in-flight model request.
692
+ Continuity deliberately excludes app runners: server restart stops their process trees, and they must be started again after reconnection. Package update commands do not restart the server automatically. It also does not preserve browser drafts, SSE connections, arbitrary extension memory, or an active request across supervisor failure, OS reboot, power loss, or machine restart. Session files can still restore durable transcript history after those failures, but they cannot resume the same in-flight model request.
586
693
 
587
694
  ### Compact live output mode
588
695
 
@@ -957,7 +1064,7 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
957
1064
  - `--host 0.0.0.0` also exposes the Web UI to the local network; pass `--remote-auth` to start with PIN auth already enabled.
958
1065
  - Any connected browser client with access (and the PIN, if enabled) can control Pi and run Web UI bash actions as the Web UI process user.
959
1066
  - Remote PIN auth is a simple trusted-LAN HTTP gate, not hardened multi-user authentication; do not expose it to untrusted networks.
960
- - The Web UI update endpoint is restricted to localhost, because it runs package update commands and restarts the server.
1067
+ - The Web UI update endpoint is restricted to localhost, because it runs package update commands.
961
1068
  - Treat Pi Web UI as a local companion, not a hardened multi-user web service.
962
1069
 
963
1070
  ## Troubleshooting
@@ -969,9 +1076,9 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
969
1076
  - **Remote browser asks for a PIN:** read it from the optional **Remote WebUI** side-panel controls, `/webui-status`, `/remote status`, or the local Web UI server log. Disable the toggle from localhost to remove the PIN gate.
970
1077
  - **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.
971
1078
 
972
- ## Native update workflow
1079
+ ## Legacy native update workflow
973
1080
 
974
- This diagram describes the new native-command updater in the current working tree, not a released or fully accepted implementation. The [implementation plan](plans/planned/simplify-updates.md) still lists integrated validation, independent reviews, and the completion report as pending. The UI handoff reports browser tests blocked by missing Playwright. Durable job discovery and the separate PATH Pi preview fields are now present in the server, superseding the handoff's earlier integration-gap notes.
1081
+ The following diagram and command table document the retained legacy journal/runner code. New menu actions use the simpler package-update service described above and do not enter this flow. This diagram describes the former native-command update flow. Durable job discovery keeps the original target and receipts through reconnects; confirmed PATH Pi details remain separate from the active session runtime. The [compact workspace implementation record](docs/overhaul/implementation-record.md) records the current integration checks. Browser coverage includes target confirmation, partial/unknown outcomes, PWA recovery and reconnect continuity; it uses disposable state and simulated updates rather than installing packages.
975
1082
 
976
1083
  ```mermaid
977
1084
  flowchart TD
@@ -1064,3 +1171,35 @@ Restarting only the Web UI normally keeps managed Pi tabs, working directories,
1064
1171
  ## Settings and private data
1065
1172
 
1066
1173
  Web UI settings are stored under `~/.pi/webui/` by default. Private runtime state, update records, authentication data, and supervisor details are not exposed to browsers. Do not delete private runtime files while managed tabs are still active.
1174
+
1175
+
1176
+ ### Session owners during the compact workspace migration
1177
+
1178
+ The browser uses flat native modules for session identity, composer state, attention reconciliation, EventSource lifetime and extension request queuing. Their adapter contract is maintained in [the overhaul capability ledger](docs/overhaul/capability-ledger.md#w2-ownership-under-integration). HTTP/SSE shapes, supervisor ownership and settings storage are unchanged.
1179
+
1180
+ A captured tab context becomes stale when that tab replaces its session, as well as when the active tab changes. Replacement clears conversation projections, reconnects the single stream and schedules authoritative refresh. It preserves drafts, attachment objects and project editor buffers. Scoped GET deduplication cannot share a request across context generations. Extension responses continue to use the originating tab and request ID. Per-tab lifetime captures protect prompt preparation, completion and dialog responders across replacement without cancelling valid source-tab sends during navigation. Replacement retires old dialogs locally; successful sends release only their captured attachment objects.
1181
+
1182
+ The attention owner reconciles multiple idle tabs every ten seconds to discover later blockers. It forwards an AbortSignal through metadata fetches, limits each scheduled request to ten seconds, defers open group menus and backs off failures. Ordinary bootstrap and explicit user refreshes remain separate; their result serial protects against older responses. Authoritative tab mutation responses advance that serial as well, so an old poll cannot restore a closed tab or erase a newly created one.
1183
+
1184
+ Focused ownership checks are the `session-*.test.mjs`, `platform-event-stream.test.mjs` and `shell-action-adapter.test.mjs` tests. Browser adoption uses the opt-in `FAKE_PI_SESSION_OWNERSHIP=1` fixture; this is a test-only switch and makes no provider calls. The complete package check and separate Chromium tests remain integration gates.
1185
+
1186
+ ## Compact control integration
1187
+
1188
+ `model-catalog-order.mjs` groups model catalog records without changing their identities or the saved scoped-model order. Only explicit `releaseDate` and `release_date` values establish chronology; invalid or absent dates use display-name/ID sorting. The grouped native selector retains origin-session guards and keyboard selection.
1189
+
1190
+ `settings-workspace.mjs` indexes configuration destinations and hosts canonical controls. Sampling and Codex speed reads on Settings entry must not mutate settings. Sampling, runner, summary and Git-footer dialogs retain their session/project target through asynchronous work. Footer context actions share the captured command target without requiring the Settings dialog to be open.
1191
+
1192
+ The compact composer permits vertical focus recovery in short windows and contains horizontal overflow within its action row. The minimized workflow pair occupies two action cells. `shell-navigation-resize.mjs` owns pointer capture, active-drag Escape handling and effective width bounds; only changed user widths are persisted. Viewport clamping must not overwrite the preferred width.
1193
+
1194
+ Coverage includes `composer-toolbar-polish.spec.mjs`, `settings-complete-home.spec.mjs`, `model-catalog-groups.spec.mjs` and `session-sidebar-resize.spec.mjs`. Run these with the package's Chromium browser configuration and isolated test state.
1195
+
1196
+ ### Deferred workspace selection
1197
+
1198
+ Browser draft records retain optional `cwd` in the existing version-1 envelope. It is bounded to 4096 UTF-16 code units and rejects NUL; absent or empty values keep No Project behavior. The empty-screen workspace picker captures its originating draft identity, and first-send promotion captures cwd alongside text/revision. Selection cannot reassign a promoted draft or create a Pi child early.
1199
+
1200
+ The shared path-fast-pick and directory-creation routes allow absent tab context only when there are zero tabs and no explicit tab identifier. Explicit unknown identifiers still fail, and real-tab Natural Conversation guards retain their existing behavior. `tests/browser/workspace-draft-selection.spec.mjs` covers these route contracts and browser draft selection/promotion races.
1201
+
1202
+
1203
+ ### Thread start flow
1204
+
1205
+ `public/workspace-choices.mjs` is the pure list builder for the New thread palette and the draft folder dropdown (`tests/workspace-choices.test.mjs`). `tests/browser/thread-start-flow.spec.mjs` covers palette and dropdown choices with zero `POST /api/tabs`, first-prompt creation in the chosen folder, a dropdown change during a pending first send, keyboard navigation and Branch worktree. `#newTabButton` keeps its ID for existing hooks; the old `+ Tab` menu items are gone.
package/README.md CHANGED
@@ -17,16 +17,18 @@ Pi Web UI keeps the normal Pi agent experience while giving you more room to man
17
17
 
18
18
  | Area | Highlights |
19
19
  | --- | --- |
20
- | **Sessions and workspaces** | Run several isolated Pi sessions, resume prior work in a new terminal without replacing the current one, switch projects, preserve per-tab drafts, add another tab directly from the tab strip, and create branch worktrees. |
20
+ | **Sessions and workspaces** | Start a No Project conversation in its own folder, run several isolated Pi sessions, resume prior work in a new terminal without replacing the current one, switch projects, save unfinished No Project conversations as browser drafts, preserve per-tab drafts, add another tab directly from the tab strip, and create branch worktrees. Organize the compact sidebar into Inbox, Working, and Settled. |
21
21
  | **Live agent work** | Follow streaming Markdown with syntax highlighting for code blocks, grouped consecutive thinking, tool output, queues, todo progress, managed agent runs, and direct agent-to-agent conversations without leaving the browser. |
22
22
  | **Models and controls** | Change models and thinking effort, check Codex CLI subscription usage, manage scoped models, configure tools and skills, and use the command palette. |
23
23
  | **Files and prompts** | Upload or paste files and images, edit text attachments, use slash-command suggestions, browse project files, and reference project paths with `@`. |
24
24
  | **Git workflows** | Inspect changes, switch branches, review diffs, stage work, generate commit messages with an optional one-shot fallback model, push, and prepare pull requests through guided steps. |
25
- | **Project utilities** | Launch detected app runners, manage working directories, search files and transcripts, and customize themes. |
25
+ | **Project utilities** | Inspect Project and Activity from one right panel, open a floating session overview, launch detected app runners, manage working directories, search files and transcripts, and customize themes. |
26
26
  | **Companion features** | Add stats, remote access, voice, `/btw`, richer Git status, themes, release tools, and other supported Pi packages. |
27
27
  | **Desktop and mobile** | Use a full desktop workspace with resizable left and right side panels, or a compact phone layout with touch-friendly navigation and controls. |
28
28
  | **Customizable controls** | Hide optional workspace, Control Deck, composer, workflow, attachment, and input-tag controls while keeping Send available. |
29
29
 
30
+ In the compact layout, use **Inspector** in the conversation header to open Project or Activity. Use **Overview** for a floating summary of the current session and its work.
31
+
30
32
  ## Quick start
31
33
 
32
34
  ### Requirements
@@ -49,6 +51,8 @@ Restart Pi, then run:
49
51
 
50
52
  Open the printed address, usually <http://127.0.0.1:31415/>. The browser normally opens automatically.
51
53
 
54
+ A fresh start shows **No Project** with no active session. Send your first message to start a conversation in its own folder, or choose a project. To start in a specific folder immediately, use `/webui-start --cwd /path/to/project`.
55
+
52
56
  Check the server at any time with:
53
57
 
54
58
  ```text
@@ -56,14 +60,36 @@ Check the server at any time with:
56
60
  /webui-status detailed
57
61
  ```
58
62
 
63
+ ### Choose your desktop layout
64
+
65
+ Fresh installations start with the compact desktop layout when the Web UI can confirm there is no earlier Web UI state. Existing installations keep Classic until you choose **Controls → Interface → Desktop layout → Compact preview**. Use **Inspector** in the header for Project and Activity, and the lower-left rail for **Attention**, **All tools**, and **Settings**. All tools searches commands and panels; pin frequent actions there. The footer's **Model** and **Effort** controls open their pickers. **All tools → /model** opens the full model catalog; **Model shortcuts** opens your saved scoped models. In Settings, search or choose a category to open the original control or Setup dialog.
66
+
67
+ Press **Pi** at the top left, or press the **New thread** (pencil) button and choose **No project**, to open an empty conversation. Its thread and folder are created when you send the first message. If you type and switch away, your text appears as a **Draft** in Inbox. Reopen it to continue, or close it to discard the text. Drafts cannot be settled. Existing sessions stay open; resuming one reuses its folder. From the empty screen, **Open workspace** or a recent folder chooses where your first prompt will run without opening a terminal. A saved Draft keeps both its text and selected folder.
68
+
69
+ The **New thread** button opens a searchable folder list: the current folder, No project, pinned and recent folders, **Browse…** and **Branch worktree…**. Picking a folder opens an empty draft there; nothing starts until your first prompt. On the empty screen, click the **Workspace** value to switch the draft's folder from the same list. Branch worktree still creates its thread right away.
70
+
71
+ In the folder picker, **Pinned folders** appears above **Current location**, and **Create a folder** appears above the folder list. Both sections start expanded and can be collapsed.
72
+
73
+ The compact left sidebar keeps idle, finished, and input-waiting sessions in **Inbox**, with active work in **Working**. Choose **Settle** (✓) on a finished session to move it into **Settled**, collapsed by default. Expand it and choose **Restore** (↥) to bring a session back. New work or a request for input brings it back automatically. Settling does not close the session.
74
+
75
+ In the compact layout, **Ctrl/Cmd+K** opens the same **All tools** search. Session and Project menus offer a short list of actions; **More actions** opens the full catalog. The **Attention** button separates decisions waiting for you, running sessions, and finished work. Select a decision to open its session's response dialog.
76
+
77
+ Drag the right edge of the compact session sidebar or the left edge of the inspector to resize it. Open Settings with the gear beside Home at the bottom left.
78
+
79
+ Select the model or effort in the footer to open its picker. The full model catalog groups models by provider, then sorts dated models newest first and undated models alphabetically. A choice applies to that session without a separate Apply button. While Pi is working, **During this run** chooses whether the single submission button steers the run or queues your message afterward. Enter follows that choice; Abort remains separate.
80
+
81
+ **Project** groups Files, Changes, Runners, Releases, and Documents. **Activity** groups Agents, Queues, Progress, Conversations, Events, and provider usage. Use the inspector header to choose a section without scrolling sideways. Open a section when you need it; changing views keeps running work and unsaved drafts. A queue count beside the draft opens pending follow-ups for editing and reordering.
82
+
83
+ Choose **Classic** in Settings to return. Your open sessions, drafts, and saved Classic arrangement remain available. Phone and tablet modes have separate preferences.
84
+
59
85
  ### Your first session
60
86
 
61
87
  1. Start the Web UI with `/webui-start`.
62
88
  2. Confirm the working directory in the footer or choose another project. You can paste or type a full path in the picker; on Windows, use a rooted drive path such as `C:/` or `D:/project`. From a drive root, choose **Parent** to open **This PC** and select another available drive.
63
89
  3. Select a model and thinking effort.
64
90
  4. Enter a prompt, attach context if needed, and follow the live response. The prompt grows to a bounded height, then scrolls vertically so every line stays reachable.
65
- 5. Open the Control Deck for sessions, Git, app runners, themes, updates, and optional features. Under **Controls → Interface**, choose **Top bar** or **Sidebar** for terminal tabs, then choose **Right**, **Left**, or **Both** for the Control Deck. In **Sidebar**, **Both** is unavailable; choosing **Right** or **Left** swaps the Control Deck and terminal/tabs rails across the chat.
66
- 6. On desktop, drag the workspace-facing edge of any visible Control Deck—or the terminal/tabs rail in **Sidebar**—to choose a comfortable width. In **Both**, resize the left and right Control Decks independently; widths return on your next visit.
91
+ 5. In the compact layout, use **Project**, **Activity**, **Settings**, or **All tools**. In Classic, open the Control Deck for sessions, Git, app runners, themes, updates, and optional features. Under **Controls → Interface**, choose **Top bar** or **Sidebar** for threads, then choose **Right**, **Left**, or **Both** for the Control Deck. In **Sidebar**, **Both** is unavailable; choosing **Right** or **Left** swaps the Control Deck and terminal/tabs rails across the chat.
92
+ 6. In Classic on desktop, drag the workspace-facing edge of any visible Control Deck—or the terminal/tabs rail in **Sidebar**—to choose a comfortable width. In **Both**, resize the left and right Control Decks independently; widths return on your next visit.
67
93
 
68
94
  The completed response replaces the live draft, including thinking the provider corrects or removes. On older Pi releases, tool arguments may appear only after the tool is identified, so Intercom content stays out of the main transcript.
69
95
 
@@ -83,6 +109,8 @@ Independent Pi processes do not appear automatically. Start them through `pi-web
83
109
 
84
110
  When agents exchange direct Intercom messages or use native subagent-supervisor coordination, one compact tag per conversation appears beneath the composer. The tags start at the right edge and extend toward the middle, using up to half of the prompt width. Each tag has a bounded width. If they do not fit, WebUI keeps complete tags visible and replaces the rest with a **+X** tag. Select **+X** to open the remaining conversations above the composer. Long names still shorten with an ellipsis when one name exceeds the available space, while the full name remains available to assistive technology and on hover. Select a conversation to open a read-only chat view showing the two agent names or IDs and their messages. Generic Intercom transport calls and received Intercom records stay out of the main agent-output transcript, while attachments, tool output, and reasoning remain excluded from the chat view.
85
111
 
112
+ If preview navigation gets in your way, add `?shell=classic` to the Web UI address to return to the standard layout without resetting your preferences. See [the technical reference](TECHNICAL.md) for the surrounding layout options.
113
+
86
114
  Useful shortcuts:
87
115
 
88
116
  - `Ctrl/Cmd+K` opens the command palette.
@@ -291,7 +319,7 @@ Choose a project immediately:
291
319
  pi-webui --cwd ~/src/my-project
292
320
  ```
293
321
 
294
- If you omit `--cwd`, the browser asks which project to open first.
322
+ Without `--cwd`, a fresh start opens **No Project** with no active session. Type your first message to create a conversation in its own folder, or choose a project. Previously running or explicitly restored sessions remain available.
295
323
 
296
324
  ## Keep it private
297
325
 
@@ -302,7 +330,7 @@ Use the optional Remote Web UI package when you need trusted-LAN access and PIN
302
330
 
303
331
  ## Technical details
304
332
 
305
- To update, select **Update Pi** or **Update Web UI** in the Control Deck. Read the preview of installations and commands, including skipped installations, before confirming. Only localhost can start an update. Finish work in affected tabs first; native package updates may run lifecycle scripts under your existing configuration and cannot be automatically rolled back. The small activity indicator and command results remain available after reconnect. If the status is unknown, check the host before trying again.
333
+ Use the **Updates** button beside Settings to update **Pi and extensions + WebUI**, **WebUI only**, or **Pi only**. WebUI checks its Pi-managed and global npm installation locations and uses the matching update command. Selecting a scope starts the update immediately. A progress card shows the current step, elapsed time, and an estimated percentage while commands run. It says **Already up to date** when the commands explicitly report no changes. Open **Details** for command results, then **Back to progress** while running or **Back to result** when finished. Otherwise, restart WebUI after a successful update to load the updated code. Updates can only be started from localhost. Package scripts run under your existing configuration, and package updates cannot be automatically rolled back.
306
334
 
307
335
  > **Before downgrading:** stop the Web UI and back up `~/.pi/webui/settings.json`. Older releases do not understand the two-sided Control Deck layout and can overwrite it. Re-upgrade before restoring the backup.
308
336