@firstpick/pi-package-webui 0.10.1 → 0.10.3

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 (55) hide show
  1. package/DEVELOPMENT.md +41 -19
  2. package/README.md +13 -3
  3. package/TECHNICAL.md +16 -2
  4. package/bin/pi-webui.mjs +257 -76
  5. package/index.ts +1 -256
  6. package/lib/append-system-selection.mjs +311 -0
  7. package/lib/git-workflow-preferences.mjs +6 -0
  8. package/lib/trust-boundaries.mjs +37 -0
  9. package/package.json +1 -1
  10. package/public/app.js +162 -7
  11. package/public/index.html +5 -2
  12. package/public/service-worker.js +1 -1
  13. package/tests/append-system-http.test.mjs +622 -0
  14. package/tests/append-system-selection.test.mjs +259 -0
  15. package/tests/append-system-selector-static.test.mjs +95 -0
  16. package/tests/boot-failure-diagnostics.test.mjs +2 -2
  17. package/tests/codex-fast-mode-static.test.mjs +2 -2
  18. package/tests/common-options-submenus-interaction-static.test.mjs +4 -0
  19. package/tests/common-options-submenus-markup-static.test.mjs +2 -1
  20. package/tests/composer-action-grid-reorder-static.test.mjs +2 -2
  21. package/tests/control-visibility-static.test.mjs +2 -2
  22. package/tests/controls-layout-static.test.mjs +2 -2
  23. package/tests/events-tree-context-menu-static.test.mjs +2 -2
  24. package/tests/fast-mode-client-static.test.mjs +1 -1
  25. package/tests/feature-decision-output-popup-static.test.mjs +1 -1
  26. package/tests/file-viewer-image-static.test.mjs +2 -2
  27. package/tests/guided-git-activation-static.test.mjs +10 -3
  28. package/tests/guided-git-fallback-runtime.test.mjs +46 -21
  29. package/tests/guided-git-fallback-ui-static.test.mjs +3 -3
  30. package/tests/intercom-conversation-viewer-static.test.mjs +2 -2
  31. package/tests/main-output-loading-static.test.mjs +2 -2
  32. package/tests/middle-button-drag-scroll-static.test.mjs +2 -2
  33. package/tests/mobile-continuity-tablet-static.test.mjs +2 -2
  34. package/tests/mobile-foundation-static.test.mjs +2 -2
  35. package/tests/mobile-phone-experience-static.test.mjs +1 -1
  36. package/tests/mobile-static.test.mjs +3 -2
  37. package/tests/native-parity-harness.test.mjs +7 -0
  38. package/tests/open-issue-wizard-static.test.mjs +1 -1
  39. package/tests/optional-feature-prompt-impact-static.test.mjs +2 -2
  40. package/tests/persistent-ui-layout-static.test.mjs +2 -2
  41. package/tests/prompt-input-vertical-scroll-static.test.mjs +2 -2
  42. package/tests/questionnaire-dialog.test.mjs +2 -2
  43. package/tests/resource-tui-extension.test.mjs +4 -18
  44. package/tests/session-sampling-ui-static.test.mjs +2 -2
  45. package/tests/side-panel-section-height-removal-static.test.mjs +2 -2
  46. package/tests/subagent-observability-static.test.mjs +2 -2
  47. package/tests/syntax-highlighting-static.test.mjs +2 -2
  48. package/tests/terminal-tab-prompt-tooltip-static.test.mjs +147 -0
  49. package/tests/terminal-tab-workspace-static.test.mjs +1 -1
  50. package/tests/theme-customizer-static.test.mjs +1 -1
  51. package/tests/windows-drive-cwd-picker-static.test.mjs +2 -2
  52. package/lib/tui-model-profile-selector.mjs +0 -183
  53. package/lib/tui-resource-selector.mjs +0 -173
  54. package/tests/tui-model-profile-selector.test.mjs +0 -102
  55. package/tests/tui-resource-selector.test.mjs +0 -74
package/DEVELOPMENT.md CHANGED
@@ -4,22 +4,44 @@ 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
- ## TUI tool and skill selector
7
+ ## Tool and skill command ownership
8
8
 
9
- `index.ts` keeps resource scope resolution and persistence in `registerTuiResourceController`. After the user chooses Session, Global, or Model scope, `lib/tui-resource-selector.mjs` owns the shared searchable list used by both `/tools` and `/skills`. Its interaction follows Pi's `/scoped-models` selector: arrows navigate, Enter toggles, the `app.models.enableAll`, `app.models.clearAll`, and `app.models.save` bindings perform bulk actions and save, and Escape or Ctrl+C cancels. Bulk actions affect only filtered resources while search is active.
10
-
11
- For Model scope, `lib/tui-model-profile-selector.mjs` searches provider, exact ID, and display name. It returns the selected model object directly rather than reconstructing a model from its rendered label. The picker opens at the active model when possible and marks models with a resource-specific profile.
9
+ WebUI does not register TUI `/tools` or `/skills` commands. The standalone `@firstpick/pi-extension-tools` and `@firstpick/pi-extension-setup-skills` packages own those commands and their Session, Global, and Model selector flow. Shared profile resolution, locking, and TUI selector components live in `@firstpick/pi-utils`. Browser-native tool and skill controls continue through `webui-rpc-helper.mjs` and the WebUI HTTP routes against the same saved state.
12
10
 
