pi-usereq 0.11.0 → 0.12.0

package/pi-usereq/docs/WORKFLOW.md

@@ -108,7 +108,7 @@
           - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
             - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
       - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
-    - `runFilesReferences(...)`: branch `--files-references`; emit monolithic explicit-file references markdown [`src/core/tool-runner.ts`]
+    - `runFilesSummarize(...)`: branch `--files-summarize`; emit monolithic explicit-file summary markdown [`src/core/tool-runner.ts`]
       - `generateMarkdown(...)`: analyze requested files and concatenate Python-compatible reference markdown sections [`src/core/generate-markdown.ts`]
         - `detectLanguage(...)`: map extension to language key [`src/core/generate-markdown.ts`]
         - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
@@ -208,7 +208,7 @@
           - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
             - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
             - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
-    - `runReferences(...)`: branch `--references`; emit monolithic project references markdown [`src/core/tool-runner.ts`]
+    - `runSummarize(...)`: branch `--summarize`; emit monolithic project summary markdown [`src/core/tool-runner.ts`]
       - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
         - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -417,10 +417,12 @@
         - `withProcessCwd(...)`: execute registration under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
           - `piUsereqExtension(...)`: register extension commands, tools, shortcuts, and lifecycle hooks [`src/index.ts`]
             - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before registration [`src/core/resources.ts`]
-            - `registerPromptCommands(...)`: register bundled `req-*` prompt commands [`src/index.ts`]
+            - `registerReqResetCommand(...)`: register the specialized non-agentic `req-reset` command [`src/index.ts`]
+            - `registerReqReferencesCommand(...)`: register the specialized non-agentic `req-references` command with non-`idle` rejection that transitions workflow state to `error` [`src/index.ts`]
+            - `registerPromptCommands(...)`: register bundled prompt-backed `req-*` commands with non-`idle` rejection that transitions workflow state to `error` [`src/index.ts`]
             - `registerAgentTools(...)`: register structured agent tools [`src/index.ts`]
             - `registerConfigCommands(...)`: register configuration commands [`src/index.ts`]
-            - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
+            - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut and cycle only the active runtime sound level without persisting boot config [`src/index.ts`]
               - `loadProjectConfig(...)`: load the current project config for shortcut registration [`src/index.ts`]
                 - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
                 - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -433,6 +435,10 @@
                   - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
                 - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
                 - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+              - `getPiUsereqRuntimeSoundLevel(...)`: read the active runtime sound level before shortcut cycling [`src/core/extension-status.ts`]
