pi-usereq 0.4.0 → 0.6.0

package/{req → pi-usereq}/docs/WORKFLOW.md

@@ -207,23 +207,13 @@
               - `formatResult(...)`: render compressed output [`src/core/compress.ts`]
         - `formatAvailableTags(...)`: render supported tag index for failure paths [`src/core/find-constructs.ts`]
     - `runStaticCheck(...)`: branch `--test-static-check`; invoke static-check test driver [`src/core/static-check.ts`]
-      - `StaticCheckBase.run(...)`: iterate resolved files for dummy driver [`src/core/static-check.ts`]
+      - `StaticCheckBase.run(...)`: iterate resolved files for debug dummy driver [`src/core/static-check.ts`]
         - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-      - `StaticCheckPylance.run(...)`: iterate resolved files for pyright path [`src/core/static-check.ts`]
-        - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
-          - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-            - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-      - `StaticCheckRuff.run(...)`: iterate resolved files for ruff path [`src/core/static-check.ts`]
-        - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
-          - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-            - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-      - `StaticCheckCommand.run(...)`: iterate resolved files for generic command path [`src/core/static-check.ts`]
+      - `StaticCheckCommand.run(...)`: iterate resolved files for external command path [`src/core/static-check.ts`]
+        - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+          - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
         - `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`]
@@ -234,24 +224,14 @@
         - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
           - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
       - `dispatchStaticCheckForFile(...)`: instantiate checker by configured module [`src/core/static-check.ts`]
-        - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
-        - `StaticCheckBase.run(...)`: execute dummy checker [`src/core/static-check.ts`]
+        - `formatDispatchStaticCheckModules(...)`: render valid persisted modules for unknown-module failures [`src/core/static-check.ts`]
+        - `StaticCheckBase.run(...)`: execute debug dummy checker [`src/core/static-check.ts`]
           - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-        - `StaticCheckPylance.run(...)`: execute pyright checker [`src/core/static-check.ts`]
-          - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
-            - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-              - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-        - `StaticCheckRuff.run(...)`: execute ruff checker [`src/core/static-check.ts`]
-          - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
-            - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-              - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-        - `StaticCheckCommand.run(...)`: execute generic command checker [`src/core/static-check.ts`]
+        - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
+          - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
           - `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`]
@@ -388,24 +368,14 @@
           - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
         - `dispatchStaticCheckForFile(...)`: instantiate checker by configured module [`src/core/static-check.ts`]
-          - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
-          - `StaticCheckBase.run(...)`: execute dummy checker [`src/core/static-check.ts`]
+          - `formatDispatchStaticCheckModules(...)`: render valid persisted modules for unknown-module failures [`src/core/static-check.ts`]
+          - `StaticCheckBase.run(...)`: execute debug dummy checker [`src/core/static-check.ts`]
             - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-          - `StaticCheckPylance.run(...)`: execute pyright checker [`src/core/static-check.ts`]
-            - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
-              - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-                - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-          - `StaticCheckRuff.run(...)`: execute ruff checker [`src/core/static-check.ts`]
-            - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
-              - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
-                - `findExecutable(...)`: resolve executable on `PATH` [`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`]
-          - `StaticCheckCommand.run(...)`: execute generic command checker [`src/core/static-check.ts`]
+          - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
+            - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+              - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
             - `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`]
@@ -477,7 +447,7 @@
 - External Boundaries:
   - Node process APIs for argv, cwd, environment, stdout, stderr, and exit code.
   - Filesystem access for config, docs discovery, source reads, and bundled resources.
-  - Git, bash, pyright, ruff, and arbitrary configured checker subprocesses via child-process execution.
+  - Git, bash, and arbitrary configured checker subprocesses via child-process execution.
 
 ### `PROC:req-debug`
 - Entrypoints:
@@ -587,19 +557,21 @@
             - `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, timers, and rendered status text [`src/core/extension-status.ts`]
+          - `updateExtensionStatus(...)`: refresh stored context usage, elapsed timers, cumulative runtime, and rendered 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`]
-            - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed-time ticker [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the git/base/docs/tests/src/tools/context/elapsed/last/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/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`]
-              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`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 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                  - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+                - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+                  - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
                   - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
-                - `formatStatusDuration(...)`: render `M:SS` durations [`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`]
                 - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
           - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
             - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
@@ -627,19 +599,24 @@
         - `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 plus the display-only config-path row [`src/index.ts`]
+            - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
           - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`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 and apply optional dim value tones [`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 docs/tests/src/tools/context/elapsed/last/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/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`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`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 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`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`]
               - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
           - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
           - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
@@ -664,17 +641,16 @@
               - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
               - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
                 - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-          - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
         - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
           - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+        - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
           - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
           - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
           - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
         - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+        - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
           - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
             - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
             - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -684,7 +660,7 @@
         - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
         - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
           - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-        - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+        - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
           - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
           - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
           - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -695,20 +671,20 @@
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
         - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
         - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-        - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+        - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
         - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
         - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
         - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-        - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
         - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-        - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-        - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+        - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-        - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
         - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-        - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-        - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+        - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
         - `normalizeToolFailure(...)`: convert `ReqError` failures into structured 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`]
@@ -754,7 +730,7 @@
     - `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 [`src/index.ts`]
+    - `registerPromptCommands(...)`: register one command per prompt name and cache prompt metadata for later successful-completion notifications [`src/index.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before prompt render [`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`]
@@ -786,6 +762,7 @@
           - `buildPiDevConformanceBlock(...)`: resolve manifest-gated pi.dev review and API-compliance rules [`src/core/prompts.ts`]
         - `adaptPromptForInternalTools(...)`: rewrite tool names for internal wrappers [`src/core/prompts.ts`]
       - `deliverPromptCommand(...)`: dispatch the rendered prompt into the current active session [`src/index.ts`]
+        - `statusController.state.pendingPromptRequest`: cache the prompt command name and raw `%%ARGS%%` payload for the next successful completion [`src/core/extension-status.ts`]
         - External boundaries: `pi.sendUserMessage(...)` delivers the rendered prompt payload.
     - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families and agent-oriented payload builders [`src/index.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need bundled assets [`src/core/resources.ts`]
@@ -802,16 +779,10 @@
           - `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`]
-      - `buildSharedRuntimePathFacts(...)`: derive shared runtime path facts for path, git, docs, worktree, and static-check payloads [`src/index.ts`]
-        - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
-          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-          - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
-        - `buildRuntimePathFacts(...)`: convert runtime paths into payload-facing path strings [`src/core/path-context.ts`]
-          - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
       - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
       - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-      - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
-      - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
+      - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+      - `buildTokenToolPayload(...)`: construct token-optimized token JSON with direct-access source facts and metrics [`src/core/token-counter.ts`]
         - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
         - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
           - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
@@ -822,17 +793,16 @@
             - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
             - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
               - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-        - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
       - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
         - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+      - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
         - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
         - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
         - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
       - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+      - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
         - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
           - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
           - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -842,7 +812,7 @@
       - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
       - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
         - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-      - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+      - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
         - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
         - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
         - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -854,16 +824,16 @@
       - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
       - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
       - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-      - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
       - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-      - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-      - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+      - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-      - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
       - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-      - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-      - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+      - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
       - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
     - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
       - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]
@@ -911,20 +881,23 @@
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
           - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
         - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
-        - `updateExtensionStatus(...)`: refresh stored context usage, timers, and rendered status text [`src/core/extension-status.ts`]
+        - `updateExtensionStatus(...)`: refresh stored context usage, elapsed timers, prompt-request state, cumulative runtime, and rendered status text [`src/core/extension-status.ts`]
           - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
-          - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed-time ticker [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the docs/tests/src/tools/context/elapsed/last/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover 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`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable 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 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+                - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
                 - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
-              - `formatStatusDuration(...)`: render `M:SS` durations [`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`]
               - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-        - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
+              - `formatPiNotifyPushoverStatus(...)`: serialize the dedicated Pushover enable flag for the footer [`src/core/pi-notify.ts`]
+        - `runPiNotifyEffects(...)`: dispatch configured terminal beeps, successful-run sound hooks, and optional Pushover API requests on `agent_end` [`src/core/pi-notify.ts`]
           - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
             - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
           - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
@@ -939,6 +912,10 @@
             - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
               - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
               - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+          - `runPiNotifyPushoverRequest(...)`: POST the successful prompt payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
+            - `buildPiNotifyPushoverPayload(...)`: serialize token, user, title, priority, and message fields [`src/core/pi-notify.ts`]
+            - `buildPiNotifyPushoverTitle(...)`: compose `<prompt> @ <base-path> [<time>]` for successful completion [`src/core/pi-notify.ts`]
+            - `buildPiNotifyPushoverBody(...)`: reuse the raw prompt argument payload [`src/core/pi-notify.ts`]
   - `configurePiUsereq(...)`: interactive configuration menu runtime root [`src/index.ts`]
     - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
@@ -951,24 +928,29 @@
       - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
         - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
     - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions plus the display-only config-path row [`src/index.ts`]
+      - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
     - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`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 and apply optional dim value tones [`src/core/settings-menu.ts`]
     - `saveProjectConfig(...)`: persist config on save-and-close [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `saveConfig(...)`: persist config JSON [`src/core/config.ts`]
         - `getProjectConfigPath(...)`: resolve config file 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 git/base/docs/tests/src/tools/context/elapsed/last/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover 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`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable 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 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-          - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+        - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+          - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
           - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
-        - `formatStatusDuration(...)`: render `M:SS` durations [`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`]
         - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
     - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
       - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
@@ -979,9 +961,9 @@
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
       - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with configured counts [`src/index.ts`]
       - `shellSplit(...)`: parse optional parameter input [`src/core/utils.ts`]
-      - `parseEnableStaticCheck(...)`: parse `LANG=MODULE[,CMD[,PARAM...]]` specification [`src/core/static-check.ts`]
+      - `parseEnableStaticCheck(...)`: parse `LANG=Command,CMD[,PARAM...]` specification [`src/core/static-check.ts`]
         - `splitCsvLikeTokens(...)`: split comma-like spec payload with quoting support [`src/core/static-check.ts`]
-        - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
+        - `formatStaticCheckModules(...)`: render valid user modules for error paths [`src/core/static-check.ts`]
     - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
       - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
         - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
@@ -1001,8 +983,11 @@
       - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows [`src/index.ts`]
         - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
     - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize notification actions for the shared settings menu [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize notification actions plus the nested Pushover submenu entry for the shared settings menu [`src/index.ts`]
       - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
+      - `configurePiNotifyPushoverMenu(...)`: interactive Pushover editor nested under the notifications menu [`src/index.ts`]
+        - `buildPiNotifyPushoverMenuChoices(...)`: serialize Pushover global-disable, enable, credential, and priority actions [`src/index.ts`]
+        - `selectPiNotifyPushoverPriority(...)`: present the `0=Normal` and `1=High Priority` selector [`src/index.ts`]
     - `getDefaultConfig(...)`: restore default config on reset [`src/core/config.ts`]
       - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
     - `applyConfiguredPiUsereqTools(...)`: re-apply active tools after reset [`src/index.ts`]