13
11
  Focused contributor validation:
14
12
 
15
13
  ```bash
16
- node --check lib/tui-resource-selector.mjs
17
- node --check lib/tui-model-profile-selector.mjs
18
- node tests/tui-resource-selector.test.mjs
19
- node tests/tui-model-profile-selector.test.mjs
20
14
  node tests/resource-tui-extension.test.mjs
21
15
  ```
22
16
 
17
+ ## Append-system prompt picker contract
18
+
19
+ The browser exposes one global `APPEND_SYSTEM.md` override through the native selector flow in `public/app.js`:
20
+
21
+ - `openNativeAppendSystemSelector` opens the shared native command dialog, fetches `GET /api/append-system-files?tab=<id>` via `nativeCommandApi`, and renders the returned candidates through the shared `renderNativeSelectorItems` implementation (filter input and keyboard navigation included). Candidate labels are visible alias paths and warn that followed targets can be outside the displayed root. It marks the saved candidate `current`, marks `Use Pi default discovery` current when no valid override is saved, and shows an invalid saved `appendSystemPromptPath` as a disabled row with a diagnostic. Scan `diagnostics` render as a bounded note (first 20 entries, kind/path/message only); prompt file contents are never fetched.
22
+ - Selecting an item posts `POST /api/append-system-selection` with `{ tabId, path }` (`path: null` for Pi default discovery). The save itself never reloads a tab. Only a response with `changed: true` and `restartRequired: true` proceeds to `confirmAppendSystemRestart`, which asks through the shared `appConfirmText` confirmation and, on approval, reuses the standard active-tab reload path (`sendPrompt("prompt", "/reload", { targetTabId, throwOnError: true })`); reload errors are surfaced in the events log. Cancellation keeps the saved choice for the next manual reload or new tab.
23
+ - The command palette lists the action as `/append-system` so the flow stays reachable from the browser-native settings surface.
24
+
25
+ Endpoint data contract (server side owned by the discovery/persistence workstream): `GET /api/append-system-files?tab=<id>` returns `appendSystemPromptPath` (saved override or `null`), `roots` (`{ path, label }`), bounded `candidates` (`{ path, rootLabel }`), bounded `diagnostics` (`{ kind, path, message }`), and `limits`. Discovery follows symlinked roots, directory entries, and exact-visible-name file links, including external targets, while candidate identity remains the visible absolute alias. Canonical directory identities are internal cycle/deduplication keys only. A provenance-valid global choice outside the active tab's roots is included as one deduplicated `Saved selection` candidate. `POST /api/append-system-selection` accepts `{ tabId, path }` and returns the same scan payload plus `changed` and `restartRequired`; it never returns file contents. Changed selections must be candidates of a fresh active-tab scan, while the exact provenance-valid saved path may be submitted unchanged from another project.
26
+
27
+ The exact lexical global Pi default `path.join(homedir(), ".pi", "agent", "APPEND_SYSTEM.md")` is excluded during discovery before candidate-limit accounting. Existing and submitted selections equal to it are normalized to `null` default discovery, so they do not produce an invalid saved row or `--append-system-prompt` override. No other global, nested, or project-local candidate is excluded.
28
+
29
+ Private settings persist both `appendSystemPromptPath` and its lexical `appendSystemPromptRootPath`. Child launch revalidates lexical containment, the exact visible name, the depth-10 bound, and the final followed target's regular-file status. The followed target may be outside the saved root, while the visible saved alias is passed unchanged to Pi. Broken, inaccessible, and non-regular targets fail closed. This intentionally allows a link to scan or load a prompt outside the two visible roots; canonical target identity is not persisted, and the accepted retargeting/validation-to-open race remains.
30
+
31
+ Each successful WebUI-managed Pi launch captures its validated selected path as tab-local runtime metadata. `tabMeta.prompt` and detached-supervisor metadata use only `null` or `{ "kind": "append-system", "path": "<absolute visible path>" }`. The path is capped at 4096 characters and cannot contain C0 control characters (`U+0000`–`U+001F`) or DEL (`U+007F`); restored values must also have exactly those two fields, the known kind, and an absolute path, or normalization returns `null`. Discovery omits candidates with those controls, and fresh or restored selections containing them fail closed. Tabs created by older builds therefore restore without a custom-prompt claim. Supervisor hydration retains valid descriptors, while supervised replacement stays atomic and direct create, working-folder replacement, and full reload update the live tab only after the child emits its successful spawn event.
32
+
33
+ Direct-mode `pi_process_start` is emitted from that child `spawn` event. A failed spawn emits `pi_process_error` without a preceding start. A failed direct working-folder replacement retains the prior live cwd and prompt descriptor and leaves cwd-dependent watcher subscriptions on that prior cwd; cwd, activity, prompt, and watcher publication move together only after the replacement spawn succeeds.
34
+
35
+ This descriptor comes directly from the validated saved selection used while constructing that process launch. It is never reconstructed from current global settings or by scanning final child arguments, so later selection changes do not rewrite existing tabs and arbitrary launcher `--append-system-prompt` values remain outside this contract. Prompt file contents, inline launcher text, and unrelated arguments are not copied into the descriptor.
36
+
37
+ Focused contributor validation:
38
+
39
+ ```bash
40
+ node tests/append-system-selection.test.mjs
41
+ node tests/append-system-http.test.mjs
42
+ node tests/append-system-selector-static.test.mjs
43
+ ```
44
+
23
45
  ## Web UI settings write lock