+              - `cyclePiNotifySoundLevel(...)`: compute the next active runtime sound level [`src/core/pi-notify.ts`]
+              - `setPiUsereqRuntimeSoundLevel(...)`: store the cycled runtime sound level and refresh the footer [`src/core/extension-status.ts`]
+                - `renderPiUsereqStatus(...)`: refresh the single-line footer after shortcut-driven runtime sound changes [`src/core/extension-status.ts`]
       - `buildDebugManual(...)`: render mode and per-command/per-tool examples, including JSON-oriented token-tool examples [`scripts/lib/extension-debug-harness.ts`]
     - `replaySessionStart(...)`: replay recorded `session_start` handlers and capture resulting UI state [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
@@ -464,7 +470,7 @@
             - `RecordingExtensionAPI.setActiveTools(...)`: replace active-tool set with runtime-visible names [`scripts/lib/recording-extension-api.ts`]
               - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
           - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
-          - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore elapsed timers, reset workflow state for startup/new/reload, and render status text [`src/core/extension-status.ts`]
+          - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore elapsed timers, load the active runtime sound level from persisted config during `session_start`, reset workflow state for startup/new/reload, and render status text [`src/core/extension-status.ts`]
             - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
               - `RecordingCommandContext.getContextUsage(...)`: return the offline context-usage placeholder [`scripts/lib/recording-extension-api.ts`]
             - `shouldResetElapsedStateOnSessionStart(...)`: detect `startup|reload` elapsed-reset boundaries [`src/core/extension-status.ts`]
@@ -473,18 +479,18 @@
             - `shouldResetWorkflowStateOnSessionStart(...)`: detect `startup|new|reload` workflow-reset boundaries [`src/core/extension-status.ts`]
             - `persistElapsedState(...)`: mirror completed timers into process-scoped persistence [`src/core/extension-status.ts`]
             - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
               - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
               - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
                 - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
                   - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
                     - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
                     - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
                 - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
                 - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
                 - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
-                - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+                - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
                   - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
                 - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                   - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
@@ -517,43 +523,66 @@
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
       - `withProcessCwd(...)`: execute the named command under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-        - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources when invoking `req-*` handlers [`src/core/resources.ts`]
+        - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources when invoking bundled prompt-backed `req-*` handlers [`src/core/resources.ts`]
         - `getProjectBase(...)`: resolve command project base [`src/index.ts`]
         - `loadProjectConfig(...)`: load command runtime config [`src/index.ts`]
+        - `resolveReqResetPromptRequest(...)`: resolve the recoverable prompt execution plan for `req-reset` from in-memory or persisted prompt state [`src/index.ts`]
+        - `prepareReqResetCommandExecution(...)`: derive base-path recovery and generated cleanup facts for `req-reset` [`src/core/req-reset-command.ts`]
+          - `buildReqResetWorktreeNamePattern(...)`: derive the generated worktree-name matcher from the configured prefix plus repository basename [`src/core/req-reset-command.ts`]
+        - `executeReqResetCommandExecution(...)`: preserve transcript, restore `base-path`, and force-remove matching worktrees plus branches for `req-reset` [`src/core/req-reset-command.ts`]
+          - `preservePromptCommandExecutionTranscript(...)`: copy execution-session records into the original session file when recovery plan data exists [`src/core/prompt-command-runtime.ts`]
+          - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path before cleanup [`src/core/prompt-command-runtime.ts`]
+          - `listReqResetMatchingWorktreeRoots(...)`: enumerate registered and sibling generated worktrees targeted for deletion [`src/core/req-reset-command.ts`]
+            - `listReqResetRegisteredWorktreeRoots(...)`: enumerate registered git worktree roots [`src/core/req-reset-command.ts`]
+            - `listReqResetSiblingWorktreeRoots(...)`: enumerate sibling generated worktree directories [`src/core/req-reset-command.ts`]
+          - `deletePromptWorktree(...)`: force-remove one matching worktree plus its linked branch [`src/core/prompt-command-runtime.ts`]
+          - `listReqResetMatchingBranchNames(...)`: enumerate remaining matching branches after worktree deletion [`src/core/req-reset-command.ts`]
+          - `runCapture(...)`: run `git branch -D` for remaining matching branches [`src/core/req-reset-command.ts`]
+        - `rejectNonIdleReqCommand(...)`: abort non-`idle` replayed `req-references` or bundled prompt commands by transitioning workflow state to `error` [`src/index.ts`]
+        - `prepareReqReferencesCommandExecution(...)`: validate git state and resolve direct-write references execution facts for `req-references` [`src/core/req-references-command.ts`]
+          - `validatePromptGitState(...)`: validate clean runtime repository state while ignoring extension-owned debug-log artifacts [`src/core/prompt-command-runtime.ts`]
+        - `executeReqReferencesCommandExecution(...)`: regenerate `REFERENCES.md`, stage only the target file, create the fixed commit, and verify clean repository state for `req-references` [`src/core/req-references-command.ts`]
+          - `runReferences(...)`: generate summarize-equivalent markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
+          - `getGitAddTargetPath(...)`: resolve the staged path relative to the git root [`src/core/req-references-command.ts`]
+          - `runCapture(...)`: run git add, commit, and status subprocesses [`src/core/req-references-command.ts`]
+          - `listResidualGitStatusLines(...)`: confirm no residual git-status rows remain after commit [`src/core/req-references-command.ts`]
+            - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
         - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion plus conditional pi.dev governance guidance [`src/core/prompts.ts`]
         - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
           - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
           - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including effective worktree locking and the display-only config-path row [`src/index.ts`]
             - `formatProjectConfigPathForMenu(...)`: format the current config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
-          - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
+          - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions, keeping inline toggle rows open while rebuilding dependent rows in place [`src/core/settings-menu.ts`]
             - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
             - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
               - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
-            - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, and disable non-selectable actions [`src/core/settings-menu.ts`]
+            - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, disable non-selectable actions, and expose inline value cycles [`src/core/settings-menu.ts`]
+            - `setSettingsListSelectedIndex(...)`: restore the focused row during in-place menu rebuilds [`src/core/settings-menu.ts`]
+            - `getSettingsListSelectedIndex(...)`: expose the focused row for the offline bridge after inline toggle handling [`src/core/settings-menu.ts`]
           - `saveProjectConfig(...)`: persist menu updates on save-and-close [`src/index.ts`]
           - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
             - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
               - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
                 - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
                   - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
                   - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, consolidated elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, consolidated elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                 - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-          - `configureStaticCheckMenu(...)`: interactive guided static-check editor with per-language enable toggles [`src/index.ts`]
-          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
-          - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with dedicated event submenus [`src/index.ts`]
-            - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers [`src/index.ts`]
+          - `configureStaticCheckMenu(...)`: interactive guided static-check editor with in-place per-language enable toggles [`src/index.ts`]
+          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor whose per-tool toggle submenu keeps focus while cycling `on|off` values [`src/index.ts`]
+          - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with in-place global toggles, credential-locked enablement guidance text, persisted boot-sound edits, and dedicated event submenus [`src/index.ts`]
+            - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers, including boot-sound rows sourced from persisted config [`src/index.ts`]
               - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
-              - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows plus the shared event-submenu launcher [`src/index.ts`]
-            - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+              - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows with locked enablement guidance text plus the shared event-submenu launcher [`src/index.ts`]
+            - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor that keeps focus while toggling `on|off` rows for one notification transport [`src/index.ts`]
               - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`src/index.ts`]
               - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
               - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
@@ -572,13 +601,13 @@
               - `TokenCounter(...)`: lazily resolve `js-tiktoken` only when token counting executes [`src/core/token-counter.ts`]
                 - `loadJsTiktokenModule(...)`: convert missing tokenizer dependencies into deterministic `ReqError` failures [`src/core/token-counter.ts`]
               - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
-          - `runFilesReferences(...)`: execute the monolithic explicit-file references markdown runner [`src/core/tool-runner.ts`]
+          - `runFilesSummarize(...)`: execute the monolithic explicit-file summary markdown runner [`src/core/tool-runner.ts`]
             - `generateMarkdown(...)`: analyze requested files and concatenate Python-compatible reference markdown sections [`src/core/generate-markdown.ts`]
           - `runFilesCompress(...)`: execute the monolithic explicit-file compression markdown runner [`src/core/tool-runner.ts`]
             - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
           - `runFilesSearch(...)`: execute the monolithic explicit-file construct-search markdown runner [`src/core/tool-runner.ts`]
             - `searchConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
-          - `runReferences(...)`: execute the monolithic project references markdown runner [`src/core/tool-runner.ts`]
+          - `runSummarize(...)`: execute the monolithic project summary markdown runner [`src/core/tool-runner.ts`]
           - `runCompress(...)`: execute the monolithic project compression markdown runner [`src/core/tool-runner.ts`]
           - `runSearch(...)`: execute the monolithic project construct-search markdown runner [`src/core/tool-runner.ts`]
           - `runTokens(...)`: execute the monolithic canonical-doc token runner [`src/core/tool-runner.ts`]
@@ -587,6 +616,12 @@
           - `buildMonolithicToolExecuteResult(...)`: wrap runner stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
             - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
           - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
+        - `executeStatusTool(...)`: execute one CLI-style runner and wrap one status-only content block plus minimal execution details [`src/index.ts`]
+          - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
+            - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
+          - `buildMonolithicToolExecuteResult(...)`: wrap status stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
+            - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+          - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
     - `runSdkSmoke(...)`: replay offline `session_start`, probe the official SDK runtime, and compare inventories [`scripts/lib/sdk-smoke.ts`]
       - `replaySessionStart(...)`: capture the offline `session_start` contract [`scripts/lib/extension-debug-harness.ts`]
       - `probeSdkRuntime(...)`: load the official SDK runtime and extract extension-owned inventory [`scripts/lib/sdk-smoke.ts`]
@@ -631,24 +666,109 @@
     - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
       - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
         - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-    - `registerPromptCommands(...)`: register one command per prompt name using runtime prompt-front-matter descriptions, recover a live bootstrap cwd when stale command contexts still point at deleted worktrees, gate orchestration on `idle`, transition workflow state through `checking|running|error`, prepare a forked execution session with the active session directory, persist prompt metadata for switch-triggered rebinding, switch the active pi CLI session to the verified execution cwd before prompt handoff, append dedicated workflow-activation debug entries, capture the replacement-session context, dispatch the rendered prompt into the forked active session through that context, record `running` immediately after delivery handoff starts, and only then await the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed [`src/index.ts`]
+    - `registerReqResetCommand(...)`: register the specialized non-agentic `req-reset` command that accepts any workflow state, restores `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and returns to `idle` without worktree creation or LLM initialization [`src/index.ts`]
+      - `resolveReqResetPromptRequest(...)`: resolve the recoverable prompt execution plan from in-memory or persisted prompt state [`src/index.ts`]
+      - `resolveLiveBootstrapCwd(...)`: recover the live command cwd while preserving a worktree-backed session when it still exists [`src/index.ts`]
+      - `syncContextCwdMirror(...)`: best-effort realign the command-context `cwd` mirror to the recovered live cwd before reset execution [`src/index.ts`]
+      - `bootstrapRuntimePathState(...)`: refresh static runtime path facts from the recovered `base-path` before reset execution [`src/core/path-context.ts`]
+        - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the recovered `base-path` [`src/core/runtime-project-paths.ts`]
+      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for reset execution [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from the recovered runtime base path [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
+      - `setPiUsereqWorkflowState(...)`: update workflow state directly for running, idle, or error during `req-reset` execution [`src/core/extension-status.ts`]
+        - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
+            - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+            - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+            - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+            - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
+              - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
+            - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
+              - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
+              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+      - `prepareReqResetCommandExecution(...)`: derive the generated cleanup matcher, sibling parent path, and optional recovery plan for `req-reset` [`src/core/req-reset-command.ts`]
+        - `buildReqResetWorktreeNamePattern(...)`: derive the generated worktree-name matcher from the configured prefix plus repository basename [`src/core/req-reset-command.ts`]
+      - `executeReqResetCommandExecution(...)`: preserve transcript, restore `base-path`, and force-remove matching worktrees plus branches [`src/core/req-reset-command.ts`]
+        - `preservePromptCommandExecutionTranscript(...)`: copy execution-session records into the original session file when recovery plan data exists [`src/core/prompt-command-runtime.ts`]
+        - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path before cleanup [`src/core/prompt-command-runtime.ts`]
+        - `listReqResetMatchingWorktreeRoots(...)`: enumerate registered and sibling generated worktrees targeted for deletion [`src/core/req-reset-command.ts`]
+          - `listReqResetRegisteredWorktreeRoots(...)`: enumerate registered git worktree roots [`src/core/req-reset-command.ts`]
+          - `listReqResetSiblingWorktreeRoots(...)`: enumerate sibling generated worktree directories [`src/core/req-reset-command.ts`]
+        - `deletePromptWorktree(...)`: force-remove one matching worktree plus its linked branch [`src/core/prompt-command-runtime.ts`]
+        - `listReqResetMatchingBranchNames(...)`: enumerate remaining matching branches after worktree deletion [`src/core/req-reset-command.ts`]
+        - `runCapture(...)`: run `git branch -D` for remaining matching branches [`src/core/req-reset-command.ts`]
+      - `clearPersistedPromptCommandRuntimeState(...)`: clear persisted prompt workflow and reusable session context after successful recovery [`src/core/prompt-command-state.ts`]
+      - `notifyContextSafely(...)`: emit stale-safe success or error notifications after reset execution [`src/index.ts`]
+    - `registerReqReferencesCommand(...)`: register the specialized non-agentic `req-references` command that rejects non-`idle` invocation by transitioning workflow state to `error`, otherwise validates git state, regenerates `REFERENCES.md`, stages only that file, creates the fixed commit, verifies clean repository state, and returns to `idle` without worktree routing [`src/index.ts`]
+      - `rejectNonIdleReqCommand(...)`: abort non-`idle` `req-references` re-entry by transitioning workflow state to `error` [`src/index.ts`]
+      - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the command context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
+      - `syncContextCwdMirror(...)`: best-effort realign the command-context `cwd` mirror to the recovered live cwd before direct references execution [`src/index.ts`]
+      - `bootstrapRuntimePathState(...)`: refresh static and dynamic runtime path facts for direct references execution [`src/core/path-context.ts`]
+        - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the recovered live cwd [`src/core/runtime-project-paths.ts`]
+      - `getProjectBase(...)`: resolve project base from the recovered command-context cwd [`src/index.ts`]
+      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for the recovered command-context cwd [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from the recovered command-context cwd [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
+      - `setPiUsereqWorkflowState(...)`: update workflow state directly for checking, running, idle, or error during `req-references` execution [`src/core/extension-status.ts`]
+        - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
+            - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+            - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+            - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+            - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
+              - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
+            - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
+              - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
+              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+      - `prepareReqReferencesCommandExecution(...)`: validate git state and resolve the configured references target before direct execution [`src/core/req-references-command.ts`]
+        - `validatePromptGitState(...)`: validate clean runtime repository state through slash-command-owned git checks while ignoring extension-owned debug-log artifacts [`src/core/prompt-command-runtime.ts`]
+          - `throwPromptGitStatusError(...)`: normalize slash-command git-preflight failures [`src/core/prompt-command-runtime.ts`]
+      - `executeReqReferencesCommandExecution(...)`: regenerate `REFERENCES.md`, stage only the target file, create the fixed commit, and verify clean repository state [`src/core/req-references-command.ts`]
+        - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
+          - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
+        - `getGitAddTargetPath(...)`: resolve the staged path relative to the git root [`src/core/req-references-command.ts`]
+        - `runCapture(...)`: run git add, commit, and status subprocesses [`src/core/req-references-command.ts`]
+        - `listResidualGitStatusLines(...)`: confirm no residual git-status rows remain after commit [`src/core/req-references-command.ts`]
+          - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
+    - `registerPromptCommands(...)`: register one bundled prompt-backed command per prompt name using runtime prompt level-one heading descriptions, reject non-`idle` re-entry by transitioning workflow state to `error`, recover a live bootstrap cwd when stale command contexts still point at deleted worktrees, otherwise transition workflow state through `checking|running|error`, prepare a forked execution session with the active session directory, persist prompt metadata for switch-triggered rebinding, switch the active pi CLI session to the verified execution cwd before prompt handoff, append dedicated workflow-activation debug entries, capture the replacement-session context, dispatch the rendered prompt into the forked active session through that context, record `running` immediately after delivery handoff starts, and only then await the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed [`src/index.ts`]
+      - `rejectNonIdleReqCommand(...)`: abort non-`idle` bundled prompt re-entry by transitioning workflow state to `error` [`src/index.ts`]
       - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the command context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
       - `syncContextCwdMirror(...)`: best-effort realign the command-context `cwd` mirror to the recovered live cwd before prompt preflight [`src/index.ts`]
       - `transitionPromptWorkflowState(...)`: update workflow state and append gated `workflow_state` debug entries only after the transition completes [`src/index.ts`]
         - `setPiUsereqWorkflowState(...)`: update workflow state before prompt preflight, prompt handoff, or command-side failure [`src/core/extension-status.ts`]
         - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
-        - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+        - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
           - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
           - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
             - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
               - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
                 - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
                 - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
             - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
             - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
             - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
-            - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+            - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
               - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
             - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
               - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
@@ -735,7 +855,7 @@
           - `cleanupPromptWorktreeCreation(...)`: remove registered worktree entries, leftover directories, and matching branches [`src/core/prompt-command-runtime.ts`]
             - `promptWorktreeRegistered(...)`: test whether the sibling worktree remains registered [`src/core/prompt-command-runtime.ts`]
             - `promptWorktreeBranchExists(...)`: test whether the matching branch remains present [`src/core/prompt-command-runtime.ts`]
-    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families, token-optimized payload builders, and compact-plus-expanded custom result renderers [`src/index.ts`]
+    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families, the status-only references writer, token-optimized payload builders, and compact-plus-expanded custom result renderers [`src/index.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need bundled assets [`src/core/resources.ts`]
         - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
           - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
@@ -756,10 +876,10 @@
       - `buildStructuredToolRenderResult(...)`: attach compact invocation-parameter summaries and expanded monolithic result renderers to every agent tool [`src/index.ts`]
       - `executeMonolithicTool(...)`: execute one CLI-style runner and wrap one monolithic content block plus minimal execution details [`src/index.ts`]
         - `runFilesTokens(...)`: execute the monolithic token pack-summary runner [`src/core/tool-runner.ts`]
-        - `runFilesReferences(...)`: execute the monolithic explicit-file references markdown runner [`src/core/tool-runner.ts`]
+        - `runFilesSummarize(...)`: execute the monolithic explicit-file summary markdown runner [`src/core/tool-runner.ts`]
         - `runFilesCompress(...)`: execute the monolithic explicit-file compression markdown runner [`src/core/tool-runner.ts`]
         - `runFilesSearch(...)`: execute the monolithic explicit-file construct-search markdown runner [`src/core/tool-runner.ts`]
-        - `runReferences(...)`: execute the monolithic project references markdown runner [`src/core/tool-runner.ts`]
+        - `runSummarize(...)`: execute the monolithic project summary markdown runner [`src/core/tool-runner.ts`]
         - `runCompress(...)`: execute the monolithic project compression markdown runner [`src/core/tool-runner.ts`]
         - `runSearch(...)`: execute the monolithic project construct-search markdown runner [`src/core/tool-runner.ts`]
         - `runTokens(...)`: execute the monolithic canonical-doc token runner [`src/core/tool-runner.ts`]
@@ -768,6 +888,12 @@
         - `buildMonolithicToolExecuteResult(...)`: wrap runner stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
           - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
         - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
+      - `executeStatusTool(...)`: execute one CLI-style runner and wrap one status-only content block plus minimal execution details [`src/index.ts`]
+        - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
+          - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
+        - `buildMonolithicToolExecuteResult(...)`: wrap status stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
+          - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
     - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
       - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]
       - `configurePiUsereq(...)`: serve the inline `show-config` action inside the shared settings-menu flow [`src/index.ts`]
@@ -784,7 +910,7 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-    - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
+    - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut and cycle only the active runtime sound level without persisting boot config [`src/index.ts`]
       - `getProcessCwdSafe(...)`: resolve a fallback-safe process cwd for extension-load registration [`src/index.ts`]
       - `loadProjectConfig(...)`: load config for shortcut registration [`src/index.ts`]
         - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
@@ -796,8 +922,12 @@
           - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
           - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
           - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
+      - `getPiUsereqRuntimeSoundLevel(...)`: read the active runtime sound level before shortcut cycling [`src/core/extension-status.ts`]
+      - `cyclePiNotifySoundLevel(...)`: compute the next active runtime sound level [`src/core/pi-notify.ts`]
+      - `setPiUsereqRuntimeSoundLevel(...)`: store the cycled runtime sound level and refresh the footer [`src/core/extension-status.ts`]
+        - `renderPiUsereqStatus(...)`: refresh the single-line footer after shortcut-driven runtime sound changes [`src/core/extension-status.ts`]
     - `registerExtensionStatusHooks(...)`: register shared wrappers for lifecycle telemetry hooks and suppress the documented stale-extension-context callbacks that can arrive after successful session replacement [`src/index.ts`]
-      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers, tool-result debug logging, dedicated workflow-closure plus shutdown diagnostics built from pre-shutdown prompt snapshots, workflow-state transitions, recover a live bootstrap cwd during `session_start` when stale context mirrors still point at deleted worktrees, matched-success prompt-command restoration to `base-path` plus merge and worktree deletion, stale-safe closure notifications, and matched-failure base-path restoration plus closure-error notification using persisted replacement-session contexts when event hooks omit `switchSession()` [`src/index.ts`]
+      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers, tool-result debug logging, dedicated workflow-closure plus shutdown diagnostics built from pre-shutdown prompt snapshots, workflow-state transitions, recover a live bootstrap cwd during `session_start` when stale context mirrors still point at deleted worktrees, matched-success prompt-command restoration to `base-path` plus stash-assisted merge and worktree deletion even after a busy-command rejection moved workflow state to `error`, warning-only closure notifications when restored `base-path` changes are reapplied, stale-safe closure notifications, and matched-failure base-path restoration plus closure-error notification using persisted replacement-session contexts when event hooks omit `switchSession()` [`src/index.ts`]
         - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the startup context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
         - `syncContextCwdMirror(...)`: best-effort realign the startup context `cwd` mirror to the recovered live cwd before startup config loads [`src/index.ts`]
         - `loadProjectConfig(...)`: session-start configuration load from the recovered live cwd [`src/index.ts`]
@@ -815,7 +945,7 @@
         - `resolveDebugProjectBase(...)`: prefer static `base-path` for debug-log writes during worktree-backed prompt runs and recover a live bootstrap cwd when no prompt plan is active [`src/index.ts`]
         - `notifyContextSafely(...)`: suppress stale replacement-context notification failures after session replacement while preserving closure progress [`src/index.ts`]
         - `logDebugToolExecution(...)`: append selected tool-result debug entries [`src/core/debug-runtime.ts`]
-        - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore persisted elapsed timers on `session_start`, restore persisted prompt-command state when the active session matches the forked execution session, resynchronize that state on later lifecycle hooks after switch-triggered rebinding, preserve in-memory prompt-command state plus process-scoped persistence across `session_shutdown`, accumulate completed runtime, and render status text while tolerating stale replacement contexts [`src/core/extension-status.ts`]
+        - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore persisted elapsed timers on `session_start`, load the active runtime sound level from persisted config on `session_start`, restore persisted prompt-command state when the active session matches the forked execution session, resynchronize that state on later lifecycle hooks after switch-triggered rebinding, preserve in-memory prompt-command state plus process-scoped persistence across `session_shutdown`, accumulate completed runtime, and render status text while tolerating stale replacement contexts [`src/core/extension-status.ts`]
           - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
           - `shouldResetElapsedStateOnSessionStart(...)`: detect `startup|reload` reset boundaries [`src/core/extension-status.ts`]
           - `resetElapsedState(...)`: clear in-memory and persisted completed timers [`src/core/extension-status.ts`]
@@ -830,18 +960,18 @@
           - `persistPromptCommandState(...)`: mirror workflow state plus pending or active prompt execution plans into process-scoped persistence [`src/core/extension-status.ts`]
             - `writePersistedPromptCommandRuntimeState(...)`: store workflow state plus pending or active prompt execution plans on `globalThis` [`src/core/prompt-command-state.ts`]
           - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
             - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
               - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
                 - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
                   - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
                   - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
               - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
                 - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
@@ -890,16 +1020,18 @@
         - `logPromptWorkflowEvent(...)`: append selected workflow-closure and workflow-session-shutdown debug entries [`src/index.ts`]
         - `transitionPromptWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration, and append gated workflow-state debug entries immediately after each transition [`src/index.ts`]
           - `setPiUsereqWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
           - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
-        - `finalizePromptCommandExecution(...)`: verify persisted execution-session header metadata plus live worktree artifacts, synchronize the successful execution transcript into the restored base session, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, merge the matched successful worktree branch with `--ff-only` from `base-path`, delete the worktree and branch after merge success, and append selected merge plus workflow-restore debug entries [`src/core/prompt-command-runtime.ts`]
+        - `finalizePromptCommandExecution(...)`: verify persisted execution-session header metadata plus live worktree artifacts, synchronize the successful execution transcript into the restored base session, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, execute the matched successful stash-assisted `base-path` merge sequence, delete the worktree and branch after merge success, and carry a warning-only closure result when restored `base-path` changes are reapplied [`src/core/prompt-command-runtime.ts`]
           - `verifyPromptCommandClosureArtifacts(...)`: verify execution-session header cwd, worktree registration, branch presence, and worktree-path existence without requiring worktree-session reactivation after prompt end [`src/core/prompt-command-runtime.ts`]
           - `preservePromptCommandExecutionTranscript(...)`: append or materialize the restored base-session transcript from the execution-session JSONL before the base-path switch [`src/core/prompt-command-runtime.ts`]
             - `readPromptSessionJsonLines(...)`: parse execution-session JSONL records and parse original-session JSONL records when a persisted base session already exists [`src/core/prompt-command-runtime.ts`]
             - `readPromptSessionFileCwd(...)`: verify the restored session header cwd equals `base-path` after transcript synchronization [`src/core/prompt-command-runtime.ts`]
             - `readPromptSessionJsonLines(...)`: re-read the restored base session and verify copied execution entry identifiers [`src/core/prompt-command-runtime.ts`]
           - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path, reuse the persisted replacement-session context keyed by the execution-session file, append optional workflow-restore debug entries, clear active worktree path facts, and realign the live `ctx.cwd` mirror before merge or merge-abort return [`src/core/prompt-command-runtime.ts`]
-          - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful fast-forward merge [`src/core/prompt-command-runtime.ts`]
+          - `finalizePromptCommandMerge(...)`: inspect tracked `base-path` changes, run `git stash` plus `git stash pop` around the existing `--ff-only` merge when tracked changes exist, emit a warning-only merge result after reapplying local changes, and append selected merge debug entries [`src/core/prompt-command-runtime.ts`]
+            - `listPromptTrackedBasePathChanges(...)`: parse tracked staged or unstaged `git status --porcelain` rows and ignore untracked or ignored rows before stash-assisted merge selection [`src/core/prompt-command-runtime.ts`]
+          - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful stash-assisted fast-forward merge [`src/core/prompt-command-runtime.ts`]
         - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path when interrupted, failed, or unmatched prompt-end events skip merge and retain the worktree for manual recovery, reusing the persisted replacement-session context when lifecycle hooks omit `switchSession()` [`src/core/prompt-command-runtime.ts`]
           - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
             - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
@@ -954,11 +1086,13 @@
       - `formatDebugMenuSummary(...)`: summarize global debug mode plus selected tool and prompt counts [`src/index.ts`]
       - `formatProjectConfigPathForMenu(...)`: format the current config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
       - `buildTerminalSettingsMenuChoices(...)`: append the canonical `Reset defaults` row without `Save and close` [`src/index.ts`]
-    - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
+    - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions, keeping inline toggle rows open while rebuilding dependent rows in place [`src/core/settings-menu.ts`]
       - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
       - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
         - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
-      - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, and disable non-selectable actions [`src/core/settings-menu.ts`]
+      - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, disable non-selectable actions, and expose inline value cycles [`src/core/settings-menu.ts`]
+      - `setSettingsListSelectedIndex(...)`: restore the focused row during in-place menu rebuilds [`src/core/settings-menu.ts`]
+      - `getSettingsListSelectedIndex(...)`: expose the focused row for the offline bridge after inline toggle handling [`src/core/settings-menu.ts`]
     - `persistConfigChange(...)`: persist config immediately after every settings mutation and refresh status rendering [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `saveConfig(...)`: persist config JSON [`src/core/config.ts`]
@@ -967,23 +1101,23 @@
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `getProjectConfigPath(...)`: resolve the persisted config path [`src/core/config.ts`]
     - `setPiUsereqStatusConfig(...)`: cache the just-saved docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-    - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: refresh live context usage and render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
       - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
       - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
         - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
           - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
             - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
             - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
         - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
         - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
         - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
-        - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+        - `formatContextUsageBar(...)`: render the icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`src/core/extension-status.ts`]
           - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
         - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
           - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
           - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-    - `configureStaticCheckMenu(...)`: interactive guided static-check editor with per-language enable toggles [`src/index.ts`]
+    - `configureStaticCheckMenu(...)`: interactive guided static-check editor with in-place per-language enable toggles [`src/index.ts`]
       - `getStaticCheckLanguageConfigForMenu(...)`: resolve a menu-facing per-language static-check object [`src/index.ts`]
       - `countConfiguredStaticCheckLanguages(...)`: count languages that retain checker entries [`src/index.ts`]
       - `countEnabledStaticCheckLanguages(...)`: count languages whose enable flag is on [`src/index.ts`]
@@ -1005,7 +1139,7 @@
           - `createStaticCheckLanguageConfig(...)`: clone checker entries and derive the enable flag [`src/core/config.ts`]
       - `createStaticCheckLanguageConfig(...)`: create empty per-language configs for toggle and removal flows [`src/core/config.ts`]
       - `shellSplit(...)`: parse optional parameter input [`src/core/utils.ts`]
-    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
+    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor whose per-tool toggle submenu keeps focus while cycling `on|off` values [`src/index.ts`]
       - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
         - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
           - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
@@ -1018,25 +1152,25 @@
           - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
       - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus the value-less terminal reset action [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-    - `configureDebugMenu(...)`: interactive debug editor for global enablement, log path, status-change logging, dedicated workflow-event logging, workflow filters, reset confirmation, and per-tool plus per-prompt toggles [`src/index.ts`]
+    - `configureDebugMenu(...)`: interactive debug editor with in-place enable or disable toggles, workflow filters, reset confirmation, and per-tool plus per-prompt selectors [`src/index.ts`]
       - `buildDebugMenuChoices(...)`: serialize global debug controls, workflow-event toggles, canonical tool and prompt toggles, and the value-less terminal reset row [`src/index.ts`]
         - `buildDebugMenuChoice(...)`: dim and disable locked debug rows while global debug is off [`src/index.ts`]
         - `getDebugToolToggleNames(...)`: enumerate debuggable tool names in canonical grouped order [`src/index.ts`]
       - `selectDebugLogOnStatus(...)`: select one explicit workflow-state filter or `any` [`src/index.ts`]
       - `confirmResetChanges(...)`: require explicit approval before applying reset mutations [`src/index.ts`]
       - `resetDebugConfigToDefaults(...)`: restore the debug configuration subtree to documented defaults [`src/index.ts`]
-    - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with credential-locked enablement, immediate-save mutations, reset confirmation, and dedicated event submenus [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and the value-less terminal reset row [`src/index.ts`]
+    - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with in-place global toggles, credential-locked enablement guidance text, immediate-save persisted boot-sound mutations, reset confirmation, and dedicated event submenus [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and the value-less terminal reset row, including boot-sound rows sourced from persisted config [`src/index.ts`]
         - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
-        - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows with locked enablement plus the shared event-submenu launcher [`src/index.ts`]
+        - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows with locked enablement guidance text plus the shared event-submenu launcher [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row [`src/index.ts`]
-      - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+      - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor that keeps focus while toggling `on|off` rows for one notification transport [`src/index.ts`]
         - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`src/index.ts`]
         - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
         - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
         - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
       - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
-      - `selectPiNotifySoundLevel(...)`: present the `Enable sound` selector with the subtree-local reset action [`src/index.ts`]
+      - `selectPiNotifySoundLevel(...)`: present the `Enable sound (boot value)` selector while preserving the active runtime sound level [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
       - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with the subtree-local reset action [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]

package/scripts/lib/extension-debug-harness.ts

@@ -211,10 +211,10 @@ const PROMPT_COMMAND_EXAMPLES: Record<string, string> = {
  */
 const TOOL_EXAMPLES: Record<string, string> = {
   "files-tokens": `npm run debug:ext:tool -- --name files-tokens --params '{"files":["pi-usereq/docs/REQUIREMENTS.md","pi-usereq/docs/WORKFLOW.md"]}' --cwd . --format json`,
-  "files-references": `npm run debug:ext:tool -- --name files-references --params '{"files":["src/index.ts","src/core/tool-runner.ts"]}' --cwd . --format pretty`,
+  "files-summarize": `npm run debug:ext:tool -- --name files-summarize --params '{"files":["src/index.ts","src/core/tool-runner.ts"]}' --cwd . --format pretty`,
   "files-compress": `npm run debug:ext:tool -- --name files-compress --params '{"files":["src/index.ts"],"enableLineNumbers":true}' --cwd . --format json`,
   "files-search": `npm run debug:ext:tool -- --name files-search --params '{"tag":"FUNCTION|METHOD","pattern":"^run","files":["src/core/tool-runner.ts"],"enableLineNumbers":true}' --cwd . --format pretty`,
-  references: "npm run debug:ext:tool -- --name references --cwd . --format pretty",
+  summarize: "npm run debug:ext:tool -- --name summarize --cwd . --format pretty",
   compress: `npm run debug:ext:tool -- --name compress --params '{"enableLineNumbers":true}' --cwd . --format json`,
   search: `npm run debug:ext:tool -- --name search --params '{"tag":"FUNCTION","pattern":"^run","enableLineNumbers":true}' --cwd . --format pretty`,
   tokens: "npm run debug:ext:tool -- --name tokens --cwd . --format json",

package/scripts/tool-args-to-params.ts

@@ -97,7 +97,7 @@ function takeBooleanFlag(tokens: string[], flag: string): { tokens: string[]; pr
 export function buildToolParamsFromArgsText(toolName: string, argsText: string): Record<string, unknown> {
   const tokens = shellSplit(argsText);
   switch (toolName) {
-    case "references":
+    case "summarize":
     case "tokens":
     case "static-check":
       if (tokens.length !== 0) {
@@ -105,7 +105,7 @@ export function buildToolParamsFromArgsText(toolName: string, argsText: string):
       }
       return {};
     case "files-tokens":
-    case "files-references":
+    case "files-summarize":
     case "files-static-check":
       return { files: tokens };
     case "files-compress": {