24
46
 
25
47
  `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.
@@ -279,7 +301,7 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
279
301
  - Optional Natural Conversation Mode shell for the standalone `@firstpick/pi-package-natural-conversation` package: when `/talk` (or `/voice`/`/conversation`) is loaded in the active Pi tab, Web UI shows per-tab Start/End controls, a read-only voice-mode chip, and backend guards that keep thinking `off` while blocking unsafe Web UI actions.
280
302
  - Browser voice loop for Natural Conversation Mode (`public/voice-conversation.mjs`): while the mode is active in a tab, the browser's Web Speech APIs listen for speech, send final transcripts as normal prompts, and speak Pi's final answers. The microphone pauses while answers are spoken (echo prevention), speech during final-output streaming becomes a steering interruption, speech during tool execution is queued until the tool phase ends, and silence after a spoken question sends a single structured silence event. Remote (non-localhost) sessions keep the microphone off until the per-tab `Allow remote microphone streaming` consent is granted; only text transcripts ever reach the Pi host on the browser-default path. Opt-in server-side fallback routes are available for local/Groq/OpenAI STT and local/OpenAI TTS when configured with server-side env vars; remote/LAN raw-audio STT fallback uploads require explicit per-request consent.
281
303
  - Browser-native Pi dialogs for `/model`, `/settings`, `/summary-setup`, `/safety-guard-setup`, `/git-workflow-setup`, `/theme`, `/fork`, `/clone`, `/name`, `/resume`, `/tree`, `/login`, `/logout`, `/scoped-models`, `/tools`, and `/skills`, plus an on-demand `/summary` Markdown overlay and native-command adapter output for `/copy`, `/session`, `/new`, `/compact`, `/reload`, and `/export`. Safety Guard Setup includes the opt-in auto-review toggle and active-tab authenticated model/supported-thinking selectors; auto-review remains off by default, and enabled saves reject unavailable selections.
282
- - Runtime `/tools` and `/skills` selectors backed by the hidden Web UI RPC helper, with explicit **Session only**, **Global default**, and exact **Model default** scopes. Session choices persist on the current branch and take precedence; global defaults are inherited by future sessions without rewriting existing branches. Disabled skills are removed from the system prompt, and tracked `SKILL.md` files can be opened/edited from skill tags. Responsive fitting keeps visible and hidden tag sets disjoint; the `+X` disclosure renders the hidden set in an upward, bounded popup and preserves selection, outside-dismissal, `Escape`, and focus-return behavior.
304
+ - Browser-native tool and skill selectors backed by the hidden Web UI RPC helper, with explicit **Session only**, **Global default**, and exact **Model default** scopes. Session choices persist on the current branch and take precedence; global defaults are inherited by future sessions without rewriting existing branches. Disabled skills are removed from the system prompt, and tracked `SKILL.md` files can be opened/edited from skill tags. Responsive fitting keeps visible and hidden tag sets disjoint; the `+X` disclosure renders the hidden set in an upward, bounded popup and preserves selection, outside-dismissal, `Escape`, and focus-return behavior.
283
305
  - Session resume into a newly created terminal tab, metadata rename, and localhost-only safe delete with active/open-tab/session-directory guards.
284
306
  - Model, thinking, session, workspace, theme, optional-feature, Codex usage, optional Remote WebUI, update/restart/stop, event, notification, thinking-visibility, terminal-tab-layout, and custom-background controls in collapsible side-panel sections.
285
307
  - A side-panel **Git** section mirrors the repositories represented by every open terminal tab/group. Repository cards are shown directly—without session-name parent disclosures—and always use the Git-root or cwd basename as their title. One repository can be expanded at a time. First/stale expansion refreshes local status after a five-minute cache window, while live filesystem updates use a debounced server watcher and SSE invalidation to refresh visible repositories without periodic Git polling or an automatic network `git fetch`. Its compact Changes tree groups conflicted, staged, modified, and untracked paths with additions/deletions; right-click a repository, folder, or file (or press Shift+F10/the Context Menu key) for View Diff, refresh, stage/unstage, and confirmed discard/delete actions. History lists the latest 30 commits and opens bounded read-only commit diffs.
@@ -660,17 +682,17 @@ Product screenshots are maintained in the [user-facing README](README.md#feature
660
682
 
661
683
  ### Tools setup
662
684
 
663
- - **What it is:** Browser and native TUI `/tools` selectors for active and available Pi tools.
685
+ - **What it is:** A browser selector for active and available Pi tools. The standalone tools extension owns the TUI `/tools` command.
664
686
  - **What you can do:** Search or toggle tools, pin the current session branch, save a global default, configure an exact provider/model profile, or return a scope to inherited behavior. A successful model change immediately recomputes unpinned tools.
665
687
 
666
688
  ### Skills setup
667
689
 
668
- - **What it is:** Browser and native TUI `/skills` selectors for skills discovered in the active Pi session.
690
+ - **What it is:** A browser selector for skills discovered in the active Pi session. The standalone skills extension owns the TUI `/skills` command.
669
691
  - **What you can do:** Find skills by name or description, pin the current session branch, save a global default, configure an exact provider/model profile, or return a scope to inherited behavior. A successful model change immediately recomputes unpinned skills while preserving `disableModelInvocation` filtering and explicit disabled-skill blocking.
670
692
 
671
693
  Session-specific tool and skill choices are independent and always win when their branch is resumed or selected in `/tree`. Exact model profiles are keyed by case-sensitive provider/model ID pairs and are stored as an array under settings-envelope version 8. Each profile contains nullable tool and skill selections: `null` inherits, while an empty array explicitly enables none. Legacy branch entries remain explicit pins; version-2 branch entries add `explicit` and `inherit` modes. Global and exact-model defaults are stored in the private Pi Web UI settings file (normally `~/.pi/webui/settings.json`) and do not mutate an explicit current session.
672
694
 
673
- `index.ts` owns resource lifecycle only in TUI mode, while `webui-rpc-helper.mjs` owns it in RPC mode. Both capture or resolve an immutable runtime fallback, recompute on session/tree/model events, and fence asynchronous model changes before applying them. HTTP model-profile writes validate the exact authenticated model and update the latest locked settings snapshot so concurrent writers and temporarily unavailable names are preserved.
695
+ `webui-rpc-helper.mjs` owns the browser session's resource lifecycle in RPC mode. It captures or resolves an immutable runtime fallback, recomputes on session/tree/model events, and fences asynchronous model changes before applying them. HTTP model-profile writes validate the exact authenticated model and update the latest locked settings snapshot so concurrent writers and temporarily unavailable names are preserved.
674
696
 
675
697
  `@firstpick/pi-package-qt-webui` consumes this package as the canonical tool/skill state owner. Its backend imports `webuiSettingsFile()`, `readWebuiSettings()`, `updateWebuiSettings()`, and the resource-selection helpers rather than copying the settings schema or lock protocol. Qt global and exact-model writes therefore merge into the same `resourceDefaults`, and its Pi helper uses the same `webui-tools-config` and `webui-skills-config` version-2 branch entries for session explicit/inherit state. Qt-only sampling remains outside this contract. Each Qt resource-state request reads the latest shared settings; there is no direct process-to-process synchronization.
676
698
 
@@ -758,9 +780,9 @@ Optional companions:
758
780
  - `@firstpick/pi-extension-workflows` — `/workflow` runtime with non-blocking Web UI subprocess-output widgets.
759
781
  - `@firstpick/pi-extension-feature-system-prompt` — feature-request classification and routing, with lightweight/complex decisions shown in the Web UI composer.
760
782
  - `@firstpick/pi-extension-safety-guard` — configurable guardrails for dangerous bash commands and protected file edits, with native `/safety-guard-setup` controls.
761
- - `@firstpick/pi-extension-setup-skills` — TUI `/skills` setup command alongside WebUI-native skill toggles.
783
+ - `@firstpick/pi-extension-setup-skills` — sole owner of the TUI `/skills` setup command; WebUI keeps separate browser-native skill controls.
762
784
  - `@firstpick/pi-extension-todo-progress` — todo-progress rendering.
763
- - `@firstpick/pi-extension-tools` — TUI `/tools` active-tool manager alongside WebUI-native tool toggles.
785
+ - `@firstpick/pi-extension-tools` — sole owner of the TUI `/tools` active-tool manager; WebUI keeps separate browser-native tool controls.
764
786
  - `@firstpick/pi-package-remote-webui` — `/remote` trusted-LAN QR helper plus the optional browser controls for opening/closing LAN access and Remote PIN auth.
765
787
  - `@firstpick/pi-extension-git-footer-status` — richer extension-owned git/footer status, including the structured Web UI footer payload. The Claude Usage panel consumes its live Anthropic response-header snapshot when available and keeps the standalone Claude CLI endpoint as an explicit/fallback refresh path.
766
788
  - `@firstpick/pi-extension-stats` — stats commands and status data.
@@ -791,7 +813,7 @@ For an existing repository, the workflow can:
791
813
  1. Show staged, unstaged, untracked, and fetched incoming changes.
792
814
  2. Fast-forward pull fetched incoming commits when the repository is safely behind.
793
815
  3. Review/select files, preserve a non-empty staged set, or explicitly opt into `git add .`.
794
- 4. Generate `/git-staged-msg` with the configured model, supported reasoning effort, language, and scope policy, then restore the tab's prior model/effort. Each request is correlated to its originating tab and a before-generation snapshot of both message files; the browser advances only when both non-empty files are fresh and stable for that exact generation.
816
+ 4. Generate `/git-staged-msg` with the configured model, supported reasoning effort, language, and scope policy without changing the tab's active model or effort. Each request is correlated to its originating tab and a before-generation snapshot of both message files; the browser advances only when both non-empty files are fresh and stable for that exact generation.
795
817
  5. Use the preferred generated short/long message, a generated single-file default such as `updated file.txt`, or a manual **Commit input** message.
796
818
  6. Show an optional pre-commit verification reminder, then require explicit confirmation before push and PR delivery actions.
797
819
 
@@ -805,13 +827,13 @@ The saved setup includes:
805
827
  - ask/current-branch/PR-worktree delivery highlighting; and
806
828
  - optional pre-commit verification reminders.
807
829
 
808
- If a configured model or effort is unavailable, setup saving fails closed. During generation, the server selects the configured profile and invokes the native extension command. The accepted RPC response confirms only that Pi handled the command. The server treats a correlated `extension_error` event as the native command's terminal failure and checks for a fresh correlated artifact only when the command did not report one. If the artifact check fails immediately after the accepted response, the server allows a bounded 500 ms grace period for a separately delivered correlated `extension_error` before reporting the artifact failure. Only the native command's internal direct model/provider-generation failure classification may start the explicitly configured fallback profile once. Invalid generated output, a missing or stale artifact after a command with no reported error, and all non-provider failures remain terminal. It never chooses an unconfigured model. The original tab model and effort are restored after a successful native artifact verification or terminal failure. Request validation, staged-content checks, cancellation, Git failures, and Pi process exit/error do not trigger fallback; a dead Pi process cannot run another attempt. Footer and Guided Git pushes send the active tab's current `HEAD` to the same-named branch on the preferred remote and set that branch as the upstream instead of retaining a potentially mismatched upstream. Guided Git never force-pushes automatically. Git hooks and signing configuration continue to run normally.
830
+ If a configured model or effort is unavailable, setup saving fails closed. During generation, the server encodes the configured profile in a private base64url extension-command argument and invokes the native extension command. The extension validates and resolves that profile, then calls its provider independently without changing the parent tab's active model or reasoning effort. The accepted RPC response confirms only that Pi handled the command. The server treats a correlated `extension_error` event as the native command's terminal failure and checks for a fresh correlated artifact only when the command did not report one. If the artifact check fails immediately after the accepted response, the server allows a bounded 500 ms grace period for a separately delivered correlated `extension_error` before reporting the artifact failure. Only the native command's internal direct model/provider-generation failure classification may start the explicitly configured fallback profile once. Invalid generated output, a missing or stale artifact after a command with no reported error, and all non-provider failures remain terminal. It never chooses an unconfigured model. Request validation, staged-content checks, cancellation, Git failures, and Pi process exit/error do not trigger fallback; a dead Pi process cannot run another attempt. Footer and Guided Git pushes send the active tab's current `HEAD` to the same-named branch on the preferred remote and set that branch as the upstream instead of retaining a potentially mismatched upstream. Guided Git never force-pushes automatically. Git hooks and signing configuration continue to run normally.
809
831
 
810
832
  After the message is generated, **Create PR** invokes the native branch command to generate `dev/COMMIT/staged-branch-name.txt`, lets you confirm or edit the `type/feature-name` branch, then switches with `git switch -c` before committing. In PR mode, choose **Commit short**, **Commit long**, or type a message and use **Commit input**, then **Push and Create PR** pushes the branch, invokes `/pr`, shows the generated `dev/PR/<encodeURIComponent(current-branch)>.md` description for editing/confirmation, and creates the pull request with `gh pr create`. Use **Manual branch** to skip model branch-name generation and type the branch directly.
811
833
 
812
834
  Use the workflow process buttons to jump directly to **Initialize**, **Stage**, **Message**, **Commit**, **Push**, or PR steps when earlier work was already completed manually. Selecting **Message** lets you either run `/git-staged-msg` or type a commit message and use **Commit input** directly. Selecting **Commit** loads the current generated files from `dev/COMMIT/` before enabling the commit choices. Manual preview remains available for existing files, while an active generation uses bounded single-flight polling and the exact server generation ID so duplicate timers and reconnects cannot surface a stale artifact. A yellow dot means that process was selected or is available but its action has not completed in this workflow; green means the process action completed.
813
835
 
814
- All three generation commands come from `@firstpick/pi-extension-git-guided-workflow` and call the active selected model directly. Creating the PR also requires an authenticated GitHub CLI (`gh`). Review the generated commit message, branch name, remote URL, and PR description before committing, pushing, or creating a PR.
836
+ All three generation commands come from `@firstpick/pi-extension-git-guided-workflow`. Direct invocations call the active Pi model; WebUI invocations call the configured Guided Git model independently. Creating the PR also requires an authenticated GitHub CLI (`gh`). Review the generated commit message, branch name, remote URL, and PR description before committing, pushing, or creating a PR.
815
837
 
816
838
  ### Extension activation contract
817
839
 
@@ -845,9 +867,9 @@ npx playwright test --project=chromium tests/browser/guided-git-extension-comman
845
867
 
846
868
  The persisted `generation.fallback` object always contains `provider`, `modelId`, and `thinkingLevel`; an empty provider/model pair disables fallback. The Guided Git setup client sends the nested fallback object on every save, filters the selected primary out of fallback choices, and sends empty provider/model fields when **No fallback** is selected. Server-side validation remains authoritative for availability, profile equality, and supported effort.
847
869
 
848
- `POST /api/git-workflow/generate` keeps `generation` as the effective profile and allocates one server generation ID for commit, branch, or PR text. The server resolves an RPC command with `source: "extension"`, selects the configured profile, sends the exact native slash command, and waits for that synchronous command response. The attempt succeeds only when the command also produces a fresh artifact relative to the captured baseline. If artifact verification fails, a bounded grace period gives the native `extension_error` event precedence when RPC stdout delivers it after the accepted command response. Only the native extension's stable internal direct model/provider-failure classification may start the configured fallback and return `fallbackUsed: true` with `primaryGeneration`; a successful RPC response without either a fresh artifact or correlated native error is terminal. Terminal dispatch errors include bounded correlation metadata.
870
+ `POST /api/git-workflow/generate` keeps `generation` as the effective profile and allocates one server generation ID for commit, branch, or PR text. The server resolves an RPC command with `source: "extension"`, selects the configured profile, encodes it with the public generation arguments in a private base64url command argument, sends the exact native slash command, and waits for that synchronous command response. The server does not send `set_model` or `set_thinking_level` RPC requests. The attempt succeeds only when the command also produces a fresh artifact relative to the captured baseline. If artifact verification fails, a bounded grace period gives the native `extension_error` event precedence when RPC stdout delivers it after the accepted command response. Only the native extension's stable internal direct model/provider-failure classification may start the configured fallback and return `fallbackUsed: true` with `primaryGeneration`; a successful RPC response without either a fresh artifact or correlated native error is terminal. Terminal dispatch errors include bounded correlation metadata.
849
871
 
850
- Fallback lifecycle events start with `webui_git_workflow_generation_fallback_started` and carry the effective `generation`, `primaryGeneration`, `kind`, `tabId`, and `generationId`, plus a curated bounded `reason` or `error`; full provider diagnostics remain server-side. The server retains at most the start and terminal fallback events per tab and replays them on EventSource reconnect. One correlation ID and pre-primary artifact baseline remain authoritative across both attempts. Commit, branch, and PR reads require successful terminal artifact verification, so failed-primary output cannot become ready while fallback runs. The server owns reservation, cancellation state, the two-attempt ceiling, and restoration of the original model/effort after success or terminal failure; the browser observes lifecycle state and never sends a retry. Validation failures, user aborts, Git command failures, and Pi process exit/error remain ordinary failures and never enter fallback dispatch.
872
+ Fallback lifecycle events start with `webui_git_workflow_generation_fallback_started` and carry the effective `generation`, `primaryGeneration`, `kind`, `tabId`, and `generationId`, plus a curated bounded `reason` or `error`; full provider diagnostics remain server-side. The server retains at most the start and terminal fallback events per tab and replays them on EventSource reconnect. One correlation ID and pre-primary artifact baseline remain authoritative across both attempts. Commit, branch, and PR reads require successful terminal artifact verification, so failed-primary output cannot become ready while fallback runs. The server owns reservation, cancellation state, and the two-attempt ceiling; the browser observes lifecycle state and never sends a retry. Primary and fallback requests leave the parent session's active model and effort unchanged. Validation failures, user aborts, Git command failures, and Pi process exit/error remain ordinary failures and never enter fallback dispatch.
851
873
 
852
874
  ## Open Issue bot
853
875
 
package/README.md CHANGED
@@ -162,7 +162,7 @@ For a long scoped-model list, right-click the Git footer **Model** box and choos
162
162
 
163
163
  **Optional feature needed:** None — the browser tools setup is included in Pi Web UI core.
164
164
 
165
- Enable tools for the current session, save a global default, or configure an exact model profile. In Pi's TUI, `/tools` uses the same searchable keyboard workflow as `/scoped-models`: arrow keys move, `Enter` toggles, `Ctrl+A` enables matching entries, `Ctrl+X` clears them, and `Ctrl+S` saves. **Model default** opens a searchable exact-model picker that marks the active model and existing tool profiles without switching the active model. Selecting a configured model automatically applies its tool profile unless the session has its own tool selection.
165
+ Enable tools for the current session, save a global default, or configure an exact model profile. Selecting a configured model automatically applies its tool profile unless the session has its own tool selection. Pi's TUI `/tools` command belongs to the optional `@firstpick/pi-extension-tools` companion and uses the same Session, Global, and Model scopes; WebUI does not register a competing command.
166
166
 
167
167
  #### Skills setup
168
168
 
@@ -170,7 +170,17 @@ Enable tools for the current session, save a global default, or configure an exa
170
170
 
171
171
  **Optional feature needed:** None — the browser skills setup is included in Pi Web UI core.
172
172
 
173
- Find installed skills and manage session, global, or exact-model activation. In Pi's TUI, `/skills` uses the same searchable keyboard workflow as `/scoped-models`, including the exact-model picker used by `/tools`. Selecting a configured model automatically applies its skill profile unless the session has its own skill selection.
173
+ Find installed skills and manage session, global, or exact-model activation. Selecting a configured model automatically applies its skill profile unless the session has its own skill selection. Pi's TUI `/skills` command belongs to the optional `@firstpick/pi-extension-setup-skills` companion and uses the same Session, Global, and Model scopes; WebUI does not register a competing command.
174
+
175
+ #### Append-system prompt picker
176
+
177
+ **Optional feature needed:** None. It is included in Pi Web UI core.
178
+
179
+ Choose one `APPEND_SYSTEM.md` file as a global append-system prompt for WebUI-managed Pi tabs. Open **Common Pi options**, choose **Feature Setup**, then select **Append-system Prompt**. You can also open the command palette and run **/append-system**. The picker shows files found by a bounded scan below your home `~/.pi` folder and the active tab's working directory, ready to filter and select. It follows file and folder links, including links to locations outside those two folders, while keeping the visible linked path in the list. The current choice is marked, and **Use Pi default discovery** removes the override again. Pi's exact global default file, `~/.pi/agent/APPEND_SYSTEM.md`, is represented by that default choice rather than a duplicate file row. Other files below `~/.pi`, including nested alternatives, remain selectable. Scan diagnostics explain when limits omit results; [TECHNICAL.md](TECHNICAL.md) lists the limits. The picker only shows file paths; it never edits or displays prompt file contents.
180
+
181
+ Saving the choice does not change a running Pi session by itself. After a changed save, the Web UI asks whether to restart the active Pi tab now; cancel keeps the saved choice for the next manual reload or new tab. Because the choice is global, it also applies to every new tab you open afterward. Pick files and links carefully: a followed link can scan or load a prompt from anywhere the Web UI process can read, and an append prompt changes Pi's high-priority instructions.
182
+
183
+ Hover a terminal tab to see the effective WebUI-selected non-default `APPEND_SYSTEM.md` visible path. Tabs using Pi's default discovery omit this line. Existing tabs keep their launch-time information until their Pi process is fully restarted or the tab is recreated, and the tooltip never reads or shows prompt contents.
174
184
 
175
185
  ### Project automation and Git
176
186
 
@@ -192,7 +202,7 @@ Run `/git-guided-workflow` in the browser composer or use the **Guided Git workf
192
202
 
193
203
  Move through review, staging, commit-message generation, commit, push, and pull-request steps with explicit confirmations. If a repository has no remote, choose **Public** or **Private** from the visibility dropdown and confirm publication. Guided Git uses the local Git root directory name, runs the authenticated system `gh` command, adds `origin`, and pushes the current branch.
194
204
 
195
- In **Guided Git Setup**, you can optionally choose a fallback model and its own reasoning effort. If the primary model reaches a final generation failure, Guided Git tries the fallback once, reports the change in the workflow, and restores the tab’s prior model and effort afterward. Large staged diffs use multiple model requests; a fallback attempt sends the complete staged evidence again to the configured fallback provider and can nearly double the request count and cost. Validation failures, cancellation, Git command failures, and a stopped Pi process do not trigger fallback.
205
+ In **Guided Git Setup**, choose the model and reasoning effort used for generated Git text. Guided Git calls that model independently without changing the parent tab’s active model or effort. You can optionally choose a fallback model and its own reasoning effort; after a final primary generation failure, Guided Git tries the fallback once and reports the change in the workflow. Large staged diffs use multiple model requests; a fallback attempt sends the complete staged evidence again to the configured fallback provider and can nearly double the request count and cost. Validation failures, cancellation, Git command failures, and a stopped Pi process do not trigger fallback.
196
206
 
197
207
  #### Git branch picker
198
208
 
package/TECHNICAL.md CHANGED
@@ -194,7 +194,7 @@ The flat-or-advanced choice is a browser-local display preference. It persists a
194
194
 
195
195
  ## Tool and skill scopes
196
196
 
197
- The browser-native tool and skill selectors, and the TUI `/tools` and `/skills` commands, offer **Session only**, **Global default**, and **Model default** scopes. In the TUI resource list, type to search, use the arrow keys to move, press `Enter` to toggle, `Ctrl+A` to enable matching entries, `Ctrl+X` to clear matching entries, and `Ctrl+S` to save. `Escape` cancels; `Ctrl+C` clears a non-empty search before cancelling. These shortcuts match `/scoped-models`, including custom Pi bindings for the shared model-selection actions. **Model default** uses a separate searchable provider, ID, and display-name picker. It opens at the active model when available, marks existing profiles, and returns the exact provider/model pair without changing the active model. Tools and skills resolve independently: a session choice wins over an exact case-sensitive provider/model profile, which wins over the global default and then Pi's runtime default.
197
+ The browser-native tool and skill selectors offer **Session only**, **Global default**, and **Model default** scopes. The extension-owned TUI `/tools` and `/skills` commands use the same scopes and saved state. Tools and skills resolve independently: a session choice wins over an exact case-sensitive provider/model profile, which wins over the global default and then Pi's runtime default. WebUI does not register either TUI command; they belong to `@firstpick/pi-extension-tools` and `@firstpick/pi-extension-setup-skills`.
198
198
 
199
199
  After Pi successfully selects a model, its exact tool and skill profiles apply immediately for resource types that are not pinned by the current session; no reload or selector reopening is needed. A model with no profile falls back through the global and runtime defaults. Choosing a model inside a profile editor selects the profile to edit—it does not switch the active Pi model.
200
200
 
@@ -204,6 +204,20 @@ Tracked skill files appear as selectable tags above the composer. The strip keep
204
204
 
205
205
  When the browser page is hidden, the Web UI closes that page's live event stream so the browser cannot accumulate serialized output frames for later parsing and DOM rendering. Merely moving focus to another visible window does not pause streaming. On return, it first fetches authoritative tabs, state, and transcript snapshots, reconnects live events, and refreshes nonessential panels during browser idle time. Pending extension prompts are replayed by the server after reconnection, and completed output remains available from the authoritative transcript.
206
206
 
207
+ ## Append-system prompt selection
208
+
209
+ The command palette action **/append-system** opens a picker for one global WebUI append-system prompt override. The scan starts from exactly two visible roots: the active Pi tab's working directory and your `~/.pi` folder. It checks at most 2,048 directories to a maximum visible-path depth of 10, returns at most 256 candidates and 64 diagnostics, and matches only the exact case-sensitive visible filename `APPEND_SYSTEM.md`. Root, folder, and file symbolic links are followed, including links whose targets are outside both visible roots. Candidate rows keep the visible linked path. Broken links and links to unsupported file types are skipped with bounded diagnostics, and the scan never reads or displays prompt contents.
210
+
211
+ **Trust warning:** a followed link can make the picker scan directories or load a prompt anywhere the Web UI process can read. Check both the link and its current target before selecting it. Link cycles and repeated targets remain bounded, but a link may be retargeted later.
212
+
213
+ The saved choice is a global WebUI setting, discovered through the active tab's working directory but applied to every new or reloaded WebUI Pi tab. It persists in private WebUI settings and its visible path is passed to newly launched Pi processes as a `--append-system-prompt` argument; a running session keeps its current instructions until restart. The exact global default path `~/.pi/agent/APPEND_SYSTEM.md` is not shown as a separate candidate because **Use Pi default discovery** already represents it. Submitting or previously saving that exact path is also treated as default discovery, without a redundant launcher override. Project-local defaults and nested alternatives such as `~/.pi/agent/minimal/APPEND_SYSTEM.md` remain selectable.
214
+
215
+ After a changed save the picker asks once whether to restart the active Pi tab. Cancel keeps the saved choice ready for the next manual reload or new tab. A saved visible path remains valid if its followed target changes to another regular file. If the link breaks, resolves to an unsupported type, or the visible path otherwise stops being valid, it stays visible in the picker marked as invalid with a diagnostic, and launching falls back to Pi's normal `APPEND_SYSTEM.md` discovery until you pick a valid file or choose **Use Pi default discovery**.
216
+
217
+ Hover a terminal tab to see `Append-system prompt: <path>` when that tab's Pi process started with an effective WebUI-selected non-default prompt. A grouped item reports its own prompt, while a collapsed group reports its active represented tab. Tabs using default discovery omit the line. Changing the saved choice does not rewrite existing tabs; their launch-time information changes only after a full Pi-process restart or tab recreation. The tooltip displays only the validated visible path and never reads or shows prompt contents.
218
+
219
+ Discovery and saving are localhost-only; a request rejected from a non-local browser shows a clear error in the picker and changes nothing. User-supplied Pi launcher arguments are still appended after the saved override. Pi appends repeatable `--append-system-prompt` inputs in argument order, so both the saved prompt and any later launcher prompts contribute in that order.
220
+
207
221
  ## Events and session-tree navigation
208
222
 
209
223
  Visible non-Intercom tool start, finish, and failure rows in **Events** show the tool name, lifecycle status, a shortened call ID, completion duration when a matching start was observed, and a bounded path only for a small set of file-oriented tools. The panel never displays unrestricted arguments, raw results, or tool output. Select any event row to keep the existing jump-to-chat behavior.
@@ -331,7 +345,7 @@ The launcher refuses immediately while the originating tab is running, compactin
331
345
 
332
346
  Open **Common Pi Options → Guided Git Setup** or run `/git-workflow-setup` before using generated commit messages, branch names, or pull-request text. Choose the required primary model and its reasoning effort. You may also choose a different fallback model and a separate supported effort, or leave **No fallback** selected. The effort lists follow the capabilities reported for each selected model. Before enabling fallback, account for its privacy and cost impact: large commit diffs use multiple model requests, and a fallback attempt sends the complete staged evidence again to the configured fallback provider.
333
347
 
334
- A configured fallback is a strict one-retry policy: Guided Git lets Pi finish the primary model’s own retry lifecycle, then makes at most one fallback attempt after a final primary model-generation failure. The workflow output identifies the primary and configured fallback at startup and reports when generation continues with the fallback. For a commit diff at the extension’s 16 MiB ceiling, one attempt can use up to 35 requests; chunk-summary formatting does not trigger retries. Fallback can repeat the full attempt, for up to 70 requests across both providers. Fallback status is restored when you return to the tab or its live event connection reconnects. Generated commit, branch, or PR text is treated as ready only after the correlated attempt finishes successfully. After successful generation or terminal failure, the tab’s model and reasoning effort are restored to the values it had before Guided Git generation began.
348
+ A configured fallback is a strict one-retry policy: Guided Git lets the primary model finish its own retry lifecycle, then makes at most one fallback attempt after a final primary model-generation failure. The workflow output identifies the primary and configured fallback at startup and reports when generation continues with the fallback. For a commit diff at the extension’s 16 MiB ceiling, one attempt can use up to 35 requests; chunk-summary formatting does not trigger retries. Fallback can repeat the full attempt, for up to 70 requests across both providers. Fallback status is restored when you return to the tab or its live event connection reconnects. Generated commit, branch, or PR text is treated as ready only after the correlated attempt finishes successfully. Primary and fallback requests run independently of the parent Pi session, whose active model and reasoning effort remain unchanged throughout.
335
349
 
336
350
  Fallback applies only to model generation. Request validation failures, staged-content checks, busy-state rejection, user cancellation, Git command failures, and a stopped or failed Pi process do not trigger it. A dead Pi process cannot run the fallback; restart or reload the tab and start a new generation request after addressing the failure.
337
351