pi-usereq 0.11.0 → 0.12.0

package/pi-usereq/docs/REFERENCES.md

@@ -23,7 +23,8 @@
     │   ├── prompt-command-runtime.ts
     │   ├── prompt-command-state.ts
     │   ├── prompts.ts
-    │   ├── reference-payload.ts
+    │   ├── req-references-command.ts
+    │   ├── req-reset-command.ts
     │   ├── resources.ts
     │   ├── runtime-project-paths.ts
     │   ├── settings-menu.ts
@@ -1127,7 +1128,7 @@ import {
 
 ---
 
-# extension-status.ts | TypeScript | 823L | 43 symbols | 5 imports | 45 comments
+# extension-status.ts | TypeScript | 880L | 46 symbols | 6 imports | 48 comments
 > Path: `src/core/extension-status.ts`
 - @brief Tracks pi-usereq extension status state and renders status-bar telemetry.
 - @details Centralizes hook interception, context-usage snapshots, active-branch lookup, run timing, and deterministic status-bar formatting for the pi-usereq extension. Runtime
@@ -1139,6 +1140,7 @@ scheduling through exported controller helpers.
 ```
 import type {
 import type { UseReqConfig } from "./config.js";
+import type { PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 import {
 import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
@@ -1146,120 +1148,120 @@ import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
 
 ## Definitions
 
-- type `type StatusForegroundColor = Extract<` (L30)
+- type `type StatusForegroundColor = Extract<` (L31)
 - @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
 - @details Restricts the status formatter to documented pi theme tokens so the
 status bar remains compatible with the active CLI theme schema. Compile-time
 only and introduces no runtime cost.
-### iface `interface RawStatusTheme` (L40-42)
+### iface `interface RawStatusTheme` (L41-43)
 - @brief Describes the raw theme capabilities required for status rendering.
 - @details Accepts the `ctx.ui.theme` foreground renderer used by the
 single-line footer. Compile-time only and introduces no runtime cost.
 
-### iface `interface StatusThemeAdapter` (L50-55)
+### iface `interface StatusThemeAdapter` (L51-56)
 - @brief Describes the normalized theme adapter used by status formatters.
 - @details Exposes deterministic label, value, foreground, and separator
 renderers so status text generation stays independent from the raw theme API.
 Compile-time only and introduces no runtime cost.
 
-- type `export type PiUsereqStatusHookName = (typeof PI_USEREQ_STATUS_HOOK_NAMES)[number];` (L98)
+- type `export type PiUsereqStatusHookName = (typeof PI_USEREQ_STATUS_HOOK_NAMES)[number];` (L99)
 - @brief Represents one hook name handled by the pi-usereq status controller.
 - @details Narrows hook registration and event-update calls to the canonical
 intercepted-hook set. Compile-time only and introduces no runtime cost.
-- type `export type PiUsereqPromptRequest = PromptCommandExecutionPlan;` (L104)
+- type `export type PiUsereqPromptRequest = PromptCommandExecutionPlan;` (L105)
 - @brief Describes one prompt request tracked across extension command delivery and runtime execution.
 - @details Reuses the prepared prompt-command execution plan so status rendering and prompt-end side effects can recover the original project base, active execution base, and optional worktree metadata for the current prompt run. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging" | "error";` (L110)
+- type `export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging" | "error";` (L111)
 - @brief Represents one prompt-orchestration workflow state displayed in the status bar.
 - @details Narrows workflow tracking to the documented `idle`, `checking`, `running`, `merging`, and `error` states reused by prompt-command gating, prompt-end orchestration, and status rendering. Compile-time only and introduces no runtime cost.
-### iface `export interface PiUsereqStatusState` (L116-124)
+### iface `export interface PiUsereqStatusState` (L117-126)
 - @brief Stores the mutable runtime facts displayed by the status bar.
-- @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
+- @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, the in-memory runtime sound level, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
 
-### iface `export interface PiUsereqStatusController` (L133-138)
+### iface `export interface PiUsereqStatusController` (L135-140)
 - @brief Stores the controller state required for event-driven status updates.
 - @details Keeps the mutable status snapshot, the current configuration, the
 latest extension context used for rendering, and the interval handle used
 for live elapsed-time refreshes. Compile-time only and introduces no runtime
 cost.
 
-### iface `interface PiUsereqStatusPersistenceStore` (L144-147)
+### iface `interface PiUsereqStatusPersistenceStore` (L146-149)
 - @brief Stores the process-scoped elapsed-timer snapshot reused across session replacement.
 - @details Preserves only the latest completed duration and accumulated completed runtime so `/new`, `/resume`, and `/fork` can restore elapsed counters after the extension runtime is rebound. Compile-time only and introduces no runtime cost.
 
-### fn `function getPiUsereqStatusPersistenceStore(): PiUsereqStatusPersistenceStore` (L161-170)
+### fn `function getPiUsereqStatusPersistenceStore(): PiUsereqStatusPersistenceStore` (L163-172)
 - @brief Returns the process-scoped elapsed-timer persistence store.
 - @details Lazily initializes one internal `globalThis` record because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, but the hosting process persists across those operations. Runtime is O(1). Side effect: initializes internal process-scoped state on first access.
 - @return {PiUsereqStatusPersistenceStore} Mutable persistence record.
 - @note Design rationale: required to preserve elapsed counters across session replacement without writing session-global menu state into project configuration.
 
-### fn `function restorePersistedElapsedState(state: PiUsereqStatusState): void` (L178-182)
+### fn `function restorePersistedElapsedState(state: PiUsereqStatusState): void` (L180-184)
 - @brief Restores persisted elapsed counters into one mutable status snapshot.
 - @details Copies the process-scoped last-run and accumulated completed durations into the supplied controller state so rebinding events can continue showing prior counters. Runtime is O(1). Side effect: mutates `state`.
 - @param[in,out] state {PiUsereqStatusState} Mutable status state.
 - @return {void} No return value.
 
-### fn `function persistElapsedState(state: PiUsereqStatusState): void` (L190-194)
+### fn `function persistElapsedState(state: PiUsereqStatusState): void` (L192-196)
 - @brief Persists elapsed counters from one mutable status snapshot.
 - @details Copies the current last-run and accumulated completed durations into the process-scoped store so later extension instances can restore them after session replacement. Runtime is O(1). Side effect: mutates internal process-scoped state.
 - @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
 - @return {void} No return value.
 
-### fn `function persistPromptCommandState(state: PiUsereqStatusState): void` (L202-208)
+### fn `function persistPromptCommandState(state: PiUsereqStatusState): void` (L204-210)
 - @brief Mirrors one controller prompt state into the process-scoped persistence store.
 - @details Persists the current workflow state plus the pending and active prompt execution plans so prompt orchestration can survive session replacement. Runtime is O(1). Side effect: mutates process-scoped prompt-command persistence state.
 - @param[in] state {PiUsereqStatusState} Current controller state snapshot.
 - @return {void} No return value.
 
-### fn `export function shouldPreservePromptCommandStateOnShutdown(state: PiUsereqStatusState): boolean` (L217-220)
+### fn `export function shouldPreservePromptCommandStateOnShutdown(state: PiUsereqStatusState): boolean` (L219-222)
 - @brief Detects whether `session_shutdown` must preserve prompt-command state.
 - @details Keeps both the in-memory controller prompt state and the process-scoped prompt execution plan intact while pi switches from the original session into the forked execution session, because the old extension instance can keep running the initiating command handler after `session_shutdown` fires and before the replacement session fully takes over. Runtime is O(1). No external state is mutated.
 - @param[in] state {PiUsereqStatusState} Controller state before shutdown mutation.
 - @return {boolean} `true` when prompt-command state must survive the shutdown event.
 - @satisfies REQ-278
 
-### fn `function restorePersistedPromptCommandState(` (L229-240)
+### fn `function restorePersistedPromptCommandState(` (L231-242)
 - @brief Restores prompt-command persistence into one fresh controller when the active session matches.
 - @details Rehydrates workflow state plus pending or active prompt execution plans only when the current session file targets the persisted execution session created for prompt orchestration. Runtime is O(1). Side effect: mutates `state` when persisted prompt state is available.
 - @param[in] sessionFile {string | undefined} Current active session file.
 - @param[in,out] state {PiUsereqStatusState} Mutable controller state.
 - @return {void} No return value.
 
-### fn `function getContextSessionFile(ctx: ExtensionContext): string | undefined` (L248-252)
+### fn `function getContextSessionFile(ctx: ExtensionContext): string | undefined` (L250-254)
 - @brief Resolves the active session file exposed by one extension context.
 - @details Reads the session-manager session-file getter when available so prompt-command persistence can be resynchronized on every lifecycle hook after session replacement. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @return {string | undefined} Current session file when available.
 
-### fn `export function isStaleExtensionContextError(error: unknown): boolean` (L261-264)
+### fn `export function isStaleExtensionContextError(error: unknown): boolean` (L263-266)
 - @brief Detects stale extension-context access after session replacement.
 - @details Matches the guarded pi runtime error emitted when one invalidated extension context, command context, or replacement-session context is accessed after session replacement or reload. Runtime is O(n) in message length only when an error is supplied. No external state is mutated.
 - @param[in] error {unknown} Candidate thrown value.
 - @return {boolean} `true` when the value matches the stale-extension-context runtime error.
 - @satisfies REQ-280
 
-### fn `function resetElapsedState(state: PiUsereqStatusState): void` (L273-277)
+### fn `function resetElapsedState(state: PiUsereqStatusState): void` (L275-279)
 - @brief Resets the in-memory and persisted elapsed counters.
 - @details Clears both completed-duration fields in the supplied state and mirrors that cleared snapshot into the process-scoped store. Runtime is O(1). Side effects include mutable state reset and process-scoped persistence update.
 - @param[in,out] state {PiUsereqStatusState} Mutable status state.
 - @return {void} No return value.
 - @satisfies REQ-217
 
-### fn `function shouldResetElapsedStateOnSessionStart(event: unknown): boolean` (L286-289)
+### fn `function shouldResetElapsedStateOnSessionStart(event: unknown): boolean` (L288-291)
 - @brief Detects whether a `session_start` event must reset elapsed counters.
 - @details Treats `startup` and `reload` as hard-reset boundaries while preserving counters for `new`, `resume`, and `fork`. Runtime is O(1). No external state is mutated.
 - @param[in] event {unknown} Session-start payload.
 - @return {boolean} `true` when elapsed counters must reset.
 - @satisfies REQ-217
 
-### fn `function shouldResetWorkflowStateOnSessionStart(event: unknown): boolean` (L298-301)
+### fn `function shouldResetWorkflowStateOnSessionStart(event: unknown): boolean` (L300-303)
 - @brief Detects whether a `session_start` event must reset the workflow state to `idle`.
 - @details Treats `startup`, `new`, and `reload` as workflow-reset boundaries so prompt-orchestration state never leaks across boot, explicit session replacement, or extension reload. Runtime is O(1). No external state is mutated.
 - @param[in] event {unknown} Session-start payload.
 - @return {boolean} `true` when workflow state must reset to `idle`.
 - @satisfies REQ-009, REQ-221
 
-### fn `function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter` (L311-320)
+### fn `function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter` (L313-322)
 - @brief Builds the normalized theme adapter used by pi-usereq status formatters.
 - @details Precomputes label, value, foreground, and separator renderers so
 status formatting remains stable across real TUI themes and deterministic
@@ -1267,16 +1269,16 @@ test doubles. Runtime is O(1). No external state is mutated.
 - @param[in] theme {RawStatusTheme} Raw theme implementation from `ctx.ui.theme`.
 - @return {StatusThemeAdapter} Normalized status-theme adapter.
 
-### fn `const colorize = (color: StatusForegroundColor, text: string): string =>` (L312-319)
+### fn `const colorize = (color: StatusForegroundColor, text: string): string =>` (L314-321)
 
-### fn `function resolveStatusBranchValue(ctx: ExtensionContext): string` (L329-331)
+### fn `function resolveStatusBranchValue(ctx: ExtensionContext): string` (L331-333)
 - @brief Resolves the active git branch value rendered in the status bar.
 - @details Reads the current branch from the active context working directory on every status render so worktree switches and restored base-session renders expose the latest branch immediately. Runtime is dominated by git execution when the working directory belongs to a repository. Side effects include subprocess creation.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @return {string} Active branch name or `unknown` when unavailable.
 - @satisfies REQ-121, REQ-283
 
-### fn `function normalizeContextUsage(` (L342-359)
+### fn `function normalizeContextUsage(` (L344-361)
 - @brief Normalizes one raw context-usage snapshot.
 - @details Preserves the runtime token and context-window counts, derives a
 percentage when the runtime omits it, clamps negative percentages to `0`,
@@ -1285,7 +1287,7 @@ external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Raw runtime snapshot.
 - @return {ContextUsage | undefined} Normalized snapshot.
 
-### fn `function refreshContextUsage(` (L371-376)
+### fn `function refreshContextUsage(` (L373-378)
 - @brief Refreshes the stored context-usage snapshot from the active extension context.
 - @details Calls `ctx.getContextUsage()` on every intercepted event so the
 controller retains the newest context-usage facts available from the pi
@@ -1295,22 +1297,22 @@ runtime. Runtime is O(1). Side effect: mutates `state.contextUsage`.
 - @return {void} No return value.
 - @satisfies REQ-118, REQ-119
 
-### fn `function resolveContextUsageIconText(` (L385-402)
+### fn `function resolveContextUsageIconText(` (L387-404)
 - @brief Resolves the icon text for one normalized context-usage snapshot.
 - @details Maps context usage to one fixed-width icon band so footer rendering remains compact and deterministic across the documented `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands. Unavailable usage degrades to the `0%` icon. Runtime is O(1). No external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
 - @return {string} Fixed-width gauge icon text.
 - @satisfies REQ-122, REQ-284
 
-### fn `function formatContextUsageBar(` (L412-424)
+### fn `function formatContextUsageBar(` (L414-426)
 - @brief Formats one icon-based context-usage gauge.
-- @details Renders the documented gauge icon with theme `error` for `>=90%`, enables terminal blink only for `>=100%`, and otherwise leaves the gauge in the default terminal color. Runtime is O(1). No external state is mutated.
+- @details Renders the documented gauge icon with the same non-error status-value theme token used by `status` below `90%`, switches to theme `error` for `>=90%`, and enables terminal blink only for `>=100%`. Runtime is O(1). No external state is mutated.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
 - @return {string} Rendered fixed-width gauge icon.
 - @satisfies REQ-122, REQ-126, REQ-127, REQ-128, REQ-233, REQ-284
 
-### fn `function formatStatusDuration(durationMs: number): string` (L435-440)
+### fn `function formatStatusDuration(durationMs: number): string` (L437-442)
 - @brief Formats one elapsed-duration value as `M:SS`.
 - @details Floors the input to whole seconds, keeps minutes unbounded above 59,
 and zero-pads seconds to two digits. Runtime is O(1). No external state is
@@ -1319,7 +1321,7 @@ mutated.
 - @return {string} Duration rendered as `M:SS`.
 - @satisfies REQ-125
 
-### fn `function formatCompletedStatusDuration(` (L451-455)
+### fn `function formatCompletedStatusDuration(` (L453-457)
 - @brief Formats one optional completed-duration value.
 - @details Returns the canonical unset placeholder `--:--` until the supplied
 timer receives a normally completed prompt duration, then delegates to
@@ -1328,7 +1330,7 @@ timer receives a normally completed prompt duration, then delegates to
 - @return {string} Rendered duration or unset placeholder.
 - @satisfies REQ-124
 
-### fn `function formatElapsedStatusValue(` (L468-478)
+### fn `function formatElapsedStatusValue(` (L470-480)
 - @brief Formats the consolidated `elapsed` status-bar value.
 - @details Emits the active prompt segment `⏱︎ <active>`, the latest normally
 completed segment `⚑ <last>`, and the accumulated successful-runtime segment
@@ -1339,7 +1341,7 @@ mutated.
 - @return {string} Consolidated `elapsed` field value.
 - @satisfies REQ-123, REQ-124, REQ-125, REQ-159
 
-### fn `function formatStatusField(` (L489-495)
+### fn `function formatStatusField(` (L491-497)
 - @brief Formats one standard status-bar field.
 - @details Renders the field label in accent color and the value in warning
 color. Runtime is O(n) in combined text length. No external state is mutated.
@@ -1348,7 +1350,7 @@ color. Runtime is O(n) in combined text length. No external state is mutated.
 - @param[in] value {string} Unstyled field value.
 - @return {string} Rendered status-field fragment.
 
-### fn `function formatRenderedStatusField(` (L507-513)
+### fn `function formatRenderedStatusField(` (L509-515)
 - @brief Formats one pre-rendered status-bar field value.
 - @details Preserves the accent-colored field label while allowing callers to
 provide a custom styled value such as the context-usage bar. Runtime is O(n)
@@ -1358,7 +1360,7 @@ in combined text length. No external state is mutated.
 - @param[in] renderedValue {string} Pre-rendered field value.
 - @return {string} Rendered status-field fragment.
 
-### fn `function formatWorkflowStateValue(` (L523-531)
+### fn `function formatWorkflowStateValue(` (L525-533)
 - @brief Formats the rendered workflow-state value for the `status` field.
 - @details Uses the standard warning-colored value renderer for non-error states and emits a blinking `error`-colored value for `status:error` so the footer highlights orchestration failures immediately. Runtime is O(n) in text length. No external state is mutated.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
@@ -1366,7 +1368,7 @@ in combined text length. No external state is mutated.
 - @return {string} Rendered workflow-state value.
 - @satisfies REQ-112, REQ-223
 
-### fn `function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean` (L542-549)
+### fn `function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean` (L544-551)
 - @brief Detects whether an agent run ended through abort semantics.
 - @details Treats any assistant message whose `stopReason` equals `aborted` as
 an escape-triggered termination that must not overwrite the `last` timer.
@@ -1375,9 +1377,17 @@ Runtime is O(n) in message count. No external state is mutated.
 - @return {boolean} `true` when the run ended in aborted state.
 - @satisfies REQ-125
 
-### fn `function buildPiUsereqStatusText(` (L562-586)
+### fn `function resolvePiUsereqRuntimeSoundLevel(` (L561-566)
+- @brief Resolves the active runtime sound level used by status and notify flows.
+- @details Prefers the mutable runtime sound state, then falls back to the cached persisted boot value, and finally defaults to `none` before `session_start` loads configuration. Runtime is O(1). No external state is mutated.
+- @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+- @param[in] config {UseReqConfig | undefined} Cached project configuration.
+- @return {PiNotifySoundLevel} Active runtime sound level.
+- @satisfies REQ-180, REQ-285
+
+### fn `function buildPiUsereqStatusText(` (L579-603)
 - @brief Builds the full single-line pi-usereq status-bar payload.
-- @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, and the documented icon-based context gauge. Runtime is O(1). No external state is mutated.
+- @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, the documented icon-based context gauge, and the active runtime sound level instead of the persisted boot value. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
 - @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
@@ -1386,7 +1396,7 @@ Runtime is O(n) in message count. No external state is mutated.
 - @return {string} Single-line status-bar text.
 - @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223, REQ-233, REQ-283, REQ-284
 
-### fn `function stopStatusTicker(controller: PiUsereqStatusController): void` (L596-601)
+### fn `function stopStatusTicker(controller: PiUsereqStatusController): void` (L613-618)
 - @brief Stops the live elapsed-time ticker when it is active.
 - @details Clears the interval handle and resets the stored timer reference so
 subsequent runs can reinitialize live status refreshes deterministically.
@@ -1394,7 +1404,7 @@ Runtime is O(1). Side effect: mutates `controller.tickHandle`.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `function syncPiUsereqStatusTicker(` (L613-629)
+### fn `function syncPiUsereqStatusTicker(` (L630-646)
 - @brief Synchronizes the live elapsed-time ticker with the current run state.
 - @details Starts a 1-second render ticker while a run is active and stops the
 ticker when the run returns to idle. Runtime is O(1). Side effects include
@@ -1404,31 +1414,48 @@ ticks.
 - @return {void} No return value.
 - @satisfies REQ-123
 
-### fn `export function createPiUsereqStatusController(): PiUsereqStatusController` (L637-652)
+### fn `export function createPiUsereqStatusController(): PiUsereqStatusController` (L654-670)
 - @brief Creates an empty pi-usereq status controller.
-- @details Initializes the mutable status snapshot, including empty prompt-request tracking, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
+- @details Initializes the mutable status snapshot, including empty prompt-request tracking and an unset runtime sound level that later loads from persisted config during `session_start`, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
 - @return {PiUsereqStatusController} New status controller.
 - @satisfies DES-010
 
-### fn `export function setPiUsereqStatusConfig(` (L664-669)
+### fn `export function setPiUsereqStatusConfig(` (L683-688)
 - @brief Stores the effective project configuration used by status rendering.
 - @details Replaces the controller's cached configuration so later status
-renders reuse the latest docs, tests, source-path, and pi-notify values
-without reading from disk on every event. Runtime is O(1). Side effect:
+renders reuse the latest docs, tests, source-path, and persisted pi-notify
+values without reading from disk on every event, while leaving the active
+runtime sound level in `controller.state`. Runtime is O(1). Side effect:
 mutates `controller.config`.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `export function renderPiUsereqStatus(` (L679-709)
+### fn `export function getPiUsereqRuntimeSoundLevel(` (L697-701)
+- @brief Returns the active runtime sound level tracked by the status controller.
+- @details Exposes the in-memory runtime sound state so shortcut handlers and prompt-end notification dispatch can stay decoupled from the persisted boot value stored in `.pi-usereq.json`. Runtime is O(1). No external state is mutated.
+- @param[in] controller {PiUsereqStatusController} Mutable status controller.
+- @return {PiNotifySoundLevel} Active runtime sound level.
+- @satisfies REQ-180, REQ-285
+
+### fn `export function setPiUsereqRuntimeSoundLevel(` (L712-722)
+- @brief Stores one new runtime sound level and refreshes the status bar.
+- @details Mutates only the in-memory runtime sound state so shortcut-driven sound changes do not update `.pi-usereq.json`, then re-renders the footer when an active extension context is available. Runtime is O(1). Side effect: mutates `controller.state.runtimeSoundLevel` and may update `ctx.ui` status.
+- @param[in] runtimeSoundLevel {PiNotifySoundLevel} Next active runtime sound level.
+- @param[in] ctx {ExtensionContext | undefined} Optional active extension context.
+- @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-180, REQ-286, REQ-287
+
+### fn `export function renderPiUsereqStatus(` (L732-763)
 - @brief Renders the current pi-usereq status bar into the active UI context.
-- @details Updates the controller's latest context pointer and writes the single-line status text only when configuration is available, including the active branch field and documented icon-based context gauge. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `ctx.ui` status when the context is still active.
+- @details Updates the controller's latest context pointer, refreshes the live `getContextUsage()` snapshot for direct render call sites that do not pass through `updateExtensionStatus(...)`, and writes the single-line status text only when configuration is available, including the active branch field, documented icon-based context gauge, and active runtime sound level. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `controller.state.contextUsage` and `ctx.ui` status when the context is still active.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
-- @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
+- @satisfies REQ-118, REQ-119, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
 
-### fn `export function setPiUsereqWorkflowState(` (L720-731)
+### fn `export function setPiUsereqWorkflowState(` (L774-785)
 - @brief Transitions the prompt-orchestration workflow state and refreshes the status bar.
 - @details Mutates the tracked workflow state, preserves the latest extension context when available, and re-renders the single-line footer immediately so internal command transitions and pi lifecycle transitions stay visible to the user. Runtime is O(1). Side effect: mutates workflow state and may update `ctx.ui` status.
 - @param[in] workflowState {PiUsereqWorkflowState} Next workflow state.
@@ -1437,17 +1464,17 @@ mutates `controller.config`.
 - @return {void} No return value.
 - @satisfies REQ-221, REQ-222, REQ-223
 
-### fn `export function updateExtensionStatus(` (L743-807)
+### fn `export function updateExtensionStatus(` (L797-864)
 - @brief Updates mutable status state for one intercepted lifecycle hook.
-- @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
+- @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, loads the active runtime sound level from persisted config during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
 - @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
 - @param[in] event {unknown} Hook payload forwarded from the wrapper.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
-- @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280
+- @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280, REQ-285
 
-### fn `export function disposePiUsereqStatusController(` (L818-823)
+### fn `export function disposePiUsereqStatusController(` (L875-880)
 - @brief Disposes the pi-usereq status controller.
 - @details Stops the live ticker, clears the cached context pointer, and leaves
 the last captured status snapshot available for inspection until the
@@ -1459,49 +1486,52 @@ limited to interval disposal and in-memory state mutation.
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`StatusForegroundColor`|type||30||
-|`RawStatusTheme`|iface||40-42|interface RawStatusTheme|
-|`StatusThemeAdapter`|iface||50-55|interface StatusThemeAdapter|
-|`PiUsereqStatusHookName`|type||98||
-|`PiUsereqPromptRequest`|type||104||
-|`PiUsereqWorkflowState`|type||110||
-|`PiUsereqStatusState`|iface||116-124|export interface PiUsereqStatusState|
-|`PiUsereqStatusController`|iface||133-138|export interface PiUsereqStatusController|
-|`PiUsereqStatusPersistenceStore`|iface||144-147|interface PiUsereqStatusPersistenceStore|
-|`getPiUsereqStatusPersistenceStore`|fn||161-170|function getPiUsereqStatusPersistenceStore(): PiUsereqSta...|
-|`restorePersistedElapsedState`|fn||178-182|function restorePersistedElapsedState(state: PiUsereqStat...|
-|`persistElapsedState`|fn||190-194|function persistElapsedState(state: PiUsereqStatusState):...|
-|`persistPromptCommandState`|fn||202-208|function persistPromptCommandState(state: PiUsereqStatusS...|
-|`shouldPreservePromptCommandStateOnShutdown`|fn||217-220|export function shouldPreservePromptCommandStateOnShutdow...|
-|`restorePersistedPromptCommandState`|fn||229-240|function restorePersistedPromptCommandState(|
-|`getContextSessionFile`|fn||248-252|function getContextSessionFile(ctx: ExtensionContext): st...|
-|`isStaleExtensionContextError`|fn||261-264|export function isStaleExtensionContextError(error: unkno...|
-|`resetElapsedState`|fn||273-277|function resetElapsedState(state: PiUsereqStatusState): void|
-|`shouldResetElapsedStateOnSessionStart`|fn||286-289|function shouldResetElapsedStateOnSessionStart(event: unk...|
-|`shouldResetWorkflowStateOnSessionStart`|fn||298-301|function shouldResetWorkflowStateOnSessionStart(event: un...|
-|`createStatusThemeAdapter`|fn||311-320|function createStatusThemeAdapter(theme: RawStatusTheme):...|
-|`colorize`|fn||312-319|const colorize = (color: StatusForegroundColor, text: str...|
-|`resolveStatusBranchValue`|fn||329-331|function resolveStatusBranchValue(ctx: ExtensionContext):...|
-|`normalizeContextUsage`|fn||342-359|function normalizeContextUsage(|
-|`refreshContextUsage`|fn||371-376|function refreshContextUsage(|
-|`resolveContextUsageIconText`|fn||385-402|function resolveContextUsageIconText(|
-|`formatContextUsageBar`|fn||412-424|function formatContextUsageBar(|
-|`formatStatusDuration`|fn||435-440|function formatStatusDuration(durationMs: number): string|
-|`formatCompletedStatusDuration`|fn||451-455|function formatCompletedStatusDuration(|
-|`formatElapsedStatusValue`|fn||468-478|function formatElapsedStatusValue(|
-|`formatStatusField`|fn||489-495|function formatStatusField(|
-|`formatRenderedStatusField`|fn||507-513|function formatRenderedStatusField(|
-|`formatWorkflowStateValue`|fn||523-531|function formatWorkflowStateValue(|
-|`didAgentEndAbort`|fn||542-549|function didAgentEndAbort(messages: AgentEndEvent["messag...|
-|`buildPiUsereqStatusText`|fn||562-586|function buildPiUsereqStatusText(|
-|`stopStatusTicker`|fn||596-601|function stopStatusTicker(controller: PiUsereqStatusContr...|
-|`syncPiUsereqStatusTicker`|fn||613-629|function syncPiUsereqStatusTicker(|
-|`createPiUsereqStatusController`|fn||637-652|export function createPiUsereqStatusController(): PiUsere...|
-|`setPiUsereqStatusConfig`|fn||664-669|export function setPiUsereqStatusConfig(|
-|`renderPiUsereqStatus`|fn||679-709|export function renderPiUsereqStatus(|
-|`setPiUsereqWorkflowState`|fn||720-731|export function setPiUsereqWorkflowState(|
-|`updateExtensionStatus`|fn||743-807|export function updateExtensionStatus(|
-|`disposePiUsereqStatusController`|fn||818-823|export function disposePiUsereqStatusController(|
+|`StatusForegroundColor`|type||31||
+|`RawStatusTheme`|iface||41-43|interface RawStatusTheme|
+|`StatusThemeAdapter`|iface||51-56|interface StatusThemeAdapter|
+|`PiUsereqStatusHookName`|type||99||
+|`PiUsereqPromptRequest`|type||105||
+|`PiUsereqWorkflowState`|type||111||
+|`PiUsereqStatusState`|iface||117-126|export interface PiUsereqStatusState|
+|`PiUsereqStatusController`|iface||135-140|export interface PiUsereqStatusController|
+|`PiUsereqStatusPersistenceStore`|iface||146-149|interface PiUsereqStatusPersistenceStore|
+|`getPiUsereqStatusPersistenceStore`|fn||163-172|function getPiUsereqStatusPersistenceStore(): PiUsereqSta...|
+|`restorePersistedElapsedState`|fn||180-184|function restorePersistedElapsedState(state: PiUsereqStat...|
+|`persistElapsedState`|fn||192-196|function persistElapsedState(state: PiUsereqStatusState):...|
+|`persistPromptCommandState`|fn||204-210|function persistPromptCommandState(state: PiUsereqStatusS...|
+|`shouldPreservePromptCommandStateOnShutdown`|fn||219-222|export function shouldPreservePromptCommandStateOnShutdow...|
+|`restorePersistedPromptCommandState`|fn||231-242|function restorePersistedPromptCommandState(|
+|`getContextSessionFile`|fn||250-254|function getContextSessionFile(ctx: ExtensionContext): st...|
+|`isStaleExtensionContextError`|fn||263-266|export function isStaleExtensionContextError(error: unkno...|
+|`resetElapsedState`|fn||275-279|function resetElapsedState(state: PiUsereqStatusState): void|
+|`shouldResetElapsedStateOnSessionStart`|fn||288-291|function shouldResetElapsedStateOnSessionStart(event: unk...|
+|`shouldResetWorkflowStateOnSessionStart`|fn||300-303|function shouldResetWorkflowStateOnSessionStart(event: un...|
+|`createStatusThemeAdapter`|fn||313-322|function createStatusThemeAdapter(theme: RawStatusTheme):...|
+|`colorize`|fn||314-321|const colorize = (color: StatusForegroundColor, text: str...|
+|`resolveStatusBranchValue`|fn||331-333|function resolveStatusBranchValue(ctx: ExtensionContext):...|
+|`normalizeContextUsage`|fn||344-361|function normalizeContextUsage(|
+|`refreshContextUsage`|fn||373-378|function refreshContextUsage(|
+|`resolveContextUsageIconText`|fn||387-404|function resolveContextUsageIconText(|
+|`formatContextUsageBar`|fn||414-426|function formatContextUsageBar(|
+|`formatStatusDuration`|fn||437-442|function formatStatusDuration(durationMs: number): string|
+|`formatCompletedStatusDuration`|fn||453-457|function formatCompletedStatusDuration(|
+|`formatElapsedStatusValue`|fn||470-480|function formatElapsedStatusValue(|
+|`formatStatusField`|fn||491-497|function formatStatusField(|
+|`formatRenderedStatusField`|fn||509-515|function formatRenderedStatusField(|
+|`formatWorkflowStateValue`|fn||525-533|function formatWorkflowStateValue(|
+|`didAgentEndAbort`|fn||544-551|function didAgentEndAbort(messages: AgentEndEvent["messag...|
+|`resolvePiUsereqRuntimeSoundLevel`|fn||561-566|function resolvePiUsereqRuntimeSoundLevel(|
+|`buildPiUsereqStatusText`|fn||579-603|function buildPiUsereqStatusText(|
+|`stopStatusTicker`|fn||613-618|function stopStatusTicker(controller: PiUsereqStatusContr...|
+|`syncPiUsereqStatusTicker`|fn||630-646|function syncPiUsereqStatusTicker(|
+|`createPiUsereqStatusController`|fn||654-670|export function createPiUsereqStatusController(): PiUsere...|
+|`setPiUsereqStatusConfig`|fn||683-688|export function setPiUsereqStatusConfig(|
+|`getPiUsereqRuntimeSoundLevel`|fn||697-701|export function getPiUsereqRuntimeSoundLevel(|
+|`setPiUsereqRuntimeSoundLevel`|fn||712-722|export function setPiUsereqRuntimeSoundLevel(|
+|`renderPiUsereqStatus`|fn||732-763|export function renderPiUsereqStatus(|
+|`setPiUsereqWorkflowState`|fn||774-785|export function setPiUsereqWorkflowState(|
+|`updateExtensionStatus`|fn||797-864|export function updateExtensionStatus(|
+|`disposePiUsereqStatusController`|fn||875-880|export function disposePiUsereqStatusController(|
 
 
 ---
@@ -2102,7 +2132,7 @@ import type { UseReqConfig } from "./config.js";
 
 - type `export type PiNotifyConfigFields = Pick<` (L115)
 - @brief Describes the configuration fields consumed by pi-notify helpers.
-- @details Narrows the full project config to the persisted notify, sound, and Pushover fields used by status rendering, prompt-end routing, and shortcut toggles. Compile-time only and introduces no runtime cost.
+- @details Narrows the full project config to the notify, sound, and Pushover fields used by status rendering and prompt-end routing. Callers may override `notify-sound` with the active runtime sound level before dispatch. Compile-time only and introduces no runtime cost.
 - type `type PiNotifySpawn = typeof spawn;` (L145)
 - @brief Describes the shell-spawn callback used by prompt-end command dispatch.
 - @details Narrows the injected spawn surface so deterministic tests can capture detached shell invocations without patching global module state externally. Compile-time only and introduces no runtime cost.
@@ -2187,10 +2217,10 @@ import type { UseReqConfig } from "./config.js";
 
 ### fn `export function cyclePiNotifySoundLevel(currentLevel: PiNotifySoundLevel): PiNotifySoundLevel` (L371-377)
 - @brief Cycles one sound level through the canonical shortcut order.
-- @details Advances persisted sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling and menu reuse. Runtime is O(1). No external state is mutated.
-- @param[in] currentLevel {PiNotifySoundLevel} Current persisted sound level.
-- @return {PiNotifySoundLevel} Next sound level in the cycle.
-- @satisfies REQ-134
+- @details Advances the active runtime sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling without mutating persisted boot configuration. Runtime is O(1). No external state is mutated.
+- @param[in] currentLevel {PiNotifySoundLevel} Current active runtime sound level.
+- @return {PiNotifySoundLevel} Next runtime sound level in the cycle.
+- @satisfies REQ-286
 
 ### fn `function isPiNotifyOutcomeEnabled(` (L388-402)
 - @brief Tests whether one outcome-specific toggle is enabled.
@@ -2445,29 +2475,29 @@ import type { UseReqConfig } from "./config.js";
 
 ---
 
-# pi-usereq-tools.ts | TypeScript | 178L | 7 symbols | 0 imports | 17 comments
+# pi-usereq-tools.ts | TypeScript | 180L | 7 symbols | 0 imports | 17 comments
 > Path: `src/core/pi-usereq-tools.ts`
 - @brief Declares the configurable pi-usereq active-tool inventory.
 - @details Provides canonical custom-tool names, supported embedded-tool names, default enablement subsets, and normalization helpers shared by configuration loading, extension startup, and test doubles. The module is side-effect free. Lookup and normalization costs are linear in configured tool count.
 
 ## Definitions
 
-- type `export type PiUsereqCustomToolName = (typeof PI_USEREQ_CUSTOM_TOOL_NAMES)[number];` (L79)
+- type `export type PiUsereqCustomToolName = (typeof PI_USEREQ_CUSTOM_TOOL_NAMES)[number];` (L81)
 - @brief Represents one valid extension-owned configurable tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_CUSTOM_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqEmbeddedToolName = (typeof PI_USEREQ_EMBEDDED_TOOL_NAMES)[number];` (L85)
+- type `export type PiUsereqEmbeddedToolName = (typeof PI_USEREQ_EMBEDDED_TOOL_NAMES)[number];` (L87)
 - @brief Represents one valid embedded configurable tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_EMBEDDED_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqStartupToolName = (typeof PI_USEREQ_STARTUP_TOOL_NAMES)[number];` (L91)
+- type `export type PiUsereqStartupToolName = (typeof PI_USEREQ_STARTUP_TOOL_NAMES)[number];` (L93)
 - @brief Represents one valid configurable active-tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_STARTUP_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-### fn `export function isPiUsereqEmbeddedToolName(name: string): name is PiUsereqEmbeddedToolName` (L117-119)
+### fn `export function isPiUsereqEmbeddedToolName(name: string): name is PiUsereqEmbeddedToolName` (L119-121)
 - @brief Tests whether one tool name belongs to the supported embedded-tool subset.
 - @details Performs one set-membership probe against `PI_USEREQ_EMBEDDED_TOOL_SET`. Runtime is O(1). No external state is mutated.
 - @param[in] name {string} Candidate tool name.
 - @return {boolean} `true` when the name belongs to the embedded configurable-tool subset.
 
-### fn `export function normalizeEnabledPiUsereqTools(value: unknown): PiUsereqStartupToolName[]` (L129-136)
+### fn `export function normalizeEnabledPiUsereqTools(value: unknown): PiUsereqStartupToolName[]` (L131-138)
 - @brief Normalizes a user-configured active-tool list.
 - @details Returns the default enabled-tool tuple when the input is not an array. Otherwise filters to string entries, removes names outside the configurable tool set, and deduplicates while preserving first-seen order. Time complexity is O(n). No external state is mutated.
 - @param[in] value {unknown} Raw configuration payload for `enabled-tools`.
@@ -2475,14 +2505,14 @@ import type { UseReqConfig } from "./config.js";
 - @satisfies REQ-064
 - @post Returned values are members of `PI_USEREQ_STARTUP_TOOL_NAMES` only.
 
-### fn `function buildPiUsereqStartupToolSortKey(` (L145-153)
+### fn `function buildPiUsereqStartupToolSortKey(` (L147-155)
 - @brief Builds the menu-order partition key for one configurable tool name.
 - @details Encodes the documented `Enable tools` ordering by grouping custom tools before embedded tools, placing non-`files-*` custom tools before `files-*` custom tools, and moving default-disabled names to the tail of each resolved partition. Runtime is O(1). No external state is mutated.
 - @param[in] name {PiUsereqStartupToolName} Canonical configurable tool name.
 - @return {[number, number, number, string]} Stable tuple `{group, subgroup, default_state, name}` used for lexicographic ordering.
 - @satisfies REQ-007, REQ-231, REQ-232
 
-### fn `export function comparePiUsereqStartupToolNames(` (L163-178)
+### fn `export function comparePiUsereqStartupToolNames(` (L165-180)
 - @brief Compares two configurable tool names using the documented menu order.
 - @details Applies the partition key emitted by `buildPiUsereqStartupToolSortKey(...)` and falls back to lexical comparison inside the final key slot so the `Enable tools` submenu stays deterministic across runtimes. Runtime is O(1). No external state is mutated.
 - @param[in] left {PiUsereqStartupToolName} Left configurable tool name.
@@ -2493,28 +2523,28 @@ import type { UseReqConfig } from "./config.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiUsereqCustomToolName`|type||79||
-|`PiUsereqEmbeddedToolName`|type||85||
-|`PiUsereqStartupToolName`|type||91||
-|`isPiUsereqEmbeddedToolName`|fn||117-119|export function isPiUsereqEmbeddedToolName(name: string):...|
-|`normalizeEnabledPiUsereqTools`|fn||129-136|export function normalizeEnabledPiUsereqTools(value: unkn...|
-|`buildPiUsereqStartupToolSortKey`|fn||145-153|function buildPiUsereqStartupToolSortKey(|
-|`comparePiUsereqStartupToolNames`|fn||163-178|export function comparePiUsereqStartupToolNames(|
+|`PiUsereqCustomToolName`|type||81||
+|`PiUsereqEmbeddedToolName`|type||87||
+|`PiUsereqStartupToolName`|type||93||
+|`isPiUsereqEmbeddedToolName`|fn||119-121|export function isPiUsereqEmbeddedToolName(name: string):...|
+|`normalizeEnabledPiUsereqTools`|fn||131-138|export function normalizeEnabledPiUsereqTools(value: unkn...|
+|`buildPiUsereqStartupToolSortKey`|fn||147-155|function buildPiUsereqStartupToolSortKey(|
+|`comparePiUsereqStartupToolNames`|fn||165-180|export function comparePiUsereqStartupToolNames(|
 
 
 ---
 
-# prompt-command-catalog.ts | TypeScript | 46L | 2 symbols | 0 imports | 4 comments
+# prompt-command-catalog.ts | TypeScript | 45L | 2 symbols | 0 imports | 4 comments
 > Path: `src/core/prompt-command-catalog.ts`
-- @brief Declares the canonical bundled `req-*` prompt-command inventory.
-- @details Centralizes prompt-command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. The module is side-effect free. Lookup cost is O(1) per exported constant access.
+- @brief Declares the canonical bundled prompt-backed `req-*` command inventory.
+- @details Centralizes only prompt-template-backed command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. Specialized slash commands such as `req-references` and `req-reset` are registered outside this inventory. The module is side-effect free. Lookup cost is O(1) per exported constant access.
 
 ## Definitions
 
-- type `export type PromptCommandName = (typeof PROMPT_COMMAND_NAMES)[number];` (L34)
+- type `export type PromptCommandName = (typeof PROMPT_COMMAND_NAMES)[number];` (L33)
 - @brief Narrows prompt-command identifiers to the bundled command set.
 - @details Compile-time alias reused by orchestration helpers, debug inventory normalization, and command registration. The alias introduces no runtime cost.
-### fn `export function formatPromptCommandName(` (L42-46)
+### fn `export function formatPromptCommandName(` (L41-45)
 - @brief Formats one bundled prompt-command identifier as its slash-command name.
 - @details Prefixes the canonical prompt name with `req-` so debug menus and log filters can use the invokable slash-command form without duplicating the underlying inventory. Runtime is O(n) in prompt-name length. No external state is mutated.
 - @param[in] promptName {PromptCommandName} Canonical bundled prompt name.
@@ -2523,16 +2553,16 @@ import type { UseReqConfig } from "./config.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PromptCommandName`|type||34||
-|`formatPromptCommandName`|fn||42-46|export function formatPromptCommandName(|
+|`PromptCommandName`|type||33||
+|`formatPromptCommandName`|fn||41-45|export function formatPromptCommandName(|
 
 
 ---
 
-# prompt-command-runtime.ts | TypeScript | 1816L | 54 symbols | 12 imports | 58 comments
+# prompt-command-runtime.ts | TypeScript | 1955L | 56 symbols | 12 imports | 60 comments
 > Path: `src/core/prompt-command-runtime.ts`
-- @brief Implements prompt-command preflight and worktree orchestration.
-- @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization with restored-session transcript preservation, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
+- @brief Implements bundled prompt-command preflight and worktree orchestration.
+- @details Centralizes prompt-template-backed `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, reusable transcript-preservation plus session-restoration helpers, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success stash-assisted fast-forward merge finalization, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, stash-stack mutation, and filesystem reads and writes.
 
 ## Imports
 ```
@@ -2543,7 +2573,7 @@ import { ReqError } from "./errors.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
 import {
-import {
+import { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
 import { SessionManager } from "@mariozechner/pi-coding-agent";
 import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
@@ -2552,57 +2582,57 @@ import {
 
 ## Definitions
 
-### iface `export interface PromptRequiredDocSpec` (L45-48)
+### iface `export interface PromptRequiredDocSpec` (L42-45)
 - @brief Describes one canonical required-document probe.
 - @details Binds a canonical doc filename to the remediation prompt command surfaced on failure so prompt-specific doc validation can stay deterministic. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface PromptCommandExecutionPlan` (L54-68)
+### iface `export interface PromptCommandExecutionPlan` (L51-65)
 - @brief Describes one prompt-command execution plan tracked across lifecycle hooks.
 - @details Stores the prompt identity, runtime git root, associated branch name, original project base, execution context path, persisted origin and execution session files, and optional worktree metadata so the extension can switch all cwd surfaces before prompt dispatch and finalize worktree lifecycle after agent end. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandPostCreateHookContext` (L74-79)
+### iface `interface PromptCommandPostCreateHookContext` (L71-76)
 - @brief Describes one post-create test hook payload for prompt-command worktrees.
 - @details Exposes the git root, generated worktree name, sibling worktree path, and effective execution base so tests can simulate post-create verification failures deterministically. The interface is compile-time only and introduces no runtime cost.
 
-- type `type PromptCommandPostCreateHook = (context: PromptCommandPostCreateHookContext) => void;` (L85)
+- type `type PromptCommandPostCreateHook = (context: PromptCommandPostCreateHookContext) => void;` (L82)
 - @brief Represents one synchronous test hook invoked after prompt worktree creation.
 - @details Allows tests to mutate or remove newly created worktree artifacts before verification executes. The alias is compile-time only and introduces no runtime cost.
-### iface `interface PromptCommandDebugOptions` (L91-94)
+### iface `interface PromptCommandDebugOptions` (L88-91)
 - @brief Describes optional debug logging context for prompt orchestration helpers.
 - @details Carries the effective project configuration and current workflow state so prompt-runtime helpers can append selected debug entries without depending on extension UI types. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionMessageOptions` (L100-102)
+### iface `interface PromptCommandSessionMessageOptions` (L97-99)
 - @brief Describes prompt-delivery options supported by replacement-session callbacks.
 - @details Mirrors the documented `sendUserMessage(...)` delivery modes needed when prompt orchestration targets a replacement session after a slash-command-owned session switch. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionSwitchOptions` (L108-110)
+### iface `interface PromptCommandSessionSwitchOptions` (L105-107)
 - @brief Describes the replacement-session callback options accepted by session switching.
 - @details Mirrors the documented pi runtime `withSession(...)` hook so prompt-command orchestration can continue work against the replacement session after the old command context becomes stale. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandActiveContext extends PromptCommandSessionContext` : PromptCommandSessionContext (L116-121)
+### iface `interface PromptCommandActiveContext extends PromptCommandSessionContext` : PromptCommandSessionContext (L113-118)
 - @brief Describes the minimal session-bound surface available after session replacement.
 - @details Extends the shared prompt-command context with `sendUserMessage(...)` so prompt dispatch can target the replacement session without reusing stale pre-switch runtime objects. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionEntry` (L127-133)
+### iface `interface PromptCommandSessionEntry` (L124-130)
 - @brief Describes one serializable session entry copied into a materialized execution-session file.
 - @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionContext` (L139-151)
+### iface `interface PromptCommandSessionContext` (L136-148)
 - @brief Describes the minimal command-context session surface used by prompt orchestration.
 - @details Narrows extension command contexts to the `switchSession(...)` hook, the mutable `cwd` mirror, and the session metadata probes required for cwd verification and session snapshot materialization. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandContextError extends Error` : Error (L157-159)
+### iface `interface PromptCommandContextError extends Error` : Error (L154-156)
 - @brief Describes one error object enriched with a replacement-session context.
 - @details Allows prompt orchestration helpers to preserve the last valid session-bound context across replacement boundaries so callers can continue notifications and status updates after switch-triggered failures. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function isUsablePromptSessionFile(` (L174-192)
+### fn `function isUsablePromptSessionFile(` (L171-189)
 - @brief Tests whether the current session file remains reusable for prompt-command bootstrap.
 - @details Accepts only persisted session files whose header cwd is readable, still exists on disk, and remains inside the active project base. This rejects stale execution-session files that still point at deleted or sibling worktrees from earlier prompt runs. Runtime is O(p) plus one session-header read. No external state is mutated.
 - @param[in] sessionFile {string | undefined} Candidate current session file.
 - @param[in] projectBase {string} Active project base path.
 - @return {sessionFile is string} `true` when the session file remains reusable for prompt bootstrap.
 
-### fn `function resolvePromptSessionFile(sessionFile: string | undefined, cwd: string): string` (L202-212)
+### fn `function resolvePromptSessionFile(sessionFile: string | undefined, cwd: string): string` (L199-209)
 - @brief Resolves the session file path used as the origin for prompt-command session switching.
 - @details Reuses the current session file only when its persisted header cwd is still readable, exists on disk, and remains inside the active project base. Otherwise allocates a fresh session file path rooted at the supplied cwd so later worktree switching and restoration never inherit stale deleted-worktree session metadata. Runtime is dominated by one optional session-header read plus optional session-file allocation. Side effects include session-file path allocation when the active session metadata is stale or ephemeral.
 - @param[in] sessionFile {string | undefined} Current active session file when available.
@@ -2610,7 +2640,7 @@ import {
 - @return {string} Session file path reserved for prompt orchestration.
 - @throws {ReqError} Throws when a session file path cannot be resolved.
 
-### fn `function writePromptExecutionSessionSnapshot(` (L226-252)
+### fn `function writePromptExecutionSessionSnapshot(` (L223-249)
 - @brief Writes one execution-session snapshot file with the target worktree cwd.
 - @details Persists a version-3 JSONL session header whose `cwd` equals the supplied target worktree path, then appends the supplied current-session branch entries unchanged so pi can reopen the replacement session in the correct cwd even when the origin session file has not been flushed yet. Runtime is O(n) in branch-entry count plus serialized byte size. Side effects include directory creation and file overwrite.
 - @param[in] sessionFile {string} Target execution-session file path.
@@ -2622,7 +2652,7 @@ import {
 - @throws {ReqError} Throws when the execution-session snapshot cannot be written.
 - @satisfies REQ-271
 
-### fn `function createPromptExecutionSessionFile(` (L265-288)
+### fn `function createPromptExecutionSessionFile(` (L262-285)
 - @brief Creates the persisted session file used for worktree-backed prompt execution.
 - @details Forks the resolved origin session into the target cwd when the origin session file is already persisted. Otherwise allocates a new execution-session path, materializes a JSONL header whose `cwd` equals the target worktree path, and copies the current in-memory session branch so pi can switch into the worktree session with the correct runtime cwd. Runtime is dominated by session-file copy or snapshot-write cost. Side effects include session-file creation under the target cwd session directory.
 - @param[in] sourceSessionFile {string} Origin session file path.
@@ -2633,25 +2663,25 @@ import {
 - @throws {ReqError} Throws when the execution-session file cannot be created.
 - @satisfies REQ-271
 
-### fn `function getPromptSessionCwd(ctx?: PromptCommandSessionContext): string | undefined` (L296-304)
+### fn `function getPromptSessionCwd(ctx?: PromptCommandSessionContext): string | undefined` (L293-301)
 - @brief Reads the current active session cwd from a prompt-command context.
 - @details Returns the session-manager cwd only when the supplied context exposes the documented `getCwd()` probe and the probe remains valid after any prior session replacement. Stale or missing probes degrade to `undefined` so verification paths never reuse invalidated pre-switch session objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Active session cwd when available.
 
-### fn `function getPromptSessionFile(ctx?: PromptCommandSessionContext): string | undefined` (L312-320)
+### fn `function getPromptSessionFile(ctx?: PromptCommandSessionContext): string | undefined` (L309-317)
 - @brief Reads the current active session file from a prompt-command context.
 - @details Returns the session-manager file path only when the supplied context exposes the documented `getSessionFile()` probe and the probe remains valid after any prior session replacement. Stale or missing probes degrade to `undefined` so verification paths never reuse invalidated pre-switch session objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Active session file when available.
 
-### fn `function getPromptContextCwd(ctx?: PromptCommandSessionContext): string | undefined` (L328-334)
+### fn `function getPromptContextCwd(ctx?: PromptCommandSessionContext): string | undefined` (L325-331)
 - @brief Reads the current context cwd from a prompt-command context.
 - @details Returns the context `cwd` only when the supplied getter remains valid after any prior session replacement. Stale getters degrade to `undefined` so verification paths never depend on invalidated pre-switch command objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Context cwd when available.
 
-### fn `function resolvePromptCommandSwitchContext(` (L344-359)
+### fn `function resolvePromptCommandSwitchContext(` (L341-356)
 - @brief Resolves the best available command-capable context for prompt session switching.
 - @details Prefers the caller-supplied context when it still exposes `switchSession(...)`, otherwise falls back to the persisted replacement-session context associated with the execution-session file so lifecycle handlers can complete closure when pi emits non-command event contexts. Runtime is O(1). No external state is mutated.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose execution-session file keys the persisted context.
@@ -2659,7 +2689,7 @@ import {
 - @return {{ context: PromptCommandSessionContext | undefined; source: "provided" | "persisted" | "missing" }} Preferred switch context plus its provenance.
 - @satisfies REQ-272, REQ-276
 
-### fn `function syncPromptCommandProcessCwd(expectedPath: string, stageLabel: string): void` (L370-390)
+### fn `function syncPromptCommandProcessCwd(expectedPath: string, stageLabel: string): void` (L367-387)
 - @brief Aligns the host process cwd to one expected prompt-orchestration path.
 - @details Applies `process.chdir(...)` only when the host process is still anchored to a different directory than the active prompt session, then re-reads `process.cwd()` and throws a deterministic error when the mutation fails or does not take effect. Runtime is O(p) in path length plus one optional cwd mutation. Side effect: mutates the host process cwd.
 - @param[in] expectedPath {string} Path that `process.cwd()` must match.
@@ -2668,28 +2698,28 @@ import {
 - @throws {ReqError} Throws when `process.chdir(...)` fails or leaves `process.cwd()` misaligned.
 - @satisfies REQ-257, REQ-272
 
-### fn `function readPromptSessionFileCwd(sessionFile: string): string | undefined` (L398-422)
+### fn `function readPromptSessionFileCwd(sessionFile: string): string | undefined` (L395-419)
 - @brief Reads the persisted working directory recorded in one prompt-command session file header.
 - @details Opens the JSONL session file, parses the first non-empty line as JSON, and returns the `cwd` field when present as a string so session-target verification can rely on live on-disk session state instead of stale handler-scoped `ctx` references. Runtime is O(n) in header size. No external state is mutated.
 - @param[in] sessionFile {string} Absolute session-file path.
 - @return {string | undefined} Persisted session cwd when readable; otherwise undefined.
 
-### fn `function readPromptSessionJsonLines(` (L431-478)
+### fn `function readPromptSessionJsonLines(` (L428-475)
 - @brief Reads one persisted session file as ordered parsed JSONL records.
 - @details Loads the raw session file, preserves every non-empty serialized line verbatim, parses each line as one JSON object, and rejects unreadable or structurally invalid files so prompt-closure helpers can replay exact execution-session transcript records into the restored base session without reserialization drift. Runtime is O(n) in session-file size. No external state is mutated.
 - @param[in] sessionFile {string} Absolute session-file path.
 - @return {Array<{ rawLine: string; parsed: Record<string, unknown> }>} Parsed non-empty JSONL lines in file order.
 - @throws {ReqError} Throws when the file cannot be read, when it contains no JSONL records, when any record is not a JSON object, or when the header record is missing.
 
-### fn `function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void` (L488-585)
+### fn `export function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void` (L485-582)
 - @brief Copies successful execution-session transcript records into the restored base session file.
 - @details Reads the execution session JSONL file, preserves the original base-session header when it already exists, materializes a restored base-session header when the reserved original session file is still pending persistence, appends any execution-session records missing from the original session in original execution order, and re-reads the restored file to verify both `base-path` cwd and copied entry identifiers. Runtime is O(n) in combined session-file size. Side effects include session-file creation or append operations for the restored base session.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original and execution session files must be synchronized.
 - @return {void} No return value.
 - @throws {ReqError} Throws when either session file is unreadable or when appended execution records are not persisted to the original session file.
-- @satisfies REQ-208
+- @satisfies REQ-208, REQ-307
 
-### fn `function verifyPromptCommandSessionTarget(` (L598-642)
+### fn `function verifyPromptCommandSessionTarget(` (L595-639)
 - @brief Verifies that the active session file and cwd surfaces match one expected prompt-orchestration target.
 - @details Re-reads the persisted session-file header when present plus the host `process.cwd()` and throws on the first mismatch so prompt commands abort before prompt dispatch or prompt-end handling whenever session switching leaves execution attached to the wrong cwd. A missing persisted session file is treated as a non-fatal lazy-persistence state because pi's `SessionManager` writes session files on first assistant flush rather than eagerly during `ctx.switchSession(sessionPath)`; when the file is absent, pi aligns its internal session cwd to the live `process.cwd()`, so verifying `process.cwd()` alone is authoritative in that state. Reads of `ctx.cwd`, `ctx.sessionManager.getCwd()`, and `ctx.sessionManager.getSessionFile()` are advisory only because the pi `ctx.switchSession(sessionPath)` SDK contract does not mutate the handler-scoped `ctx` object, so those probes stay bound to the pre-switch session and a divergent value alone never triggers abort; they only surface a mismatch when they disagree with both the persisted header cwd and the live `process.cwd()`. Runtime is O(p) in aggregate path length plus one session-file header read. No external state is mutated.
 - @param[in] expectedSessionFile {string} Session file that must remain active.
@@ -2700,7 +2730,7 @@ import {
 - @throws {ReqError} Throws when the persisted session-file header cwd diverges from the expected target or when `process.cwd()` diverges from the expected target.
 - @satisfies REQ-257, REQ-272
 
-### fn `function verifyPromptCommandClosureArtifacts(` (L652-687)
+### fn `function verifyPromptCommandClosureArtifacts(` (L649-684)
 - @brief Verifies persisted prompt execution artifacts before successful closure merge.
 - @details Re-reads the persisted execution-session header, verifies the worktree path still exists, confirms the sibling worktree remains registered, and confirms the linked branch is still present before prompt-end closure attempts to restore `base-path` and merge from the original repository. Unlike prompt-start activation checks, this helper intentionally does not require the live process cwd or current session-bound context to remain on `worktree-path`, because pi CLI may already have started end-of-session session replacement or other post-run housekeeping before the extension finishes closure handling. Runtime is dominated by one session-file read, two git subprocess checks, and bounded filesystem probes. No external state is mutated.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
@@ -2708,7 +2738,7 @@ import {
 - @throws {ReqError} Throws when persisted execution-session metadata or worktree artifacts no longer match the expected worktree target.
 - @satisfies REQ-208, REQ-219, REQ-258, REQ-282
 
-### fn `async function switchPromptCommandSession(` (L698-727)
+### fn `async function switchPromptCommandSession(` (L695-724)
 - @brief Switches the active prompt session to one persisted session file when required.
 - @details Calls `ctx.switchSession(sessionPath, { withSession })` so current pi runtimes can expose a fresh replacement-session context for every post-switch session-bound operation. When a runtime ignores the callback, the helper falls back to the caller-supplied context and downstream verification continues to rely on the persisted session-file header plus `process.cwd()`. If pi surfaces only the documented stale-extension-context error while invalidating the old execution-session closure, the helper treats that side effect as non-fatal and lets downstream verification confirm whether the target session actually became active. Runtime is dominated by the session switch. Side effects include active-session replacement and cwd mutation by the host runtime.
 - @param[in] sessionFile {string} Target persisted session file.
@@ -2717,47 +2747,63 @@ import {
 - @throws {ReqError} Throws when the context cannot switch sessions, when the host cancels the switch, or when later verification proves the target session never became active.
 - @satisfies REQ-068, REQ-271, REQ-272
 
-### fn `function isPromptCommandStaleContextError(error: unknown): boolean` (L736-739)
+### fn `function isPromptCommandStaleContextError(error: unknown): boolean` (L733-736)
 - @brief Detects the documented stale-extension-context runtime error during prompt-command session switching.
 - @details Matches the guarded pi runtime error emitted when the old execution-session closure is invalidated during a session replacement or reload. Prompt-command session-switch helpers use this detector to distinguish a late stale-context side effect from genuine switch failures, then rely on post-switch verification to confirm whether the target session actually became active. Runtime is O(n) in message length only when an error is supplied. No external state is mutated.
 - @param[in] error {unknown} Candidate thrown value.
 - @return {boolean} `true` when the value matches the stale-extension-context runtime error.
 - @satisfies REQ-280
 
-### fn `function attachPromptCommandErrorContext(` (L748-756)
+### fn `function attachPromptCommandErrorContext(` (L745-753)
 - @brief Attaches the last valid prompt-command context to one thrown error.
 - @details Preserves the replacement-session context discovered after `ctx.switchSession(...)` so outer callers can continue UI notifications and cleanup without reusing stale pre-switch command objects. Runtime is O(1). Side effect: mutates the error object when it is an `Error` instance.
 - @param[in] error {unknown} Thrown value.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Last valid prompt-command context.
 - @return {unknown} Original thrown value with optional attached prompt context.
 
-### fn `export function getPromptCommandErrorContext(` (L764-770)
+### fn `export function getPromptCommandErrorContext(` (L761-767)
 - @brief Reads an attached prompt-command context from one thrown error.
 - @details Returns the replacement-session context captured by prompt orchestration helpers when a switch-triggered failure occurs after the original command context became stale. Runtime is O(1). No external state is mutated.
 - @param[in] error {unknown} Thrown value.
 - @return {PromptCommandSessionContext | undefined} Attached prompt-command context when available.
 
-### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L851-856)
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L845-850)
 - @brief Executes one git subprocess synchronously and captures UTF-8 output.
 - @details Delegates to `spawnSync`, preserves the supplied working directory, and returns the raw subprocess result used by prompt-command orchestration. Runtime is dominated by external process execution. Side effects include process spawning.
 - @param[in] command {string[]} Executable plus argument vector.
 - @param[in] cwd {string} Working directory for the subprocess.
 - @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### fn `export function setPromptCommandPostCreateHookForTests(` (L864-868)
+### fn `function listPromptTrackedBasePathChanges(basePath: string): string[]` (L860-878)
+- @brief Lists tracked `base-path` status rows that require stash-assisted merge handling.
+- @details Executes `git status --porcelain`, retains only tracked rows whose index or worktree slot reports a change, and excludes untracked or ignored rows because the required `git stash` command does not preserve them. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include process spawning.
+- @param[in] basePath {string} Restored project base path.
+- @return {string[]} Tracked status rows requiring stash-assisted merge handling.
+- @throws {ReqError} Throws when git status cannot be read from `basePath`.
+- @satisfies REQ-291
+
+### fn `function finalizePromptCommandMerge(` (L888-1010)
+- @brief Executes the successful-closure merge sequence from restored `base-path`.
+- @details Detects tracked staged or unstaged `base-path` changes, wraps the existing fast-forward merge in `git stash` and `git stash pop` when required, preserves the direct merge path when no tracked changes exist, emits a warning-only result after successful local-change restoration, and writes one merge-finalization debug entry when enabled. Runtime is dominated by up to four git subprocesses plus O(n) status parsing. Side effects include stash-stack mutation, branch merge attempts, and optional debug-log writes.
+- @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose branch should be merged.
+- @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
+- @return {{ mergeAttempted: boolean; mergeSucceeded: boolean; errorMessage?: string; warningMessage?: string }} Merge-attempt facts plus optional warning text.
+- @satisfies REQ-208, REQ-245, REQ-291, REQ-292
+
+### fn `export function setPromptCommandPostCreateHookForTests(` (L1018-1022)
 - @brief Stores or clears the prompt-command post-create test hook.
 - @details Enables deterministic simulation of post-create worktree verification failures without altering production control flow. Runtime is O(1). Side effect: mutates module-local test state.
 - @param[in] hook {PromptCommandPostCreateHook | undefined} Optional replacement hook.
 - @return {void} No return value.
 
-### fn `function resolvePromptDocsRoot(projectBase: string, config: UseReqConfig): string` (L877-880)
+### fn `function resolvePromptDocsRoot(projectBase: string, config: UseReqConfig): string` (L1031-1034)
 - @brief Resolves the configured docs root for one project base.
 - @details Joins the project base with the normalized `docs-dir` value while stripping trailing separators from the persisted config field. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] projectBase {string} Absolute project root.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Absolute canonical docs root path.
 
-### fn `function resolveWorktreePaths(` (L890-917)
+### fn `function resolveWorktreePaths(` (L1044-1071)
 - @brief Resolves the effective worktree project base relative to the git root.
 - @details Reuses the original project-base location relative to the git root so nested repository subdirectories remain aligned inside the sibling worktree. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] projectBase {string} Original absolute project base path.
@@ -2765,51 +2811,51 @@ import {
 - @param[in] worktreeName {string} Created worktree name.
 - @return {{ worktreePath: string; worktreeBasePath: string }} Derived worktree paths.
 
-### fn `function sanitizePromptWorktreeBranchName(branch: string): string` (L925-927)
+### fn `function sanitizePromptWorktreeBranchName(branch: string): string` (L1079-1081)
 - @brief Rewrites a branch name into a filesystem-safe token for prompt worktrees.
 - @details Replaces characters invalid for worktree directory and branch-name generation with `-`. Runtime is O(n). No external state is mutated.
 - @param[in] branch {string} Raw branch name.
 - @return {string} Sanitized token.
 
-### fn `function validatePromptWorktreeName(wtName: string): boolean` (L935-940)
+### fn `function validatePromptWorktreeName(wtName: string): boolean` (L1089-1094)
 - @brief Validates a prompt-command-generated worktree or branch name.
 - @details Rejects empty names, dot-path markers, whitespace, and filesystem-invalid characters. Runtime is O(n). No external state is mutated.
 - @param[in] wtName {string} Candidate worktree name.
 - @return {boolean} `true` when the name is acceptable for worktree creation.
 
-### fn `function throwPromptGitStatusError(): never` (L948-950)
+### fn `function throwPromptGitStatusError(): never` (L1102-1104)
 - @brief Throws the canonical prompt-command git-preflight failure.
 - @details Normalizes all repository-validation failures to the contractually stable prompt-command error string consumed by tests and downstream prompt workflows. Runtime is O(1). No external state is mutated.
 - @return {never} Always throws.
 - @throws {ReqError} Always throws with exit code `1`.
 
-### fn `function validatePromptGitState(projectBase: string, config?: UseReqConfig): string` (L961-1005)
-- @brief Runs prompt-command-owned git validation and returns the runtime git root.
-- @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
+### fn `export function validatePromptGitState(projectBase: string, config?: UseReqConfig): string` (L1115-1159)
+- @brief Runs slash-command-owned git validation and returns the runtime git root.
+- @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence for bundled prompt commands and `req-references` without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
 - @param[in] projectBase {string} Absolute current project base.
 - @param[in] config {UseReqConfig | undefined} Optional effective project configuration used to ignore extension-owned debug-log artifacts.
 - @return {string} Absolute runtime git root.
 - @throws {ReqError} Throws the canonical prompt-command git-preflight error on any validation failure.
 - @satisfies REQ-200, REQ-220
 
-### fn `function resolveCurrentPromptBranchName(gitRoot: string): string` (L1013-1018)
+### fn `function resolveCurrentPromptBranchName(gitRoot: string): string` (L1167-1172)
 - @brief Resolves the current local branch name used by prompt-command orchestration.
 - @details Reads `git branch --show-current`, falls back to `unknown` when git cannot provide a branch name, and preserves the raw branch token for later worktree-name generation and state tracking. Runtime is dominated by one git subprocess. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @return {string} Current branch name or `unknown` when unavailable.
 
-### fn `function formatPromptWorktreeExecutionId(timestamp: Date): string` (L1032-1034)
+### fn `function formatPromptWorktreeExecutionId(timestamp: Date): string` (L1186-1188)
 - @brief Formats one prompt-worktree execution identifier.
 - @details Serializes the supplied timestamp as `YYYYMMDDHHMMSS` with zero-padded calendar and clock fields so generated worktree names remain stable, lexicographically sortable, and requirement-compatible. Runtime is O(1). No external state is mutated.
 - @param[in] timestamp {Date} Timestamp to encode.
 - @return {string} Formatted execution identifier.
 
-### fn `function getNextPromptWorktreeExecutionId(): string` (L1041-1054)
+### fn `function getNextPromptWorktreeExecutionId(): string` (L1195-1208)
 - @brief Resolves the next unique prompt-worktree execution identifier.
 - @details Formats the current wall-clock second as `YYYYMMDDHHMMSS`, then monotonically advances by one-second steps until the identifier is strictly greater than the last value emitted in the current host process. This preserves the documented timestamp-only name shape while preventing immediate same-process worktree-name reuse after fast back-to-back prompt starts. Runtime is O(1) in the common case and O(k) in repeated same-second collisions. Side effect: mutates process-scoped execution-id persistence.
 - @return {string} Unique execution identifier for worktree naming.
 
-### fn `function buildPromptWorktreeName(gitRoot: string, config: UseReqConfig): string` (L1065-1076)
+### fn `function buildPromptWorktreeName(gitRoot: string, config: UseReqConfig): string` (L1219-1230)
 - @brief Builds the prompt-command worktree name without invoking agent-tool executors.
 - @details Combines the normalized persisted worktree prefix, repository basename, sanitized current branch, and timestamp execution identifier into the dedicated prompt-command worktree name. Runtime is O(1) plus git execution cost. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
@@ -2818,21 +2864,21 @@ import {
 - @throws {ReqError} Throws when the generated name is invalid.
 - @satisfies REQ-206, REQ-220
 
-### fn `function promptWorktreeBranchExists(gitRoot: string, branchName: string): boolean` (L1085-1094)
+### fn `function promptWorktreeBranchExists(gitRoot: string, branchName: string): boolean` (L1239-1248)
 - @brief Tests whether the exact prompt-command branch is present in the local branch list.
 - @details Queries `git branch --list --format=%(refname:short)` and returns a boolean without mutating repository state. Runtime is dominated by one git subprocess plus O(n) parsing in listed branch count. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @param[in] branchName {string} Candidate local branch name.
 - @return {boolean} `true` when the exact local branch is listed.
 
-### fn `function promptWorktreeRegistered(gitRoot: string, worktreePath: string): boolean` (L1103-1114)
+### fn `function promptWorktreeRegistered(gitRoot: string, worktreePath: string): boolean` (L1257-1268)
 - @brief Tests whether the exact prompt-command worktree is registered.
 - @details Scans `git worktree list --porcelain` for the resolved target path so cleanup and verification can distinguish registered worktrees from unrelated sibling directories. Runtime is dominated by one git subprocess plus O(n) parsing in listed worktree count. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @param[in] worktreePath {string} Absolute sibling worktree path.
 - @return {boolean} `true` when the exact path is registered as a git worktree.
 
-### fn `function cleanupPromptWorktreeCreation(` (L1124-1138)
+### fn `function cleanupPromptWorktreeCreation(` (L1278-1292)
 - @brief Removes partially created prompt-command worktree resources.
 - @details Force-removes the registered sibling worktree when present, deletes the matching local branch, and falls back to filesystem removal for leftover directories so failed prompt preflight leaves no reusable worktree residue. Runtime is dominated by git subprocess execution. Side effects include branch deletion and directory removal.
 - @param[in] gitRoot {string} Absolute runtime git root.
@@ -2840,7 +2886,7 @@ import {
 - @param[in] worktreeName {string} Exact worktree and branch name.
 - @return {void} No return value.
 
-### fn `function createPromptWorktree(` (L1152-1272)
+### fn `function createPromptWorktree(` (L1306-1426)
 - @brief Creates and verifies the prompt-command worktree and branch.
 - @details Creates the sibling worktree, mirrors project config when present, runs the optional post-create test hook, verifies git worktree registration, verifies git branch listing, verifies filesystem paths before prompt dispatch, and appends selected debug entries for worktree creation. Failed verification triggers immediate rollback. Runtime is dominated by git subprocess execution and filesystem metadata checks. Side effects include worktree creation, branch creation, directory creation, file copying, optional debug-log writes, and rollback on failure.
 - @param[in] projectBase {string} Absolute original project base.
@@ -2852,7 +2898,7 @@ import {
 - @throws {ReqError} Throws when worktree creation, verification, or rollback finalization fails.
 - @satisfies REQ-206, REQ-219, REQ-220, REQ-245
 
-### fn `function deletePromptWorktree(` (L1285-1345)
+### fn `export function deletePromptWorktree(` (L1439-1499)
 - @brief Deletes prompt-command worktree resources without invoking custom-tool executors.
 - @details Force-removes the sibling worktree and matching branch, verifies both are absent so prompt finalization remains independent from agent-tool implementations, and appends selected debug entries for worktree deletion. Runtime is dominated by git subprocess execution plus filesystem probes. Side effects include worktree deletion, branch deletion, and optional debug-log writes.
 - @param[in] projectBase {string} Absolute original project base.
@@ -2861,16 +2907,16 @@ import {
 - @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
 - @return {void} No return value.
 - @throws {ReqError} Throws when cleanup cannot remove the worktree and branch fully.
-- @satisfies REQ-208, REQ-220, REQ-245
+- @satisfies REQ-208, REQ-220, REQ-245, REQ-309
 
-### fn `export function getPromptRequiredDocs(promptName: PromptCommandName): readonly PromptRequiredDocSpec[]` (L1354-1356)
+### fn `export function getPromptRequiredDocs(promptName: PromptCommandName): readonly PromptRequiredDocSpec[]` (L1508-1510)
 - @brief Returns the canonical required-document probes for one prompt command.
 - @details Performs a constant-time lookup in the prompt-doc matrix used by command preflight validation. No filesystem access occurs.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
 - @return {readonly PromptRequiredDocSpec[]} Required-doc definitions in probe order.
 - @satisfies REQ-201, REQ-202
 
-### fn `export function validatePromptRequiredDocs(` (L1369-1420)
+### fn `export function validatePromptRequiredDocs(` (L1523-1574)
 - @brief Runs prompt-specific required-document validation.
 - @details Resolves the configured docs root, verifies the prompt-mapped canonical docs exist as files, throws a deterministic remediation error for the first missing document, and appends selected debug entries for required-doc checks. Runtime is O(d) in required-doc count plus filesystem metadata cost. Side effects are limited to filesystem reads and optional debug-log writes.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -2881,7 +2927,7 @@ import {
 - @throws {ReqError} Throws when a required canonical doc is missing.
 - @satisfies REQ-201, REQ-202, REQ-203, REQ-245
 
-### fn `export function preparePromptCommandExecution(` (L1437-1513)
+### fn `export function preparePromptCommandExecution(` (L1591-1667)
 - @brief Prepares prompt-command execution for one bundled prompt.
 - @details Runs slash-command-owned git validation, enforces the prompt-specific required-doc matrix, resolves persisted origin and execution session files, applies the effective worktree policy, generates and verifies a dedicated worktree when enabled, and returns the execution plan consumed by prompt rendering plus lifecycle hooks. Worktree-backed execution reuses the active session directory for the forked session file. Runtime is dominated by git subprocesses, worktree creation, and optional session-file cloning. Side effects include worktree creation, session-file creation, filesystem reads, and optional prompt debug-log writes.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -2896,7 +2942,7 @@ import {
 - @throws {ReqError} Throws when repository validation, required-doc validation, worktree creation, or session preparation fails.
 - @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271
 
-### fn `export async function activatePromptCommandExecution(` (L1524-1557)
+### fn `export async function activatePromptCommandExecution(` (L1678-1711)
 - @brief Activates the prepared prompt execution path before prompt dispatch or agent start.
 - @details Switches the active session to the execution-session file when worktree routing changed the cwd, re-aligns `process.cwd()` to the execution path, verifies active-session cwd plus cwd mirrors after the switch completes, and stores the verified command-capable replacement-session context for later closure handling. Runtime is dominated by the optional session switch and one optional cwd mutation. Side effects include active-session replacement, host-process cwd mutation, runtime-path state mutation, and process-scoped command-context persistence.
 - @param[in] plan {PromptCommandExecutionPlan} Prepared prompt execution plan.
@@ -2905,7 +2951,7 @@ import {
 - @throws {ReqError} Throws when the session switch or cwd verification fails.
 - @satisfies REQ-206, REQ-207, REQ-257, REQ-272, REQ-276
 
-### fn `export async function restorePromptCommandExecution(` (L1569-1633)
+### fn `export async function restorePromptCommandExecution(` (L1723-1787)
 - @brief Restores the original project base path before merge or session-closure return.
 - @details Switches the active session back to the original session file when worktree routing changed the cwd, re-aligns `process.cwd()` to `base-path`, verifies the restored session target, reuses the persisted replacement-session context when lifecycle handlers receive non-command contexts, tolerates the documented stale-extension-context error when the old replacement-session closure becomes invalid immediately after a successful restore, emits optional workflow restoration debug entries, and clears active worktree path facts before session closure continues. Runtime is dominated by the optional session switch and one optional cwd mutation. Side effects include active-session replacement, host-process cwd mutation, runtime-path state mutation, and optional workflow-debug writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original base should be restored.
@@ -2915,7 +2961,7 @@ import {
 - @throws {ReqError} Throws when the session switch or cwd verification fails.
 - @satisfies REQ-208, REQ-209, REQ-245, REQ-257, REQ-272, REQ-276
 
-### fn `export async function abortPromptCommandExecution(` (L1644-1690)
+### fn `export async function abortPromptCommandExecution(` (L1798-1844)
 - @brief Aborts one prepared prompt-command execution before pi CLI takes ownership.
 - @details Restores the original session-backed cwd and deletes any created worktree plus branch when command-side preflight, prompt rendering, or prompt handoff fails before agent completion. Restoration failures are returned as structured cleanup errors so the original preflight failure is not masked. Runtime is dominated by the optional session switch plus git subprocess execution. Side effects include active-session replacement, optional worktree deletion, and optional debug-log writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prepared prompt execution plan.
@@ -2924,16 +2970,16 @@ import {
 - @return {Promise<{ cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Abort-cleanup facts plus the last valid active prompt-command context.
 - @satisfies REQ-226, REQ-220, REQ-245
 
-### fn `export async function finalizePromptCommandExecution(` (L1701-1804)
+### fn `export async function finalizePromptCommandExecution(` (L1855-1943)
 - @brief Finalizes one matched successful worktree-backed prompt execution.
-- @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
+- @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, executes the stash-assisted fast-forward merge sequence from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, stash-stack mutation, worktree deletion, and optional debug-log writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Optional prompt-command context.
 - @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
-- @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
-- @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282
+- @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; warningMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
+- @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282, REQ-291, REQ-292
 
-### fn `export function classifyPromptCommandOutcome(` (L1812-1816)
+### fn `export function classifyPromptCommandOutcome(` (L1951-1955)
 - @brief Maps one `agent_end` payload into the canonical prompt-worktree finalization outcome.
 - @details Delegates to the shared notification outcome classifier so worktree merge and fork-session retention decisions stay aligned with prompt-end notification routing. Runtime is O(m) in assistant message count. No external state is mutated.
 - @param[in] event {Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
@@ -2942,60 +2988,62 @@ import {
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PromptRequiredDocSpec`|iface||45-48|export interface PromptRequiredDocSpec|
-|`PromptCommandExecutionPlan`|iface||54-68|export interface PromptCommandExecutionPlan|
-|`PromptCommandPostCreateHookContext`|iface||74-79|interface PromptCommandPostCreateHookContext|
-|`PromptCommandPostCreateHook`|type||85||
-|`PromptCommandDebugOptions`|iface||91-94|interface PromptCommandDebugOptions|
-|`PromptCommandSessionMessageOptions`|iface||100-102|interface PromptCommandSessionMessageOptions|
-|`PromptCommandSessionSwitchOptions`|iface||108-110|interface PromptCommandSessionSwitchOptions|
-|`PromptCommandActiveContext`|iface||116-121|interface PromptCommandActiveContext extends PromptComman...|
-|`PromptCommandSessionEntry`|iface||127-133|interface PromptCommandSessionEntry|
-|`PromptCommandSessionContext`|iface||139-151|interface PromptCommandSessionContext|
-|`PromptCommandContextError`|iface||157-159|interface PromptCommandContextError extends Error|
-|`isUsablePromptSessionFile`|fn||174-192|function isUsablePromptSessionFile(|
-|`resolvePromptSessionFile`|fn||202-212|function resolvePromptSessionFile(sessionFile: string | u...|
-|`writePromptExecutionSessionSnapshot`|fn||226-252|function writePromptExecutionSessionSnapshot(|
-|`createPromptExecutionSessionFile`|fn||265-288|function createPromptExecutionSessionFile(|
-|`getPromptSessionCwd`|fn||296-304|function getPromptSessionCwd(ctx?: PromptCommandSessionCo...|
-|`getPromptSessionFile`|fn||312-320|function getPromptSessionFile(ctx?: PromptCommandSessionC...|
-|`getPromptContextCwd`|fn||328-334|function getPromptContextCwd(ctx?: PromptCommandSessionCo...|
-|`resolvePromptCommandSwitchContext`|fn||344-359|function resolvePromptCommandSwitchContext(|
-|`syncPromptCommandProcessCwd`|fn||370-390|function syncPromptCommandProcessCwd(expectedPath: string...|
-|`readPromptSessionFileCwd`|fn||398-422|function readPromptSessionFileCwd(sessionFile: string): s...|
-|`readPromptSessionJsonLines`|fn||431-478|function readPromptSessionJsonLines(|
-|`preservePromptCommandExecutionTranscript`|fn||488-585|function preservePromptCommandExecutionTranscript(plan: P...|
-|`verifyPromptCommandSessionTarget`|fn||598-642|function verifyPromptCommandSessionTarget(|
-|`verifyPromptCommandClosureArtifacts`|fn||652-687|function verifyPromptCommandClosureArtifacts(|
-|`switchPromptCommandSession`|fn||698-727|async function switchPromptCommandSession(|
-|`isPromptCommandStaleContextError`|fn||736-739|function isPromptCommandStaleContextError(error: unknown)...|
-|`attachPromptCommandErrorContext`|fn||748-756|function attachPromptCommandErrorContext(|
-|`getPromptCommandErrorContext`|fn||764-770|export function getPromptCommandErrorContext(|
-|`runCapture`|fn||851-856|function runCapture(command: string[], cwd: string): Retu...|
-|`setPromptCommandPostCreateHookForTests`|fn||864-868|export function setPromptCommandPostCreateHookForTests(|
-|`resolvePromptDocsRoot`|fn||877-880|function resolvePromptDocsRoot(projectBase: string, confi...|
-|`resolveWorktreePaths`|fn||890-917|function resolveWorktreePaths(|
-|`sanitizePromptWorktreeBranchName`|fn||925-927|function sanitizePromptWorktreeBranchName(branch: string)...|
-|`validatePromptWorktreeName`|fn||935-940|function validatePromptWorktreeName(wtName: string): boolean|
-|`throwPromptGitStatusError`|fn||948-950|function throwPromptGitStatusError(): never|
-|`validatePromptGitState`|fn||961-1005|function validatePromptGitState(projectBase: string, conf...|
-|`resolveCurrentPromptBranchName`|fn||1013-1018|function resolveCurrentPromptBranchName(gitRoot: string):...|
-|`formatPromptWorktreeExecutionId`|fn||1032-1034|function formatPromptWorktreeExecutionId(timestamp: Date)...|
-|`getNextPromptWorktreeExecutionId`|fn||1041-1054|function getNextPromptWorktreeExecutionId(): string|
-|`buildPromptWorktreeName`|fn||1065-1076|function buildPromptWorktreeName(gitRoot: string, config:...|
-|`promptWorktreeBranchExists`|fn||1085-1094|function promptWorktreeBranchExists(gitRoot: string, bran...|
-|`promptWorktreeRegistered`|fn||1103-1114|function promptWorktreeRegistered(gitRoot: string, worktr...|
-|`cleanupPromptWorktreeCreation`|fn||1124-1138|function cleanupPromptWorktreeCreation(|
-|`createPromptWorktree`|fn||1152-1272|function createPromptWorktree(|
-|`deletePromptWorktree`|fn||1285-1345|function deletePromptWorktree(|
-|`getPromptRequiredDocs`|fn||1354-1356|export function getPromptRequiredDocs(promptName: PromptC...|
-|`validatePromptRequiredDocs`|fn||1369-1420|export function validatePromptRequiredDocs(|
-|`preparePromptCommandExecution`|fn||1437-1513|export function preparePromptCommandExecution(|
-|`activatePromptCommandExecution`|fn||1524-1557|export async function activatePromptCommandExecution(|
-|`restorePromptCommandExecution`|fn||1569-1633|export async function restorePromptCommandExecution(|
-|`abortPromptCommandExecution`|fn||1644-1690|export async function abortPromptCommandExecution(|
-|`finalizePromptCommandExecution`|fn||1701-1804|export async function finalizePromptCommandExecution(|
-|`classifyPromptCommandOutcome`|fn||1812-1816|export function classifyPromptCommandOutcome(|
+|`PromptRequiredDocSpec`|iface||42-45|export interface PromptRequiredDocSpec|
+|`PromptCommandExecutionPlan`|iface||51-65|export interface PromptCommandExecutionPlan|
+|`PromptCommandPostCreateHookContext`|iface||71-76|interface PromptCommandPostCreateHookContext|
+|`PromptCommandPostCreateHook`|type||82||
+|`PromptCommandDebugOptions`|iface||88-91|interface PromptCommandDebugOptions|
+|`PromptCommandSessionMessageOptions`|iface||97-99|interface PromptCommandSessionMessageOptions|
+|`PromptCommandSessionSwitchOptions`|iface||105-107|interface PromptCommandSessionSwitchOptions|
+|`PromptCommandActiveContext`|iface||113-118|interface PromptCommandActiveContext extends PromptComman...|
+|`PromptCommandSessionEntry`|iface||124-130|interface PromptCommandSessionEntry|
+|`PromptCommandSessionContext`|iface||136-148|interface PromptCommandSessionContext|
+|`PromptCommandContextError`|iface||154-156|interface PromptCommandContextError extends Error|
+|`isUsablePromptSessionFile`|fn||171-189|function isUsablePromptSessionFile(|
+|`resolvePromptSessionFile`|fn||199-209|function resolvePromptSessionFile(sessionFile: string | u...|
+|`writePromptExecutionSessionSnapshot`|fn||223-249|function writePromptExecutionSessionSnapshot(|
+|`createPromptExecutionSessionFile`|fn||262-285|function createPromptExecutionSessionFile(|
+|`getPromptSessionCwd`|fn||293-301|function getPromptSessionCwd(ctx?: PromptCommandSessionCo...|
+|`getPromptSessionFile`|fn||309-317|function getPromptSessionFile(ctx?: PromptCommandSessionC...|
+|`getPromptContextCwd`|fn||325-331|function getPromptContextCwd(ctx?: PromptCommandSessionCo...|
+|`resolvePromptCommandSwitchContext`|fn||341-356|function resolvePromptCommandSwitchContext(|
+|`syncPromptCommandProcessCwd`|fn||367-387|function syncPromptCommandProcessCwd(expectedPath: string...|
+|`readPromptSessionFileCwd`|fn||395-419|function readPromptSessionFileCwd(sessionFile: string): s...|
+|`readPromptSessionJsonLines`|fn||428-475|function readPromptSessionJsonLines(|
+|`preservePromptCommandExecutionTranscript`|fn||485-582|export function preservePromptCommandExecutionTranscript(...|
+|`verifyPromptCommandSessionTarget`|fn||595-639|function verifyPromptCommandSessionTarget(|
+|`verifyPromptCommandClosureArtifacts`|fn||649-684|function verifyPromptCommandClosureArtifacts(|
+|`switchPromptCommandSession`|fn||695-724|async function switchPromptCommandSession(|
+|`isPromptCommandStaleContextError`|fn||733-736|function isPromptCommandStaleContextError(error: unknown)...|
+|`attachPromptCommandErrorContext`|fn||745-753|function attachPromptCommandErrorContext(|
+|`getPromptCommandErrorContext`|fn||761-767|export function getPromptCommandErrorContext(|
+|`runCapture`|fn||845-850|function runCapture(command: string[], cwd: string): Retu...|
+|`listPromptTrackedBasePathChanges`|fn||860-878|function listPromptTrackedBasePathChanges(basePath: strin...|
+|`finalizePromptCommandMerge`|fn||888-1010|function finalizePromptCommandMerge(|
+|`setPromptCommandPostCreateHookForTests`|fn||1018-1022|export function setPromptCommandPostCreateHookForTests(|
+|`resolvePromptDocsRoot`|fn||1031-1034|function resolvePromptDocsRoot(projectBase: string, confi...|
+|`resolveWorktreePaths`|fn||1044-1071|function resolveWorktreePaths(|
+|`sanitizePromptWorktreeBranchName`|fn||1079-1081|function sanitizePromptWorktreeBranchName(branch: string)...|
+|`validatePromptWorktreeName`|fn||1089-1094|function validatePromptWorktreeName(wtName: string): boolean|
+|`throwPromptGitStatusError`|fn||1102-1104|function throwPromptGitStatusError(): never|
+|`validatePromptGitState`|fn||1115-1159|export function validatePromptGitState(projectBase: strin...|
+|`resolveCurrentPromptBranchName`|fn||1167-1172|function resolveCurrentPromptBranchName(gitRoot: string):...|
+|`formatPromptWorktreeExecutionId`|fn||1186-1188|function formatPromptWorktreeExecutionId(timestamp: Date)...|
+|`getNextPromptWorktreeExecutionId`|fn||1195-1208|function getNextPromptWorktreeExecutionId(): string|
+|`buildPromptWorktreeName`|fn||1219-1230|function buildPromptWorktreeName(gitRoot: string, config:...|
+|`promptWorktreeBranchExists`|fn||1239-1248|function promptWorktreeBranchExists(gitRoot: string, bran...|
+|`promptWorktreeRegistered`|fn||1257-1268|function promptWorktreeRegistered(gitRoot: string, worktr...|
+|`cleanupPromptWorktreeCreation`|fn||1278-1292|function cleanupPromptWorktreeCreation(|
+|`createPromptWorktree`|fn||1306-1426|function createPromptWorktree(|
+|`deletePromptWorktree`|fn||1439-1499|export function deletePromptWorktree(|
+|`getPromptRequiredDocs`|fn||1508-1510|export function getPromptRequiredDocs(promptName: PromptC...|
+|`validatePromptRequiredDocs`|fn||1523-1574|export function validatePromptRequiredDocs(|
+|`preparePromptCommandExecution`|fn||1591-1667|export function preparePromptCommandExecution(|
+|`activatePromptCommandExecution`|fn||1678-1711|export async function activatePromptCommandExecution(|
+|`restorePromptCommandExecution`|fn||1723-1787|export async function restorePromptCommandExecution(|
+|`abortPromptCommandExecution`|fn||1798-1844|export async function abortPromptCommandExecution(|
+|`finalizePromptCommandExecution`|fn||1855-1943|export async function finalizePromptCommandExecution(|
+|`classifyPromptCommandOutcome`|fn||1951-1955|export function classifyPromptCommandOutcome(|
 
 
 ---
@@ -3093,7 +3141,7 @@ import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 
 ---
 
-# prompts.ts | TypeScript | 316L | 9 symbols | 7 imports | 17 comments
+# prompts.ts | TypeScript | 314L | 9 symbols | 7 imports | 17 comments
 > Path: `src/core/prompts.ts`
 - @brief Renders bundled pi-usereq prompts for the current project context.
 - @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
@@ -3111,7 +3159,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 
 ## Definitions
 
-### fn `function buildPiDevConformanceBlock(promptName: string, projectBase: string): string` (L111-120)
+### fn `function buildPiDevConformanceBlock(promptName: string, projectBase: string): string` (L109-118)
 - @brief Builds the conditional pi.dev governance block for one rendered prompt.
 - @details Emits the manifest-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
 - @param[in] promptName {string} Bundled prompt identifier.
@@ -3119,7 +3167,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Markdown bullet block or the empty string when injection is not applicable.
 - @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
 
-### fn `function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string` (L131-138)
+### fn `function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string` (L129-136)
 - @brief Injects the pi.dev governance block into the prompt behavior section.
 - @details Inserts the block immediately after the `## Behavior` heading so downstream agents evaluate the rule before workflow steps. Leaves prompts unchanged when no behavior section exists or the block is already present. Time complexity O(n).
 - @param[in] text {string} Prompt markdown after placeholder replacement.
@@ -3128,14 +3176,14 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Prompt markdown with zero or one injected conformance block.
 - @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
 
-### fn `export function adaptPromptForInternalTools(text: string): string` (L147-153)
+### fn `export function adaptPromptForInternalTools(text: string): string` (L145-151)
 - @brief Rewrites bundled prompt tool references from legacy `req --...` syntax to internal tool names.
 - @details Applies deterministic global regex replacements so prompt text matches the extension-registered tool surface instead of the standalone CLI spelling. Time complexity O(p*r) where p is pattern count and r is prompt length.
 - @param[in] text {string} Prompt markdown before tool-reference normalization.
 - @return {string} Prompt markdown with internal tool names.
 - @satisfies REQ-003
 
-### fn `export function applyReplacements(text: string, replacements: Record<string, string>): string` (L163-169)
+### fn `export function applyReplacements(text: string, replacements: Record<string, string>): string` (L161-167)
 - @brief Applies literal placeholder replacements to bundled prompt markdown.
 - @details Replaces every placeholder token using split/join semantics so all occurrences are updated without regex escaping. Time complexity O(t*n) where t is replacement count and n is prompt length.
 - @param[in] text {string} Prompt markdown containing placeholder tokens.
@@ -3143,7 +3191,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Prompt markdown with all placeholder tokens expanded.
 - @satisfies REQ-002
 
-### fn `function buildPromptExecutionBlock(` (L179-201)
+### fn `function buildPromptExecutionBlock(` (L177-199)
 - @brief Builds the prompt-command execution block injected at prompt start.
 - @details Serializes the already-completed repository validation, prompt-specific required-doc validation, worktree routing decision, and extension-owned lifecycle responsibilities so downstream agents do not repeat command-side orchestration. Time complexity is O(d) in required-doc count. No external state is mutated.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -3151,7 +3199,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Markdown block or the empty string when runtime execution metadata is unavailable.
 - @satisfies REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209
 
-### fn `function injectPromptExecutionBlock(` (L211-222)
+### fn `function injectPromptExecutionBlock(` (L209-220)
 - @brief Injects the prompt-command execution block near the start of the rendered prompt.
 - @details Inserts the execution block immediately after the first level-1 heading so downstream agents evaluate extension-owned orchestration before workflow steps. Leaves prompts unchanged when no execution block is provided or when the block is already present. Time complexity O(n).
 - @param[in] text {string} Prompt markdown after placeholder replacement.
@@ -3159,7 +3207,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Prepared execution plan.
 - @return {string} Prompt markdown with zero or one injected execution block.
 
-### fn `function buildPromptReplacements(` (L234-246)
+### fn `function buildPromptReplacements(` (L232-244)
 - @brief Builds prompt-specific runtime placeholder replacements.
 - @details Merges shared path substitutions with prompt-scoped runtime values for `%%ARGS%%` and `%%PROMPT%%`. Time complexity is O(g log g + s) due to delegated path replacement building, where g is guideline count and s is source-directory count. Side effects are limited to filesystem reads delegated to shared path-context helpers.
 - @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
@@ -3169,7 +3217,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {Record<string, string>} Prompt-specific placeholder-to-value map.
 - @satisfies REQ-002, REQ-211
 
-### fn `function renderBundledCommitInstruction(` (L258-272)
+### fn `function renderBundledCommitInstruction(` (L256-270)
 - @brief Renders the bundled git instruction injected through `%%COMMIT%%`.
 - @details Selects `resources/instructions/git_commit.md` when automatic git commit is enabled and `resources/instructions/git_read-only.md` otherwise, then applies the same runtime placeholder substitutions used by bundled prompts before returning the rendered markdown. Time complexity is O(n + g log g + s) where n is instruction size, g is guideline count, and s is source-directory count. Side effects are limited to filesystem reads.
 - @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
@@ -3179,7 +3227,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Rendered bundled git instruction selected for the current automatic-commit mode.
 - @satisfies REQ-211, REQ-213, REQ-214
 
-### fn `export function renderPrompt(` (L285-316)
+### fn `export function renderPrompt(` (L283-314)
 - @brief Renders a bundled prompt for the current project context.
 - @details Loads the bundled markdown template, expands configuration-derived placeholders, injects extension-owned execution guidance plus conditional pi.dev governance guidance, expands the optional bundled commit instruction, and rewrites legacy tool references to internal names. Time complexity O(n) relative to prompt size plus delegated commit-instruction rendering. No tracked files are modified.
 - @param[in] promptName {string} Bundled prompt identifier.
@@ -3193,211 +3241,223 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`buildPiDevConformanceBlock`|fn||111-120|function buildPiDevConformanceBlock(promptName: string, p...|
-|`injectPiDevConformanceBlock`|fn||131-138|function injectPiDevConformanceBlock(text: string, prompt...|
-|`adaptPromptForInternalTools`|fn||147-153|export function adaptPromptForInternalTools(text: string)...|
-|`applyReplacements`|fn||163-169|export function applyReplacements(text: string, replaceme...|
-|`buildPromptExecutionBlock`|fn||179-201|function buildPromptExecutionBlock(|
-|`injectPromptExecutionBlock`|fn||211-222|function injectPromptExecutionBlock(|
-|`buildPromptReplacements`|fn||234-246|function buildPromptReplacements(|
-|`renderBundledCommitInstruction`|fn||258-272|function renderBundledCommitInstruction(|
-|`renderPrompt`|fn||285-316|export function renderPrompt(|
+|`buildPiDevConformanceBlock`|fn||109-118|function buildPiDevConformanceBlock(promptName: string, p...|
+|`injectPiDevConformanceBlock`|fn||129-136|function injectPiDevConformanceBlock(text: string, prompt...|
+|`adaptPromptForInternalTools`|fn||145-151|export function adaptPromptForInternalTools(text: string)...|
+|`applyReplacements`|fn||161-167|export function applyReplacements(text: string, replaceme...|
+|`buildPromptExecutionBlock`|fn||177-199|function buildPromptExecutionBlock(|
+|`injectPromptExecutionBlock`|fn||209-220|function injectPromptExecutionBlock(|
+|`buildPromptReplacements`|fn||232-244|function buildPromptReplacements(|
+|`renderBundledCommitInstruction`|fn||256-270|function renderBundledCommitInstruction(|
+|`renderPrompt`|fn||283-314|export function renderPrompt(|
 
 
 ---
 
-# reference-payload.ts | TypeScript | 752L | 28 symbols | 5 imports | 27 comments
-> Path: `src/core/reference-payload.ts`
-- @brief Builds agent-oriented JSON payloads for `files-references` and `references`.
-- @details Converts analyzed source files into deterministic JSON sections ordered for LLM traversal, including repository structure, per-file metrics, imports, symbols, structured Doxygen fields, and structured comment evidence. Runtime is O(F log F + S) where F is file count and S is total source size. Side effects are limited to filesystem reads and optional stderr logging.
+# req-references-command.ts | TypeScript | 175L | 7 symbols | 6 imports | 10 comments
+> Path: `src/core/req-references-command.ts`
+- @brief Implements the specialized `req-references` slash-command workflow.
+- @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
 
 ## Imports
 ```
-import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
-import {
-import { detectLanguage } from "./compress.js";
-import {
+import type { UseReqConfig } from "./config.js";
+import { ReqError } from "./errors.js";
+import { validatePromptGitState } from "./prompt-command-runtime.js";
+import { runReferences } from "./tool-runner.js";
 ```
 
 ## Definitions
 
-- type `export type ReferenceToolScope = "explicit-files" | "configured-source-directories";` (L27)
-- @brief Enumerates supported references-payload scopes.
-- @details Distinguishes explicit-file requests from configured project scans while preserving one stable JSON contract. The alias is compile-time only and introduces no runtime cost.
-- type `export type ReferenceFileStatus = "analyzed" | "error" | "skipped";` (L33)
-- @brief Enumerates supported per-file references entry statuses.
-- @details Separates analyzed files, analysis failures, and skipped inputs so downstream agents can branch without reparsing stderr text. The alias is compile-time only and introduces no runtime cost.
-### iface `export interface ReferenceLineRange` (L39-43)
-- @brief Describes one numeric source line range.
-- @details Exposes start and end line numbers plus the same inclusive range as a numeric tuple for direct agent access. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceImportEntry extends ReferenceLineRange` : ReferenceLineRange (L49-52)
-- @brief Describes one structured import record.
-- @details Stores the normalized import identity, raw import statement, and declaration line range without requiring agents to parse markdown blocks. The interface is compile-time only and introduces no runtime cost.
+### iface `export interface ReqReferencesCommandPlan` (L30-35)
+- @brief Describes the prepared execution facts for one `req-references` run.
+- @details Stores the validated project base, resolved git root, target references path, and fixed commit message needed by the specialized direct-write workflow. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface ReferenceCommentEntry extends ReferenceLineRange` : ReferenceLineRange (L58-61)
-- @brief Describes one structured standalone or attached comment record.
-- @details Preserves normalized comment text plus per-line comment fragments so agents can consume comment evidence without reparsing source delimiters. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceExitPointEntry` (L67-70)
-- @brief Describes one structured exit-point annotation.
-- @details Preserves the normalized exit expression text together with its source line number for downstream reasoning about control flow hints. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceSymbolEntry extends ReferenceLineRange` : ReferenceLineRange (L76-96)
-- @brief Describes one structured symbol record.
-- @details Orders direct-access identity fields before hierarchy, locations, Doxygen metadata, and comment evidence so agents can branch without reparsing monolithic summaries. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolFileEntry extends ReferenceLineRange` : ReferenceLineRange (L102-115)
-- @brief Describes one per-file references payload entry.
-- @details Stores canonical identity, line metrics, structured imports, structured symbols, structured comment evidence, and optional file-level Doxygen metadata. Derivable identity and filesystem-probe fields are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolRequestSection` (L121-130)
-- @brief Describes the request section of the references payload.
-- @details Captures tool identity, scope, base directory, requested path inventory, and configured source-directory scope so agents can reason about how the file set was selected. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolSummarySection` (L136-147)
-- @brief Describes the summary section of the references payload.
-- @details Exposes aggregate file, symbol, import, comment, and Doxygen counts as numeric fields plus deterministic symbol-kind totals. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceRepositoryTreeNode` (L153-159)
-- @brief Describes one repository tree node in the references payload.
-- @details Encodes directory and file hierarchy without ASCII-art decoration so agents can traverse repository structure as structured JSON. The interface is compile-time only and introduces no runtime cost.
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L44-49)
+- @brief Executes one synchronous subprocess and captures UTF-8 output.
+- @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
+- @param[in] command {string[]} Executable plus argument vector.
+- @param[in] cwd {string} Working directory for the subprocess.
+- @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### iface `export interface ReferenceToolRepositorySection` (L165-169)
-- @brief Describes the repository section of the references payload.
-- @details Stores configured source-directory scope, the canonical analyzed file list, and the structured directory tree used during analysis. Static root-path echoes are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
+### fn `function buildIgnoredGitStatusPaths(` (L59-73)
+- @brief Builds the set of git-status paths ignored for cleanliness checks.
+- @details Reuses the configured debug-log path exception already honored by prompt-command git validation so extension-owned debug artifacts do not block `req-references` execution or post-commit cleanliness verification. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {Set<string>} Slash-normalized relative paths ignored during git-status evaluation.
 
-### iface `export interface ReferenceToolPayload` (L175-179)
-- @brief Describes the full agent-oriented references payload.
-- @details Exposes only aggregate analysis totals, repository structure, and per-file reference records, omitting request echoes that are already known to the caller or encoded in the tool registration. The interface is compile-time only and introduces no runtime cost.
+### fn `function listResidualGitStatusLines(` (L84-102)
+- @brief Lists residual git-status rows after ignored extension-owned paths are filtered out.
+- @details Executes `git status --porcelain`, drops the configured debug-log path when present inside the active repository, and returns all remaining staged or unstaged rows used for post-commit cleanliness verification. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include subprocess creation.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {string[]} Residual status rows after ignored paths are removed.
+- @throws {ReqError} Throws when git status cannot be inspected.
+
+### fn `function getGitAddTargetPath(gitRoot: string, absolutePath: string): string` (L111-117)
+- @brief Converts one absolute repository path into the preferred git-add target syntax.
+- @details Emits a slash-normalized relative path when the target is inside the git root and falls back to the absolute path otherwise, preserving deterministic add semantics across nested project-base layouts. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] absolutePath {string} Absolute path to stage.
+- @return {string} Relative or absolute git-add target path.
+
+### fn `export function prepareReqReferencesCommandExecution(` (L128-141)
+- @brief Prepares the specialized `req-references` execution plan.
+- @details Reuses slash-command-owned git validation, resolves the configured references document path, and returns the fixed commit metadata consumed by the direct-write workflow. Runtime is dominated by git validation subprocesses. Side effects include subprocess creation delegated through `validatePromptGitState(...)`.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {ReqReferencesCommandPlan} Prepared execution plan for direct references regeneration.
+- @throws {ReqError} Throws when git validation fails.
+- @satisfies REQ-200, REQ-299
+
+### fn `export function executeReqReferencesCommandExecution(` (L152-175)
+- @brief Executes the specialized `req-references` direct-write workflow.
+- @details Regenerates `REFERENCES.md` through the same source-summary path used by the `references` tool, stages only the target file, creates the fixed-message commit, and verifies that no residual git-status rows remain after ignored extension-owned debug artifacts are filtered out. Runtime is dominated by summary generation plus three git subprocesses. Side effects include documentation writes, index mutation, commit creation, and subprocess creation.
+- @param[in] plan {ReqReferencesCommandPlan} Prepared direct-write execution plan.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {void} No return value.
+- @throws {ReqError} Throws when reference generation, staging, commit creation, or cleanliness verification fails.
+- @satisfies REQ-300, REQ-301, REQ-302, REQ-303
 
-### iface `export interface BuildReferenceToolPayloadOptions` (L185-192)
-- @brief Describes the options required to build one references payload.
-- @details Supplies tool identity, scope, base directory, requested paths, and optional configured source directories while keeping payload construction deterministic. The interface is compile-time only and introduces no runtime cost.
+## Symbol Index
+|Symbol|Kind|Vis|Lines|Sig|
+|---|---|---|---|---|
+|`ReqReferencesCommandPlan`|iface||30-35|export interface ReqReferencesCommandPlan|
+|`runCapture`|fn||44-49|function runCapture(command: string[], cwd: string): Retu...|
+|`buildIgnoredGitStatusPaths`|fn||59-73|function buildIgnoredGitStatusPaths(|
+|`listResidualGitStatusLines`|fn||84-102|function listResidualGitStatusLines(|
+|`getGitAddTargetPath`|fn||111-117|function getGitAddTargetPath(gitRoot: string, absolutePat...|
+|`prepareReqReferencesCommandExecution`|fn||128-141|export function prepareReqReferencesCommandExecution(|
+|`executeReqReferencesCommandExecution`|fn||152-175|export function executeReqReferencesCommandExecution(|
 
-### fn `function canonicalizeReferencePath(targetPath: string, baseDir: string): string` (L201-209)
-- @brief Canonicalizes one filesystem path relative to the payload base directory.
-- @details Emits a slash-normalized relative path when the target is under the base directory; otherwise emits the normalized absolute path. Runtime is O(p) in path length. No side effects occur.
-- @param[in] targetPath {string} Absolute or relative filesystem path.
-- @param[in] baseDir {string} Base directory used for relative canonicalization.
-- @return {string} Canonicalized path string.
 
-### fn `function buildLineRange(startLineNumber: number, endLineNumber: number): ReferenceLineRange` (L218-224)
-- @brief Builds one structured line-range record.
-- @details Duplicates the inclusive range as start, end, and tuple fields so callers can address whichever shape is most convenient. Runtime is O(1). No side effects occur.
-- @param[in] startLineNumber {number} Inclusive start line number.
-- @param[in] endLineNumber {number} Inclusive end line number.
-- @return {ReferenceLineRange} Structured line-range record.
+---
 
-### fn `function extractCommentText(commentElement: SourceElement, maxLength = 0): string` (L233-253)
-- @brief Extracts normalized plain text from one comment element.
-- @details Removes language comment markers, drops delimiter-only lines, joins content with spaces, and optionally truncates the result. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Comment element.
-- @param[in] maxLength {number} Optional maximum output length; `0` disables truncation.
-- @return {string} Cleaned comment text.
+# req-reset-command.ts | TypeScript | 323L | 12 symbols | 7 imports | 14 comments
+> Path: `src/core/req-reset-command.ts`
+- @brief Implements the specialized `req-reset` slash-command workflow.
+- @details Performs non-agentic prompt-orchestration recovery by preserving the current execution-session transcript when available, restoring the original session-backed `base-path`, force-removing every generated sibling worktree and matching branch, and returning deterministic cleanup facts to the extension command handler. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem removal.
 
-### fn `function extractCommentLines(commentElement: SourceElement): string[]` (L261-275)
-- @brief Extracts cleaned individual lines from one comment element.
-- @details Removes language comment markers while preserving line granularity for structured comment payloads. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Comment element.
-- @return {string[]} Cleaned comment lines.
+## Imports
+```
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+import { ReqError } from "./errors.js";
+import {
+import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
+```
 
-### fn `function buildCommentMaps(elements: SourceElement[]): [Record<number, SourceElement[]>, SourceElement[], string]` (L283-333)
-- @brief Associates nearby comment blocks with definitions and standalone comment groups.
-- @details Reuses the repository comment-attachment heuristic that binds comments within three lines of a definition while preserving early file-description text. Runtime is O(n log n). No side effects occur.
-- @param[in] elements {SourceElement[]} Analyzed source elements.
-- @return {[Record<number, SourceElement[]>, SourceElement[], string]} Attached-comment map, standalone comments, and compact file description.
+## Definitions
 
-### fn `function resolveSymbolName(element: SourceElement): string` (L341-343)
-- @brief Resolves one stable symbol name from an analyzed element.
-- @details Prefers explicit analyzer name metadata, then falls back to the derived signature or the first source line so every symbol retains a direct-access identifier. Runtime is O(1). No side effects occur.
-- @param[in] element {SourceElement} Source element.
-- @return {string} Stable symbol name.
+### iface `export interface ReqResetCommandPlan` (L34-40)
+- @brief Describes the prepared execution facts for one `req-reset` run.
+- @details Stores the validated project base, resolved git root, sibling-worktree parent directory, generated-name matcher, and optional persisted prompt execution plan used for transcript preservation plus base-path restoration. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function resolveParentElement(definitions: SourceElement[], child: SourceElement): SourceElement | undefined` (L352-361)
-- @brief Resolves the direct parent element for one child symbol.
-- @details Matches by parent name plus inclusive line containment and chooses the deepest enclosing definition. Runtime is O(n) in definition count. No side effects occur.
-- @param[in] definitions {SourceElement[]} Sorted definition elements.
-- @param[in] child {SourceElement} Candidate child symbol.
-- @return {SourceElement | undefined} Matched parent definition when available.
+### iface `export interface ReqResetCommandExecutionResult` (L46-53)
+- @brief Describes the outcome of one `req-reset` execution attempt.
+- @details Captures the last valid session-bound context, transcript-preservation and base-path-restoration facts, removed generated worktree and branch names, and one aggregated failure string when any recovery step fails. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function buildCommentEntry(commentElement: SourceElement): ReferenceCommentEntry` (L369-376)
-- @brief Builds one structured comment record from a comment element.
-- @details Preserves numeric line-range metadata plus normalized text and per-line fragments. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Source comment element.
-- @return {ReferenceCommentEntry} Structured comment record.
+- type `type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1];` (L59)
+- @brief Describes the session-bound context surface reused during `req-reset` recovery.
+- @details Reuses the session-switching contract already accepted by `restorePromptCommandExecution(...)` so the dedicated reset command can restore the original session without depending on concrete pi runtime classes. The alias is compile-time only and introduces no runtime cost.
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L68-73)
+- @brief Executes one synchronous subprocess and captures UTF-8 output.
+- @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
+- @param[in] command {string[]} Executable plus argument vector.
+- @param[in] cwd {string} Working directory for the subprocess.
+- @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### fn `function buildRepositoryTree(canonicalPaths: string[]): ReferenceRepositoryTreeNode` (L384-443)
-- @brief Builds one structured repository tree from canonical file paths.
-- @details Materializes a nested directory map and converts it into recursively ordered JSON nodes without decorative ASCII formatting. Runtime is O(n log n) in path count. No side effects occur.
-- @param[in] canonicalPaths {string[]} Canonical file paths.
-- @return {ReferenceRepositoryTreeNode} Structured repository tree rooted at `.`.
+### fn `function escapeReqResetRegExpLiteral(text: string): string` (L81-83)
+- @brief Escapes one literal string for safe JavaScript regular-expression reuse.
+- @details Prefixes every regular-expression metacharacter with `\\` so generated worktree-name patterns can embed persisted prefixes and repository basenames without introducing unintended matcher semantics. Runtime is O(n) in string length. No external state is mutated.
+- @param[in] text {string} Literal text fragment.
+- @return {string} Regular-expression-safe literal fragment.
 
-### fn `const ensureDirectory = (parent: ReferenceRepositoryTreeNode, nodeName: string, relativePath: string): ReferenceRepositoryTreeNode =>` (L393-407)
+### fn `function buildReqResetWorktreeNamePattern(gitRoot: string, config: UseReqConfig): RegExp` (L93-100)
+- @brief Builds the generated-worktree name matcher used by `req-reset` cleanup.
+- @details Reuses the configured worktree prefix plus repository basename, accepts any sanitized branch token between those fixed segments and the final execution identifier, and constrains the timestamp suffix to the documented `YYYYMMDDHHMMSS` shape. Runtime is O(p) in combined prefix and project-name length. No external state is mutated.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {RegExp} Matcher for generated prompt-command worktree and branch names.
+- @satisfies REQ-309, REQ-310, REQ-311
 
-### fn `const finalizeNode = (node: ReferenceRepositoryTreeNode): ReferenceRepositoryTreeNode =>` (L429-440)
+### fn `function listReqResetRegisteredWorktreeRoots(gitRoot: string): string[]` (L109-118)
+- @brief Lists every registered git worktree root for one repository.
+- @details Executes `git worktree list --porcelain`, extracts each `worktree <path>` record, resolves every listed path to an absolute form, and returns the ordered list used by generated-worktree cleanup. Runtime is dominated by one git subprocess plus O(n) parsing in listed worktree count. Side effects include subprocess creation.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @return {string[]} Absolute registered worktree-root paths.
+- @throws {ReqError} Throws when git worktree enumeration fails.
+
+### fn `function listReqResetSiblingWorktreeRoots(` (L128-146)
+- @brief Lists sibling directories whose names match the generated-worktree contract.
+- @details Reads the repository parent directory, keeps only direct child directories whose basenames match the supplied generated-name pattern, and resolves each candidate to an absolute path so `req-reset` can remove unregistered leftover directories as well as registered git worktrees. Runtime is dominated by directory enumeration plus O(n) matcher cost. Side effects are limited to filesystem reads.
+- @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Absolute sibling directory paths whose basenames match the generated-name contract.
+- @throws {ReqError} Throws when directory enumeration fails.
+
+### fn `function listReqResetMatchingWorktreeRoots(` (L157-172)
+- @brief Lists every generated sibling worktree candidate targeted by `req-reset`.
+- @details Unions registered git-worktree roots with matching sibling directories so cleanup covers both registered worktrees and unregistered leftover directories, then sorts the canonical absolute paths for deterministic deletion order. Runtime is dominated by git worktree enumeration plus sibling-directory scanning. Side effects are limited to subprocess creation and filesystem reads.
+- @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Sorted absolute worktree-root paths targeted for deletion.
+- @throws {ReqError} Throws when git worktree or sibling-directory enumeration fails.
 
-### fn `function analyzeReferenceFile(` (L456-621)
-- @brief Builds one analyzed file entry for the references payload.
-- @details Parses the file with `SourceAnalyzer`, extracts structured imports and symbols, attaches structured Doxygen fields, and preserves standalone comment evidence. Runtime is O(S log S) in file size and symbol count. Side effects are limited to filesystem reads and optional stderr logging.
-- @param[in] analyzer {SourceAnalyzer} Shared source analyzer instance.
-- @param[in] inputPath {string} Caller-provided input path.
-- @param[in] absolutePath {string} Absolute file path.
-- @param[in] requestIndex {number} Zero-based request index.
-- @param[in] baseDir {string} Base directory used for canonical paths.
-- @param[in] verbose {boolean} When `true`, emit per-file progress diagnostics to stderr.
-- @return {ReferenceToolFileEntry} Structured file entry.
-
-### fn `export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOptions): ReferenceToolPayload` (L630-730)
-- @brief Builds the full agent-oriented references payload.
-- @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits structured repository data without echoing request metadata already known to the caller. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
-- @param[in] options {BuildReferenceToolPayloadOptions} Payload-construction options.
-- @return {ReferenceToolPayload} Structured references payload ordered as summary, repository, and files.
-- @satisfies REQ-011, REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
-
-### fn `export function buildReferenceToolExecutionStderr(payload: ReferenceToolPayload): string` (L738-752)
-- @brief Builds deterministic stderr diagnostics from a references payload.
-- @details Serializes skipped-input and analysis-error entries into stable newline-delimited diagnostics while leaving fully analyzed payloads silent. Runtime is O(n) in file-entry count. No side effects occur.
-- @param[in] payload {ReferenceToolPayload} Structured references payload.
-- @return {string} Newline-delimited diagnostics.
+### fn `function listReqResetMatchingBranchNames(` (L182-195)
+- @brief Lists every matching generated branch targeted by `req-reset`.
+- @details Executes `git branch --list --format=%(refname:short)`, filters the local branch inventory through the generated-name matcher, and returns a sorted list so later forced branch deletion remains deterministic. Runtime is dominated by one git subprocess plus O(n) parsing in listed branch count. Side effects include subprocess creation.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Sorted local branch names targeted for deletion.
+- @throws {ReqError} Throws when local branch enumeration fails.
+
+### fn `export function prepareReqResetCommandExecution(` (L207-230)
+- @brief Prepares the specialized `req-reset` execution plan.
+- @details Resolves the active project base into a runtime git root, derives the sibling-worktree parent directory and generated-name matcher from the same prefix plus repository-basename contract used by prompt-command worktree generation, and keeps only worktree-backed persisted prompt execution plans for transcript-preserving base-path restoration. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @param[in] promptRequest {PromptCommandExecutionPlan | undefined} Pending or active prompt execution plan when available.
+- @return {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+- @throws {ReqError} Throws when the repository root cannot be resolved.
+- @satisfies REQ-306, REQ-309, REQ-310, REQ-311
+
+### fn `export async function executeReqResetCommandExecution(` (L240-323)
+- @brief Executes the specialized `req-reset` recovery and cleanup workflow.
+- @details Preserves the execution-session transcript into the original session file when a worktree-backed prompt execution plan is still available, restores the original session-backed `base-path` through the shared prompt-command restoration helper, force-removes every matching sibling worktree directory, force-removes every remaining matching local branch, and aggregates any failure diagnostics without rolling back successful cleanup steps. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem reads.
+- @param[in] plan {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+- @param[in] ctx {ReqResetCommandContext | undefined} Optional session-bound command context.
+- @return {Promise<ReqResetCommandExecutionResult>} Recovery and cleanup outcome facts.
+- @satisfies REQ-305, REQ-307, REQ-308, REQ-309, REQ-310, REQ-313
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`ReferenceToolScope`|type||27||
-|`ReferenceFileStatus`|type||33||
-|`ReferenceLineRange`|iface||39-43|export interface ReferenceLineRange|
-|`ReferenceImportEntry`|iface||49-52|export interface ReferenceImportEntry extends ReferenceLi...|
-|`ReferenceCommentEntry`|iface||58-61|export interface ReferenceCommentEntry extends ReferenceL...|
-|`ReferenceExitPointEntry`|iface||67-70|export interface ReferenceExitPointEntry|
-|`ReferenceSymbolEntry`|iface||76-96|export interface ReferenceSymbolEntry extends ReferenceLi...|
-|`ReferenceToolFileEntry`|iface||102-115|export interface ReferenceToolFileEntry extends Reference...|
-|`ReferenceToolRequestSection`|iface||121-130|export interface ReferenceToolRequestSection|
-|`ReferenceToolSummarySection`|iface||136-147|export interface ReferenceToolSummarySection|
-|`ReferenceRepositoryTreeNode`|iface||153-159|export interface ReferenceRepositoryTreeNode|
-|`ReferenceToolRepositorySection`|iface||165-169|export interface ReferenceToolRepositorySection|
-|`ReferenceToolPayload`|iface||175-179|export interface ReferenceToolPayload|
-|`BuildReferenceToolPayloadOptions`|iface||185-192|export interface BuildReferenceToolPayloadOptions|
-|`canonicalizeReferencePath`|fn||201-209|function canonicalizeReferencePath(targetPath: string, ba...|
-|`buildLineRange`|fn||218-224|function buildLineRange(startLineNumber: number, endLineN...|
-|`extractCommentText`|fn||233-253|function extractCommentText(commentElement: SourceElement...|
-|`extractCommentLines`|fn||261-275|function extractCommentLines(commentElement: SourceElemen...|
-|`buildCommentMaps`|fn||283-333|function buildCommentMaps(elements: SourceElement[]): [Re...|
-|`resolveSymbolName`|fn||341-343|function resolveSymbolName(element: SourceElement): string|
-|`resolveParentElement`|fn||352-361|function resolveParentElement(definitions: SourceElement[...|
-|`buildCommentEntry`|fn||369-376|function buildCommentEntry(commentElement: SourceElement)...|
-|`buildRepositoryTree`|fn||384-443|function buildRepositoryTree(canonicalPaths: string[]): R...|
-|`ensureDirectory`|fn||393-407|const ensureDirectory = (parent: ReferenceRepositoryTreeN...|
-|`finalizeNode`|fn||429-440|const finalizeNode = (node: ReferenceRepositoryTreeNode):...|
-|`analyzeReferenceFile`|fn||456-621|function analyzeReferenceFile(|
-|`buildReferenceToolPayload`|fn||630-730|export function buildReferenceToolPayload(options: BuildR...|
-|`buildReferenceToolExecutionStderr`|fn||738-752|export function buildReferenceToolExecutionStderr(payload...|
+|`ReqResetCommandPlan`|iface||34-40|export interface ReqResetCommandPlan|
+|`ReqResetCommandExecutionResult`|iface||46-53|export interface ReqResetCommandExecutionResult|
+|`ReqResetCommandContext`|type||59||
+|`runCapture`|fn||68-73|function runCapture(command: string[], cwd: string): Retu...|
+|`escapeReqResetRegExpLiteral`|fn||81-83|function escapeReqResetRegExpLiteral(text: string): string|
+|`buildReqResetWorktreeNamePattern`|fn||93-100|function buildReqResetWorktreeNamePattern(gitRoot: string...|
+|`listReqResetRegisteredWorktreeRoots`|fn||109-118|function listReqResetRegisteredWorktreeRoots(gitRoot: str...|
+|`listReqResetSiblingWorktreeRoots`|fn||128-146|function listReqResetSiblingWorktreeRoots(|
+|`listReqResetMatchingWorktreeRoots`|fn||157-172|function listReqResetMatchingWorktreeRoots(|
+|`listReqResetMatchingBranchNames`|fn||182-195|function listReqResetMatchingBranchNames(|
+|`prepareReqResetCommandExecution`|fn||207-230|export function prepareReqResetCommandExecution(|
+|`executeReqResetCommandExecution`|fn||240-323|export async function executeReqResetCommandExecution(|
 
 
 ---
 
-# resources.ts | TypeScript | 119L | 7 symbols | 3 imports | 8 comments
+# resources.ts | TypeScript | 102L | 7 symbols | 3 imports | 8 comments
 > Path: `src/core/resources.ts`
 - @brief Resolves installation-owned bundled resource locations.
 - @details Encapsulates installation-path discovery, bundled-resource validation, prompt enumeration, prompt loading, and bundled instruction loading directly from the installed extension payload. Runtime is proportional to directory-entry enumeration and resource file size. Side effects are limited to filesystem reads.
@@ -3437,20 +3497,20 @@ import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
 - @return {string} Raw prompt markdown content.
 - @throws {Error} Propagates `fs.readFileSync` errors when the prompt file is missing or unreadable.
 
-### fn `export function readBundledPromptDescription(promptName: string): string` (L73-95)
-- @brief Extracts the YAML-front-matter `description` field from one bundled prompt.
-- @details Parses only the leading front-matter block, resolves the first scalar `description` entry, strips one matching pair of wrapping quotes, and unescapes quoted apostrophe or quote characters used in prompt metadata. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
+### fn `export function readBundledPromptDescription(promptName: string): string` (L73-78)
+- @brief Extracts the first Markdown level-one heading from one bundled prompt.
+- @details Removes one optional leading YAML front-matter block, scans the remaining markdown body for the first line that begins with `# `, and returns the heading payload without the marker or surrounding whitespace. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
 - @param[in] promptName {string} Prompt identifier without the `.md` suffix.
-- @return {string} Normalized prompt description or the empty string when the front matter does not declare one.
+- @return {string} First `# ` heading payload, or the empty string when no level-one heading exists.
 
-### fn `export function readBundledInstruction(instructionName: string): string` (L104-106)
+### fn `export function readBundledInstruction(instructionName: string): string` (L87-89)
 - @brief Reads one bundled markdown instruction by logical instruction name.
 - @details Resolves the instruction file under the installation-owned `resources/instructions` directory, validates resource accessibility, and loads it as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
 - @param[in] instructionName {string} Instruction identifier without the `.md` suffix.
 - @return {string} Raw instruction markdown content.
 - @throws {Error} Propagates `fs.readFileSync` errors when the instruction file is missing or unreadable.
 
-### fn `export function listBundledPromptNames(): string[]` (L113-119)
+### fn `export function listBundledPromptNames(): string[]` (L96-102)
 - @brief Lists bundled prompt identifiers available in the installed extension payload.
 - @details Scans the installation-owned prompt directory, keeps visible markdown files only, strips the `.md` suffix, and returns a lexicographically sorted list. Time complexity is O(n log n). Side effects are limited to filesystem reads.
 - @return {string[]} Sorted prompt names without file extensions.
@@ -3462,9 +3522,9 @@ import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
 |`ensureBundledResourcesAccessible`|fn||26-38|export function ensureBundledResourcesAccessible(): string|
 |`readBundledMarkdownResource`|fn||48-54|function readBundledMarkdownResource(|
 |`readBundledPrompt`|fn||63-65|export function readBundledPrompt(promptName: string): st...|
-|`readBundledPromptDescription`|fn||73-95|export function readBundledPromptDescription(promptName: ...|
-|`readBundledInstruction`|fn||104-106|export function readBundledInstruction(instructionName: s...|
-|`listBundledPromptNames`|fn||113-119|export function listBundledPromptNames(): string[]|
+|`readBundledPromptDescription`|fn||73-78|export function readBundledPromptDescription(promptName: ...|
+|`readBundledInstruction`|fn||87-89|export function readBundledInstruction(instructionName: s...|
+|`listBundledPromptNames`|fn||96-102|export function listBundledPromptNames(): string[]|
 
 
 ---
@@ -3532,7 +3592,7 @@ import { isSameOrAncestorPath } from "./path-context.js";
 
 ---
 
-# settings-menu.ts | TypeScript | 264L | 12 symbols | 2 imports | 13 comments
+# settings-menu.ts | TypeScript | 321L | 15 symbols | 2 imports | 15 comments
 > Path: `src/core/settings-menu.ts`
 - @brief Renders pi-usereq configuration menus with the shared pi.dev settings style.
 - @details Wraps `SettingsList` in one extension-command helper that exposes right-aligned current values, built-in circular scrolling, bottom-line descriptions, and a deterministic bridge for offline test harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
@@ -3545,37 +3605,35 @@ import { Container, SettingsList, Text, type Component, type SettingItem, type S
 
 ## Definitions
 
-### iface `export interface PiUsereqSettingsMenuChoice` (L14-22)
+### iface `export interface PiUsereqSettingsMenuChoice` (L14-23)
 - @brief Describes one selectable pi-usereq settings-menu choice.
-- @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, right-column current value, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
+- @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, right-column current value, optional inline-cycle values, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface PiUsereqSettingsMenuBridge` (L28-34)
+### iface `export interface PiUsereqSettingsMenuBridge` (L29-35)
 - @brief Describes the offline bridge exposed by shared settings-menu components.
 - @details Lets deterministic harnesses and unit tests drive the same settings-menu choices by label without simulating raw terminal key streams. The interface is runtime-facing but carries no side effects by itself.
 
-### iface `export interface PiUsereqSettingsMenuOptions` (L42-44)
+### iface `export interface PiUsereqSettingsMenuOptions` (L41-45)
 - @brief Describes optional behavior overrides for one settings-menu render.
-- @details Carries the caller-selected initial focus row so menu re-renders can
-preserve selection after an in-place toggle or value edit. The interface is
-compile-time only and introduces no runtime cost.
+- @details Carries the caller-selected initial focus row, the optional dynamic choice supplier used to rebuild dependent rows after inline toggles, and the optional inline-change callback used to persist `SettingsList` value cycles without closing the menu. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface PiUsereqSettingsMenuComponent extends Component` : Component (L50-52)
+### iface `export interface PiUsereqSettingsMenuComponent extends Component` : Component (L51-53)
 - @brief Represents a custom menu component augmented with the offline bridge.
 - @details Extends the generic TUI `Component` contract with one optional bridge field consumed only by deterministic test and debug harness adapters. The interface is compile-time only and introduces no runtime cost.
 
-- type `type PiUsereqSettingsThemeColor = Extract<ThemeColor, "accent" | "muted" | "dim">;` (L60)
+- type `type PiUsereqSettingsThemeColor = Extract<ThemeColor, "accent" | "muted" | "dim">;` (L61)
 - @brief Enumerates the CLI-supported theme tokens consumed by settings menus.
 - @details Narrows callback-local theme calls to the documented settings-list
 semantics used by the pi CLI. Compile-time only and introduces no runtime
 cost.
-### iface `interface PiUsereqSettingsTheme` (L69-72)
+### iface `interface PiUsereqSettingsTheme` (L70-73)
 - @brief Describes the callback-local theme surface required by settings menus.
 - @details Captures the subset of the custom-UI theme API needed to rebuild
 title and fallback settings-list styling when the shared global theme is not
 available in tests or offline replay. Compile-time only and introduces no
 runtime cost.
 
-### fn `function buildFallbackPiUsereqSettingsListTheme(` (L84-96)
+### fn `function buildFallbackPiUsereqSettingsListTheme(` (L85-97)
 - @brief Builds the fallback settings-list theme matching CLI settings semantics.
 - @details Mirrors the shared CLI settings theme token mapping for labels,
 values, descriptions, cursor, and hints while avoiding the global theme
@@ -3585,7 +3643,7 @@ mutated.
 - @return {SettingsListTheme} Fallback settings-list theme.
 - @satisfies REQ-151, REQ-156
 
-### fn `function buildPiUsereqSettingsListTheme(` (L109-123)
+### fn `function buildPiUsereqSettingsListTheme(` (L110-124)
 - @brief Resolves the settings-list theme used by pi-usereq configuration menus.
 - @details Prefers the shared CLI `getSettingsListTheme()` API so extension
 menus inherit active-theme behavior from pi itself, then falls back to an
@@ -3596,7 +3654,7 @@ external state is mutated.
 - @return {SettingsListTheme} Settings-list theme used by pi-usereq menus.
 - @satisfies REQ-151, REQ-156
 
-### fn `function formatPiUsereqSettingsMenuTitle(` (L135-140)
+### fn `function formatPiUsereqSettingsMenuTitle(` (L136-141)
 - @brief Formats the settings-menu title with active-theme semantics.
 - @details Applies the callback-local `accent` token and bold styling on every
 rebuild so custom-menu titles stay synchronized with live theme changes.
@@ -3606,46 +3664,64 @@ Runtime is O(n) in title length. No external state is mutated.
 - @return {string} Styled title text.
 - @satisfies REQ-151, REQ-156
 
-### fn `function createImmediateSelectionComponent(choiceId: string, done: (value?: string) => void): Component` (L149-161)
+### fn `function createImmediateSelectionComponent(choiceId: string, done: (value?: string) => void): Component` (L150-162)
 - @brief Closes a settings menu immediately with one selected action identifier.
 - @details Provides the submenu callback used by `SettingsList` so pressing Enter on any menu row resolves the outer custom UI promise with the row identifier. Runtime is O(1). Side effects are limited to one custom-UI completion callback.
 - @param[in] choiceId {string} Stable choice identifier to emit.
 - @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
 - @return {Component} Immediate-completion submenu component.
 
-### fn `function buildSettingItems(` (L171-189)
+### fn `function buildSettingItems(` (L172-193)
 - @brief Builds `SettingsList` items from one menu-choice vector.
-- @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier only for enabled rows. Runtime is O(n) in choice count. No external state is mutated.
+- @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, inline-cycle values, and descriptions into `SettingItem` records. Non-disabled rows with `values` cycle inline on `Enter` or `Space`, while other non-disabled rows resolve the outer custom UI through the immediate submenu bridge. Runtime is O(n) in choice count. No external state is mutated.
 - @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
 - @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
 - @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
 - @return {SettingItem[]} `SettingsList` item vector.
 
-### fn `export async function showPiUsereqSettingsMenu(` (L201-205)
+### fn `function setSettingsListSelectedIndex(` (L202-207)
+- @brief Writes one best-effort selected row index into a `SettingsList` instance.
+- @details Uses reflective access so pi-usereq can preserve focus across menu re-renders without depending on the private field at compile time. Runtime is O(1). Side effect: mutates the underlying `SettingsList` selection state when the field exists.
+- @param[in] selectedIndex {number} Zero-based row index to restore.
+- @param[in,out] settingsList {SettingsList} Mutable settings-list instance.
+- @return {void} No return value.
+
+### fn `function getSettingsListSelectedIndex(` (L215-220)
+- @brief Reads the current selected row index from a `SettingsList` instance.
+- @details Uses reflective access so pi-usereq can report the current focused row through the offline bridge without referencing the private field in the static type system. Runtime is O(1). No external state is mutated.
+- @param[in] settingsList {SettingsList} Settings-list instance.
+- @return {number | undefined} Zero-based selected row index when available.
+
+### fn `export async function showPiUsereqSettingsMenu(` (L232-236)
 - @brief Renders one shared pi-usereq settings menu and resolves the selected action.
-- @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, and optional disabled rows. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+- @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, optional disabled rows, and inline toggle cycles that do not close the menu. When callers provide `getChoices(...)`, dependent rows are rebuilt after inline changes while preserving focus on the changed row. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering and caller-owned inline-change callbacks.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in] title {string} Menu title displayed in the heading and offline bridge.
 - @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
-- @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override.
+- @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override plus inline-change behavior.
 - @return {Promise<string | undefined>} Selected choice identifier or `undefined` when cancelled.
 - @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156, REQ-192
 
+### fn `const rebuildMenu = (selectedChoiceId?: string): void =>` (L272-279)
+
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiUsereqSettingsMenuChoice`|iface||14-22|export interface PiUsereqSettingsMenuChoice|
-|`PiUsereqSettingsMenuBridge`|iface||28-34|export interface PiUsereqSettingsMenuBridge|
-|`PiUsereqSettingsMenuOptions`|iface||42-44|export interface PiUsereqSettingsMenuOptions|
-|`PiUsereqSettingsMenuComponent`|iface||50-52|export interface PiUsereqSettingsMenuComponent extends Co...|
-|`PiUsereqSettingsThemeColor`|type||60||
-|`PiUsereqSettingsTheme`|iface||69-72|interface PiUsereqSettingsTheme|
-|`buildFallbackPiUsereqSettingsListTheme`|fn||84-96|function buildFallbackPiUsereqSettingsListTheme(|
-|`buildPiUsereqSettingsListTheme`|fn||109-123|function buildPiUsereqSettingsListTheme(|
-|`formatPiUsereqSettingsMenuTitle`|fn||135-140|function formatPiUsereqSettingsMenuTitle(|
-|`createImmediateSelectionComponent`|fn||149-161|function createImmediateSelectionComponent(choiceId: stri...|
-|`buildSettingItems`|fn||171-189|function buildSettingItems(|
-|`showPiUsereqSettingsMenu`|fn||201-205|export async function showPiUsereqSettingsMenu(|
+|`PiUsereqSettingsMenuChoice`|iface||14-23|export interface PiUsereqSettingsMenuChoice|
+|`PiUsereqSettingsMenuBridge`|iface||29-35|export interface PiUsereqSettingsMenuBridge|
+|`PiUsereqSettingsMenuOptions`|iface||41-45|export interface PiUsereqSettingsMenuOptions|
+|`PiUsereqSettingsMenuComponent`|iface||51-53|export interface PiUsereqSettingsMenuComponent extends Co...|
+|`PiUsereqSettingsThemeColor`|type||61||
+|`PiUsereqSettingsTheme`|iface||70-73|interface PiUsereqSettingsTheme|
+|`buildFallbackPiUsereqSettingsListTheme`|fn||85-97|function buildFallbackPiUsereqSettingsListTheme(|
+|`buildPiUsereqSettingsListTheme`|fn||110-124|function buildPiUsereqSettingsListTheme(|
+|`formatPiUsereqSettingsMenuTitle`|fn||136-141|function formatPiUsereqSettingsMenuTitle(|
+|`createImmediateSelectionComponent`|fn||150-162|function createImmediateSelectionComponent(choiceId: stri...|
+|`buildSettingItems`|fn||172-193|function buildSettingItems(|
+|`setSettingsListSelectedIndex`|fn||202-207|function setSettingsListSelectedIndex(|
+|`getSettingsListSelectedIndex`|fn||215-220|function getSettingsListSelectedIndex(|
+|`showPiUsereqSettingsMenu`|fn||232-236|export async function showPiUsereqSettingsMenu(|
+|`rebuildMenu`|fn||272-279|const rebuildMenu = (selectedChoiceId?: string): void =>|
 
 
 ---
@@ -4155,7 +4231,7 @@ import { ReqError } from "./errors.js";
 
 ---
 
-# tool-runner.ts | TypeScript | 438L | 21 symbols | 11 imports | 23 comments
+# tool-runner.ts | TypeScript | 458L | 22 symbols | 11 imports | 24 comments
 > Path: `src/core/tool-runner.ts`
 - @brief Implements the executable back-end for pi-usereq CLI analysis and static-check commands.
 - @details Centralizes project discovery, git-backed source-file collection, documentation token generation, compression, construct lookup, and static-check dispatch. Runtime depends on the selected command and may include filesystem reads, config writes, and process spawning.
@@ -4257,9 +4333,9 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Tool result containing the formatted summary and warnings.
 - @throws {ReqError} Throws when no valid files are provided.
 
-### fn `export function runFilesReferences(files: string[], cwd = process.cwd(), verbose = false): ToolResult` (L250-256)
-- @brief Generates the monolithic references markdown for explicit files.
-- @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
+### fn `export function runFilesSummarize(files: string[], cwd = process.cwd(), verbose = false): ToolResult` (L250-256)
+- @brief Generates the monolithic summary markdown for explicit files.
+- @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible summary markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] files {string[]} Explicit file paths.
 - @param[in] cwd {string} Base directory used for relative output paths. Defaults to `process.cwd()`.
 - @param[in] verbose {boolean} When `true`, emit per-file progress diagnostics to stderr.
@@ -4284,9 +4360,9 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing construct markdown.
 - @throws {ReqError} Throws when required arguments are missing.
 
-### fn `export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L298-309)
-- @brief Generates the monolithic references markdown for configured source directories.
-- @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible references document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
+### fn `export function runSummarize(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L298-309)
+- @brief Generates the monolithic summary markdown for configured source directories.
+- @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible summary document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
 - @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
 - @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr.
@@ -4294,7 +4370,17 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @throws {ReqError} Throws when no source files are found or no file can be analyzed.
 - @satisfies REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
 
-### fn `export function runCompress(projectBase: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L321-326)
+### fn `export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L321-329)
+- @brief Writes configured project references markdown to the canonical docs file.
+- @details Reuses `runSummarize(...)` to generate the same file-structure-plus-summary markdown, resolves `<docs-dir>/REFERENCES.md` from the effective project configuration, overwrites the target file, and returns the status-only stdout `success`. Runtime is O(F log F + S) plus one file write. Side effects include filesystem writes.
+- @param[in] projectBase {string} Candidate project root.
+- @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
+- @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr during summary generation.
+- @return {ToolResult} Successful tool result containing the status-only stdout payload.
+- @throws {ReqError} Throws when source discovery, summary generation, or file writing fails.
+- @satisfies REQ-293
+
+### fn `export function runCompress(projectBase: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L341-346)
 - @brief Compresses all source files from configured source directories.
 - @details Resolves the project base, collects source files, and delegates to `compressFiles`. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
@@ -4304,7 +4390,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing compressed output.
 - @throws {ReqError} Throws when no source files are found.
 
-### fn `export function runSearch(projectBase: string, tagFilter: string, pattern: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L340-349)
+### fn `export function runSearch(projectBase: string, tagFilter: string, pattern: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L360-369)
 - @brief Searches named constructs across configured project source files.
 - @details Resolves the project base, collects source files, delegates to `searchConstructsInFiles`, and converts thrown search errors into structured `ReqError` failures. Runtime is O(F + S + M). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
@@ -4316,7 +4402,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing construct markdown.
 - @throws {ReqError} Throws when no source files are found or the search fails.
 
-### fn `export function runTokens(projectBase: string, config?: UseReqConfig): ToolResult` (L359-368)
+### fn `export function runTokens(projectBase: string, config?: UseReqConfig): ToolResult` (L379-388)
 - @brief Counts tokens for canonical documentation files.
 - @details Loads the configured docs directory, selects `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md` when present, and delegates to `runFilesTokens`. Runtime is O(F + S). Side effects are limited to filesystem reads.
 - @param[in] projectBase {string} Candidate project root.
@@ -4324,7 +4410,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Tool result containing documentation token metrics.
 - @throws {ReqError} Throws when no canonical docs files exist.
 
-### fn `export function runFilesStaticCheck(files: string[], projectBase: string, config?: UseReqConfig): ToolResult` (L378-414)
+### fn `export function runFilesStaticCheck(files: string[], projectBase: string, config?: UseReqConfig): ToolResult` (L398-434)
 - @brief Runs configured static checks for explicit files.
 - @details Loads the effective static-check config, resolves the active checker list per file-extension language through the per-language enable flag, captures checker stdout for each dispatched entry, and aggregates stderr warnings for invalid paths. Runtime is O(F * C) plus external checker cost. Side effects include filesystem reads, stdout interception, and process spawning.
 - @param[in] files {string[]} Explicit file paths.
@@ -4332,7 +4418,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
 - @return {ToolResult} Aggregated static-check result.
 
-### fn `export function runProjectStaticCheck(projectBase: string, config?: UseReqConfig): ToolResult` (L424-437)
+### fn `export function runProjectStaticCheck(projectBase: string, config?: UseReqConfig): ToolResult` (L444-457)
 - @brief Runs configured static checks for project source and test directories.
 - @details Collects source and test files, excludes fixture roots, and delegates to `runFilesStaticCheck`. Runtime is O(F * C) plus external checker cost. Side effects include filesystem reads, stdout interception, and process spawning.
 - @param[in] projectBase {string} Candidate project root.
@@ -4355,15 +4441,16 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 |`resolveProjectSrcDirs`|fn||196-204|export function resolveProjectSrcDirs(projectBase: string...|
 |`loadAndRepairConfig`|fn||213-218|export function loadAndRepairConfig(projectBase: string):...|
 |`runFilesTokens`|fn||227-239|export function runFilesTokens(files: string[]): ToolResult|
-|`runFilesReferences`|fn||250-256|export function runFilesReferences(files: string[], cwd =...|
+|`runFilesSummarize`|fn||250-256|export function runFilesSummarize(files: string[], cwd = ...|
 |`runFilesCompress`|fn||267-269|export function runFilesCompress(files: string[], cwd = p...|
 |`runFilesSearch`|fn||280-286|export function runFilesSearch(argsList: string[], enable...|
-|`runReferences`|fn||298-309|export function runReferences(projectBase: string, config...|
-|`runCompress`|fn||321-326|export function runCompress(projectBase: string, config?:...|
-|`runSearch`|fn||340-349|export function runSearch(projectBase: string, tagFilter:...|
-|`runTokens`|fn||359-368|export function runTokens(projectBase: string, config?: U...|
-|`runFilesStaticCheck`|fn||378-414|export function runFilesStaticCheck(files: string[], proj...|
-|`runProjectStaticCheck`|fn||424-437|export function runProjectStaticCheck(projectBase: string...|
+|`runSummarize`|fn||298-309|export function runSummarize(projectBase: string, config?...|
+|`runReferences`|fn||321-329|export function runReferences(projectBase: string, config...|
+|`runCompress`|fn||341-346|export function runCompress(projectBase: string, config?:...|
+|`runSearch`|fn||360-369|export function runSearch(projectBase: string, tagFilter:...|
+|`runTokens`|fn||379-388|export function runTokens(projectBase: string, config?: U...|
+|`runFilesStaticCheck`|fn||398-434|export function runFilesStaticCheck(files: string[], proj...|
+|`runProjectStaticCheck`|fn||444-457|export function runProjectStaticCheck(projectBase: string...|
 
 
 ---
@@ -4450,7 +4537,7 @@ import path from "node:path";
 
 ---
 
-# index.ts | TypeScript | 3765L | 87 symbols | 25 imports | 93 comments
+# index.ts | TypeScript | 4203L | 93 symbols | 27 imports | 99 comments
 > Path: `src/index.ts`
 - @brief Registers the pi-usereq extension commands, tools, and configuration UI.
 - @details Bridges the standalone tool-runner layer into the pi extension API by registering prompt commands, agent tools, and interactive configuration menus. Runtime at module load is O(1); later behavior depends on the selected command or tool. Side effects include extension registration, UI updates, filesystem reads/writes, and delegated tool execution.
@@ -4472,6 +4559,8 @@ import {
 import { renderPrompt } from "./core/prompts.js";
 import {
 import {
+import {
+import {
 import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import {
@@ -4486,45 +4575,45 @@ import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
 
 ## Definitions
 
-### iface `interface PiShortcutRegistrar` (L161-169)
+### iface `interface PiShortcutRegistrar` (L177-185)
 - @brief Describes the optional shortcut-registration surface used by pi-usereq.
 - @details Narrows the runtime API to the documented `registerShortcut(...)`
 method so the extension can remain compatible with offline harnesses that do
 not implement shortcut capture. Compile-time only and introduces no runtime
 cost.
 
-### fn `function getProjectBase(cwd: string): string` (L177-186)
+### fn `function getProjectBase(cwd: string): string` (L193-202)
 - @brief Resolves the effective project base from a working directory.
 - @details Normalizes the provided cwd into an absolute path without consulting configuration. Time complexity is O(1). No I/O side effects occur.
 - @param[in] cwd {string} Current working directory.
 - @return {string} Absolute project base path.
 
-### fn `function getProcessCwdSafe(): string` (L193-202)
+### fn `function getProcessCwdSafe(): string` (L209-218)
 - @brief Resolves a safe process working directory for extension-load paths.
 - @details Returns `process.cwd()` when available and falls back to absolute `PWD`, `HOME`, or `/` when the current shell directory has been deleted. Runtime is O(1). No external state is mutated.
 - @return {string} Absolute fallback-safe process working directory.
 
-### fn `function resolveLiveBootstrapCwd(cwd: string): string` (L210-222)
+### fn `function resolveLiveBootstrapCwd(cwd: string): string` (L226-238)
 - @brief Resolves the live working directory used for bootstrap-sensitive flows.
 - @details Prefers the supplied cwd when it still exists. Otherwise reuses the tracked runtime context path when it remains live, then the tracked runtime base path, and finally a process-safe cwd so deleted worktree paths retained by stale contexts cannot poison later prompt preflight or lifecycle bootstrap. Runtime is O(1) plus bounded filesystem probes. No external state is mutated.
 - @param[in] cwd {string} Candidate context cwd.
 - @return {string} Existing absolute cwd used for bootstrap work.
 
-### fn `function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void` (L231-240)
+### fn `function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void` (L247-256)
 - @brief Best-effort synchronizes one context `cwd` mirror with bootstrap reality.
 - @details Applies the resolved live cwd to the supplied context when writable and ignores stale or read-only mirrors so command bootstrap can continue using authoritative filesystem probes. Runtime is O(1). Side effects are limited to optional `ctx.cwd` mutation.
 - @param[in] cwd {string} Resolved live cwd.
 - @param[in,out] ctx {{ cwd?: string }} Mutable context-like object.
 - @return {void} No return value.
 
-### fn `function loadProjectConfig(cwd: string): UseReqConfig` (L249-252)
+### fn `function loadProjectConfig(cwd: string): UseReqConfig` (L265-268)
 - @brief Loads project configuration for the extension runtime.
 - @details Resolves the project base, loads persisted config, and normalizes configured directory paths without reading or persisting runtime-derived `base-path` or `git-path` metadata. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
 - @param[in] cwd {string} Current working directory.
 - @return {UseReqConfig} Effective project configuration.
 - @satisfies REQ-030, REQ-145, REQ-146
 
-### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L262-265)
+### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L278-281)
 - @brief Persists project configuration from the extension runtime.
 - @details Resolves the project base, normalizes configured directory paths into project-relative form, and delegates persistence to `saveConfig` without serializing runtime-derived path metadata. Runtime is O(n) in config size. Side effects include config-file writes.
 - @param[in] cwd {string} Current working directory.
@@ -4532,32 +4621,32 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-146
 
-### fn `function formatProjectConfigPathForMenu(cwd: string): string` (L274-278)
+### fn `function formatProjectConfigPathForMenu(cwd: string): string` (L290-294)
 - @brief Formats the current project config path for top-level menu display.
 - @details Resolves `<base-path>/.pi-usereq.json` from the cwd-derived project base, reuses the shared runtime-path formatter, and rewrites a leading POSIX `$HOME` token to `~` for the `Show configuration` row only. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] cwd {string} Current working directory.
 - @return {string} `~`-relative or absolute config path display value.
 - @satisfies REQ-162
 
-### fn `function buildTerminalSettingsMenuChoices(options:` (L287-298)
+### fn `function buildTerminalSettingsMenuChoices(options:` (L303-314)
 - @brief Builds the standardized terminal rows appended to every configuration menu.
 - @details Returns the canonical value-less `Reset defaults` row so all configuration menus and descendant selector menus share the same terminal ordering contract without rendering `Save and close`. Runtime is O(1). No external state is mutated.
 - @param[in] options {{ resetDefaultsDescription: string }} Menu-specific terminal-row metadata.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered terminal menu rows.
 - @satisfies REQ-193
 
-### iface `interface ResetConfirmationChange` (L304-308)
+### iface `interface ResetConfirmationChange` (L320-324)
 - @brief Describes one pending reset value change shown in confirmation menus.
 - @details Stores the row label plus its previous and next values so reset-confirmation submenus can expose machine-readable and human-verifiable change previews. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function formatResetConfirmationValue(previousValue: string, nextValue: string): string` (L317-319)
+### fn `function formatResetConfirmationValue(previousValue: string, nextValue: string): string` (L333-335)
 - @brief Formats one reset-confirmation value pair for menu display.
 - @details Serializes the previous and next values into a deterministic `previous -> next` preview string used by confirmation submenus. Runtime is O(n) in combined value length. No external state is mutated.
 - @param[in] previousValue {string} Current persisted value.
 - @param[in] nextValue {string} Candidate default value.
 - @return {string} Rendered preview string.
 
-### fn `function buildResetConfirmationChoices(` (L329-368)
+### fn `function buildResetConfirmationChoices(` (L345-384)
 - @brief Builds the shared settings-menu choices for one reset-confirmation submenu.
 - @details Renders each pending changed value as a disabled preview row, appends explicit approve and abort actions, and falls back to one disabled no-op row when no values would change. Runtime is O(n) in changed-value count. No external state is mutated.
 - @param[in] changes {ResetConfirmationChange[]} Changed-value preview rows.
@@ -4565,7 +4654,7 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {PiUsereqSettingsMenuChoice[]} Reset-confirmation submenu choices.
 
-### fn `async function confirmResetChanges(` (L380-393)
+### fn `async function confirmResetChanges(` (L396-409)
 - @brief Opens one explicit reset-confirmation submenu.
 - @details Uses the shared settings-menu renderer to show every changed value before reset application and returns `true` only when the user selects the explicit approval action. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4575,7 +4664,7 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {Promise<boolean>} `true` when the reset is explicitly approved.
 
-### fn `function writePersistedProjectConfigToEditor(` (L404-411)
+### fn `function writePersistedProjectConfigToEditor(` (L420-427)
 - @brief Writes the already-persisted project configuration file text into the editor.
 - @details Reads the current `.pi-usereq.json` file content from disk after the caller has saved any pending configuration changes and forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4584,51 +4673,51 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-031
 
-### fn `function buildSearchToolSupportedTagGuidelines(): string[]` (L472-476)
+### fn `function buildSearchToolSupportedTagGuidelines(): string[]` (L488-492)
 - @brief Builds the supported-tag guidance lines embedded in search-tool registrations.
 - @details Emits one deterministic line per supported language containing its canonical registration label and sorted tag list so downstream agents can specialize requests without invoking the tool first. Runtime is O(l * t log t). No side effects occur.
 - @return {string[]} Supported-tag guidance lines.
 
-### fn `function buildSearchToolSchemaDescription(scope: FindToolScope): string` (L484-489)
+### fn `function buildSearchToolSchemaDescription(scope: FindToolScope): string` (L500-505)
 - @brief Builds the schema description for one search-tool registration.
 - @details Specializes the explicit-file and configured-directory input contracts while documenting the monolithic markdown output channel and minimal execution details shape. Runtime is O(1). No side effects occur.
 - @param[in] scope {FindToolScope} Search-tool scope.
 - @return {string} Parameter-schema description.
 
-### fn `function buildSearchToolPromptGuidelines(scope: FindToolScope): string[]` (L497-510)
+### fn `function buildSearchToolPromptGuidelines(scope: FindToolScope): string[]` (L513-526)
 - @brief Builds the prompt-guideline set for one search-tool registration.
 - @details Encodes scope selection, monolithic markdown output semantics, regex semantics, line-number behavior, tag-filter rules, and the full language-to-tag matrix as stable agent-oriented strings. Runtime is O(l * t log t). No side effects occur.
 - @param[in] scope {FindToolScope} Search-tool scope.
 - @return {string[]} Prompt-guideline strings.
 
-- type `type MonolithicToolRenderResult = {` (L516)
+- type `type MonolithicToolRenderResult = {` (L532)
 - @brief Describes the monolithic tool-result surface consumed by tool-row renderers.
 - @details Narrows execute-result data to the primary text content block plus the minimal `details.execution` metadata returned by monolithic tool wrappers. The alias is compile-time only and introduces no runtime cost.
-### fn `function getMonolithicToolText(result: MonolithicToolRenderResult): string` (L533-536)
+### fn `function getMonolithicToolText(result: MonolithicToolRenderResult): string` (L549-552)
 - @brief Extracts the primary monolithic text block from one tool result.
 - @details Returns the first text content block when present and falls back to an empty string when the tool emitted no LLM-facing content. Runtime is O(1). No external state is mutated.
 - @param[in] result {MonolithicToolRenderResult} Tool result wrapper.
 - @return {string} Primary monolithic content text.
 
-### fn `function getMonolithicToolErrorText(result: MonolithicToolRenderResult): string | undefined` (L544-554)
+### fn `function getMonolithicToolErrorText(result: MonolithicToolRenderResult): string | undefined` (L560-570)
 - @brief Reads the first residual execution error string from one monolithic tool result.
 - @details Prefers the first `stderr_lines` entry when present and otherwise falls back to the first line of `stderr`. Runtime is O(1) plus first-line split cost. No external state is mutated.
 - @param[in] result {MonolithicToolRenderResult} Tool result wrapper.
 - @return {string | undefined} First residual execution error string.
 
-### fn `function formatCompactToolArgumentValue(value: unknown): string | undefined` (L562-601)
+### fn `function formatCompactToolArgumentValue(value: unknown): string | undefined` (L578-617)
 - @brief Formats one scalar or structural tool argument for compact render summaries.
 - @details Truncates long strings, compresses arrays into short previews, and renders plain object arguments as key indexes so collapsed tool rows stay compact while still exposing the essential invocation shape. Runtime is O(n) in preview size. No external state is mutated.
 - @param[in] value {unknown} Candidate tool argument value.
 - @return {string | undefined} Compact preview string or `undefined` when the value carries no useful summary.
 
-### fn `function buildCompactToolInvocationText(args: Record<string, unknown> | undefined): string` (L609-620)
+### fn `function buildCompactToolInvocationText(args: Record<string, unknown> | undefined): string` (L625-636)
 - @brief Builds the compact invocation summary appended to collapsed tool rows.
 - @details Renders only caller-supplied parameters that have stable, non-empty compact previews and joins them in insertion order so agents can infer how the tool was used without expanding the full result. Runtime is O(n) in argument count and preview size. No external state is mutated.
 - @param[in] args {Record<string, unknown> | undefined} Current tool call arguments.
 - @return {string} Compact invocation summary prefixed with one separating space, or the empty string when no useful preview exists.
 
-### fn `function summarizeStructuredToolResult(` (L630-645)
+### fn `function summarizeStructuredToolResult(` (L646-661)
 - @brief Builds the compact default text for one monolithic tool result row.
 - @details Prefers the tool name, compact invocation preview, and success marker for collapsed rows, and falls back to residual execution diagnostics when the tool failed before completing successfully. Runtime is O(n) in compact argument-preview size. No external state is mutated.
 - @param[in] toolName {string} Registered tool name.
@@ -4636,20 +4725,27 @@ cost.
 - @param[in] args {Record<string, unknown> | undefined} Current tool call arguments.
 - @return {string} Compact single-line summary.
 
-### fn `function buildStructuredToolRenderResult(toolName: string)` (L654-673)
+### fn `function buildStructuredToolRenderResult(toolName: string)` (L670-689)
 - @brief Builds a custom `renderResult` implementation for one monolithic tool.
 - @details Reuses a mutable `Text` component when possible, keeps the default collapsed row compact with essential invocation parameters plus result status, and reveals the full monolithic content only when the tool row is expanded. Runtime is O(n) in expanded content length and compact argument-preview size. No external state is mutated.
 - @param[in] toolName {string} Registered tool name.
 - @return {(result: MonolithicToolRenderResult, options: { expanded?: boolean; isPartial?: boolean }, _theme: unknown, context: { args?: Record<string, unknown>; lastComponent?: unknown }) => Text} Custom result renderer.
 - @satisfies REQ-210
 
-### fn `function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L681-687)
+### fn `function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L697-703)
 - @brief Executes one CLI-style runner for a monolithic agent tool.
 - @details Reuses the standalone tool-runner contract, normalizes thrown failures into `ToolResult`, and wraps the selected stdout or stderr text into the monolithic content channel. Runtime is dominated by the delegated runner. Side effects depend on the selected tool.
 - @param[in] operation {() => ToolResult} Runner callback.
 - @return {ReturnType<typeof buildMonolithicToolExecuteResult>} Monolithic tool execute result.
 
-### fn `function deliverPromptCommand(` (L698-716)
+### fn `function executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L712-741)
+- @brief Executes one CLI-style runner for a status-only agent tool.
+- @details Reuses the standalone tool-runner contract, preserves `content[0].text` as the status-only `success` or `error: <diagnostic>` payload, and strips success-path `stdout_lines` so `details.execution` stays limited to the numeric code plus optional residual stderr diagnostics. Runtime is dominated by the delegated runner. Side effects depend on the selected tool.
+- @param[in] operation {() => ToolResult} Runner callback.
+- @return {ReturnType<typeof buildMonolithicToolExecuteResult>} Status-only tool execute result.
+- @satisfies REQ-294, REQ-295, REQ-296
+
+### fn `function deliverPromptCommand(` (L752-770)
 - @brief Starts delivery of one rendered prompt into the current active session.
 - @details Prefers the replacement-session `sendUserMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Returns the underlying delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `pi.sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose replacement-session helpers. Runtime is O(n) in prompt length. Side effects are limited to user-message delivery.
 - @param[in] pi {ExtensionAPI} Handler-scoped extension API instance retained as the fallback dispatcher.
@@ -4658,7 +4754,7 @@ cost.
 - @return {Promise<void>} Promise representing eventual prompt-delivery completion.
 - @satisfies REQ-004, REQ-067, REQ-068, REQ-227, REQ-281
 
-### fn `function shouldIgnoreLatePromptDeliveryFailure(` (L727-743)
+### fn `function shouldIgnoreLatePromptDeliveryFailure(` (L781-797)
 - @brief Detects prompt-delivery failures that can be ignored after prompt ownership has moved past the command handler.
 - @details Matches the documented stale-extension-context runtime error once prompt ownership has already moved beyond command-side preflight. The helper treats the failure as ignorable when the persisted prompt runtime state shows the same execution session as the active prompt run or when the persisted workflow state has already advanced beyond `checking|running`, because rethrowing at that point would incorrectly re-enter command-side abort logic after the prompt was already accepted. Runtime is O(n) in error-message length plus path length. No external state is mutated.
 - @param[in] error {unknown} Candidate prompt-delivery failure.
@@ -4667,7 +4763,7 @@ cost.
 - @return {boolean} `true` when the failure is a late stale-context delivery rejection that MUST be ignored.
 - @satisfies REQ-208, REQ-280, REQ-281, REQ-282
 
-### fn `function logPromptWorkflowStateChange(` (L756-775)
+### fn `function logPromptWorkflowStateChange(` (L810-829)
 - @brief Appends one workflow-state debug entry for a bundled prompt when selected.
 - @details Reuses the shared debug logger so `req-*` command handlers and prompt-end orchestration can record deterministic workflow transitions without duplicating JSON payload shaping. Runtime is O(n) in serialized payload size only when logging is enabled and O(1) otherwise. Side effects include debug-log file writes for matching enabled prompts.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -4678,7 +4774,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247
 
-### fn `function logPromptWorkflowEvent(` (L791-811)
+### fn `function logPromptWorkflowEvent(` (L845-865)
 - @brief Appends one dedicated prompt workflow debug entry when selected.
 - @details Reuses the shared workflow-event logger so prompt activation, restoration, closure, and session-shutdown paths can emit higher-granularity orchestration diagnostics without duplicating JSON payload shaping. Runtime is O(n) in serialized payload size only when logging is enabled and O(1) otherwise. Side effects include debug-log file writes for matching enabled prompts.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -4692,7 +4788,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247, REQ-277
 
-### fn `function transitionPromptWorkflowState(` (L824-837)
+### fn `function transitionPromptWorkflowState(` (L878-891)
 - @brief Transitions one prompt workflow state and logs the transition immediately after the state update.
 - @details Captures the previous workflow state, applies the new state through the shared status helper, and appends the gated `workflow_state` debug entry only after the transition has completed. Runtime is O(1). Side effects include status mutation, status-bar rendering, and optional debug-log writes.
 - @param[in] ctx {ExtensionContext | ExtensionCommandContext} Active extension context.
@@ -4703,20 +4799,20 @@ cost.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `function resolvePromptCommandDescription(` (L845-849)
+### fn `function resolvePromptCommandDescription(` (L899-903)
 - @brief Resolves the runtime slash-command description for one bundled prompt.
-- @details Reads the bundled prompt front matter, extracts its normalized `description` field, and falls back to the historical generated label when the prompt metadata omits a description. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
+- @details Reads the bundled prompt markdown, extracts the first `# ` heading payload, and falls back to the historical generated label when the prompt omits a level-one heading. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
 - @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName} Bundled prompt name.
 - @return {string} Runtime command description.
 
-### fn `function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusController): string` (L858-862)
+### fn `function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusController): string` (L912-916)
 - @brief Resolves the original project base used for debug-log file writes.
 - @details Prefers the active or pending prompt execution plan so tool-result logging during worktree-backed prompt runs persists into the original repository path instead of transient worktree directories. Runtime is O(1). No external state is mutated.
 - @param[in] cwd {string} Current extension working directory.
 - @param[in] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {string} Absolute original project base path for debug logging.
 
-### fn `function notifyContextSafely(` (L873-890)
+### fn `function notifyContextSafely(` (L927-944)
 - @brief Delivers one best-effort UI notification without failing on stale replacement contexts.
 - @details Attempts to use the supplied extension context for UI notification delivery and suppresses the documented stale-extension-context runtime error raised after session replacement, because prompt-orchestration closure can outlive the context that initiated the switch. Runtime is O(n) in message length. Side effects are limited to user notification delivery when the context is still active.
 - @param[in] ctx {ExtensionContext | ExtensionCommandContext | undefined} Candidate UI context.
@@ -4725,20 +4821,30 @@ cost.
 - @return {boolean} `true` when the notification was delivered and `false` when the context was already stale.
 - @satisfies REQ-280
 
-### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L899-907)
+### fn `function rejectNonIdleReqCommand(` (L956-976)
+- @brief Rejects one non-`idle` req-command invocation and records the workflow error state.
+- @details Builds a deterministic busy-state diagnostic from the current workflow state, transitions the shared workflow state to `error`, preserves any pending or active prompt execution metadata for later closure handling, emits an error notification, and throws `ReqError`. Bundled prompt commands reuse `transitionPromptWorkflowState(...)` when cached configuration is available so prompt debug logging captures the actual state transition; specialized non-prompt commands fall back to direct status mutation. Runtime is O(1). Side effects include workflow-state mutation, status-bar rendering, optional debug-log writes, and user notification delivery.
+- @param[in] ctx {ExtensionContext | ExtensionCommandContext} Active extension context.
+- @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName | undefined} Optional bundled prompt name used for prompt debug logging.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {never} This helper always throws a deterministic `ReqError`.
+- @throws {ReqError} Always throws because non-`idle` req commands are rejected.
+- @satisfies REQ-224
+
+### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L985-993)
 - @brief Returns the configurable active-tool inventory visible to the extension.
 - @details Filters runtime tools against the canonical configurable-tool set, keeps only builtin-backed embedded tools, and orders the result by the documented custom/files/embedded/default-disabled grouping. Runtime is O(t log t). No external state is mutated.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @return {ToolInfo[]} Sorted configurable tool descriptors.
 - @satisfies REQ-007, REQ-063, REQ-231, REQ-232
 
-### fn `function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[]` (L915-919)
+### fn `function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[]` (L1001-1005)
 - @brief Normalizes and returns the configured enabled active tools.
 - @details Reuses repository normalization rules, updates the config object in place, and returns the normalized array. Runtime is O(n) in configured tool count. Side effect: mutates `config["enabled-tools"]`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {string[]} Normalized enabled tool names.
 
-### fn `function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): void` (L929-946)
+### fn `function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): void` (L1015-1032)
 - @brief Applies the configured active-tool enablement to the current session.
 - @details Preserves non-configurable active tools, removes every configurable tool from the active set, then re-adds only configured tools that exist in the current runtime inventory. Runtime is O(t). Side effects include `pi.setActiveTools(...)`.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4746,18 +4852,18 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-009, REQ-064
 
-### fn `async function handleExtensionStatusEvent(` (L959-1219)
+### fn `async function handleExtensionStatusEvent(` (L1045-1316)
 - @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
-- @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, merges and deletes the worktree only for matched successful completions, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+- @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the stash-assisted merge-and-delete finalization path for every matched successful worktree-backed completion even when a later busy-command rejection already moved workflow state to `error`, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
 - @param[in] event {unknown} Hook payload forwarded by pi.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {Promise<void>} Promise resolved when hook processing completes.
-- @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280
+- @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292
 
-### fn `function registerExtensionStatusHooks(` (L1235-1254)
+### fn `function registerExtensionStatusHooks(` (L1332-1351)
 - @brief Registers shared wrappers for every supported pi lifecycle hook.
 - @details Installs one generic wrapper per intercepted hook so every resource,
 session, agent, model, tool, bash, and input event is routed through the
@@ -4771,7 +4877,7 @@ registered hook count. Side effects include hook registration.
 - @return {void} No return value.
 - @satisfies DES-002, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117
 
-### fn `function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enabledTools: string[]): void` (L1264-1267)
+### fn `function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enabledTools: string[]): void` (L1361-1364)
 - @brief Replaces the configured active-tool selection and applies it immediately.
 - @details Normalizes the requested tool names, stores them in config, and synchronizes the active tool set with runtime registration state. Runtime is O(n + t). Side effect: mutates config and active tools.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4779,26 +4885,26 @@ registered hook count. Side effects include hook registration.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 
-### fn `function getDebugToolToggleNames(): PiUsereqStartupToolName[]` (L1275-1277)
+### fn `function getDebugToolToggleNames(): PiUsereqStartupToolName[]` (L1372-1374)
 - @brief Returns the canonical debug-tool toggle order.
 - @details Reuses the documented configurable-tool ordering so debug toggles list extension-owned tools before embedded tools and remain deterministic across sessions. Runtime is O(t log t). No external state is mutated.
 - @return {PiUsereqStartupToolName[]} Ordered debug-tool toggle names.
 - @satisfies REQ-242
 
-### fn `function resetDebugConfigToDefaults(config: UseReqConfig): void` (L1286-1294)
+### fn `function resetDebugConfigToDefaults(config: UseReqConfig): void` (L1383-1391)
 - @brief Restores the debug configuration subtree to its documented defaults.
 - @details Resets global debug enablement, log path, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 - @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277
 
-### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1302-1308)
+### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1399-1405)
 - @brief Formats the top-level Debug summary value.
 - @details Emits the current global debug mode plus compact selected-tool and selected-prompt counts for right-aligned menu display. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Compact debug summary string.
 
-### fn `function buildDebugMenuChoice(` (L1318-1331)
+### fn `function buildDebugMenuChoice(` (L1415-1428)
 - @brief Builds one debug-menu row with optional disabled styling.
 - @details Applies dim styling and disables selection whenever global debug is off for all rows except the global `Debug` toggle row. Runtime is O(1). No external state is mutated.
 - @param[in] choice {PiUsereqSettingsMenuChoice} Base debug-menu row.
@@ -4806,21 +4912,21 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice} Styled debug-menu row.
 - @satisfies REQ-241
 
-### fn `async function selectDebugLogOnStatus(` (L1340-1368)
+### fn `async function selectDebugLogOnStatus(` (L1437-1465)
 - @brief Opens the workflow-state filter selector used by the Debug submenu.
 - @details Exposes `any` plus each canonical workflow state through the shared settings-menu renderer and returns the selected normalized filter or `undefined` when the user cancels the submenu. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in] currentValue {DebugLogOnStatus} Current persisted workflow-state filter.
 - @return {Promise<DebugLogOnStatus | undefined>} Selected workflow-state filter or `undefined` when cancelled.
 
-### fn `function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1377-1448)
+### fn `function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1474-1550)
 - @brief Builds the shared settings-menu choices for debug logging configuration.
 - @details Serializes global debug controls plus workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered debug-menu choices.
 - @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277
 
-### fn `async function configureDebugMenu(` (L1458-1575)
+### fn `async function configureDebugMenu(` (L1560-1729)
 - @brief Runs the interactive Debug submenu.
 - @details Lets the user toggle global debug enablement, edit debug file and workflow filters, toggle dedicated workflow-event logging, mutate per-tool and per-prompt debug selectors, and restore subtree defaults while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4828,45 +4934,45 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<void>} Promise resolved when the submenu closes.
 - @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277
 
-- type `type PiNotifyBooleanConfigKey =` (L1581)
+- type `type PiNotifyBooleanConfigKey =` (L1735)
 - @brief Represents one persisted boolean notification-setting key.
 - @details Restricts menu toggles to the global enable flags and completed/interrupted/failed event toggles used by command-notify, sound, and Pushover configuration. Compile-time only and introduces no runtime cost.
-- type `type PiNotifyEventBooleanConfigKey = Exclude<` (L1598)
+- type `type PiNotifyEventBooleanConfigKey = Exclude<` (L1752)
 - @brief Represents one persisted boolean notification event-toggle key.
 - @details Restricts shared event-submenu mutation helpers to completed/interrupted/failed toggles and excludes global enable flags. Compile-time only and introduces no runtime cost.
-- type `type PiNotifyEventId = "completed" | "interrupted" | "failed";` (L1607)
+- type `type PiNotifyEventId = "completed" | "interrupted" | "failed";` (L1761)
 - @brief Represents one shared prompt-end event identifier used by notification menus.
 - @details Restricts event-submenu rendering to the canonical completed/interrupted/failed domain shared by command-notify, sound, and Pushover routing. Compile-time only and introduces no runtime cost.
-### iface `interface PiNotifyEventRowDefinition` (L1613-1617)
+### iface `interface PiNotifyEventRowDefinition` (L1767-1771)
 - @brief Describes one shared prompt-end event row rendered inside notification event submenus.
 - @details Binds one canonical event identifier to the human-readable label and terminal-outcome description reused across command-notify, sound, and Pushover event menus. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PiNotifyEventMenuDefinition` (L1623-1629)
+### iface `interface PiNotifyEventMenuDefinition` (L1777-1783)
 - @brief Describes one notification-system event submenu contract.
 - @details Binds the top-level launcher row, submenu title, toast prefix, and completed/interrupted/failed config keys for one notification transport. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean` (L1638-1641)
+### fn `function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean` (L1792-1795)
 - @brief Flips one persisted boolean notification setting.
 - @details Negates the selected configuration flag in place and returns the resulting boolean value so callers can emit deterministic UI feedback. Runtime is O(1). Side effect: mutates `config`.
 - @param[in] key {PiNotifyBooleanConfigKey} Boolean configuration key to toggle.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {boolean} Next enabled state.
 
-### fn `function resetPiNotifyConfigToDefaults(config: UseReqConfig): void` (L1650-1674)
+### fn `function resetPiNotifyConfigToDefaults(config: UseReqConfig): void` (L1804-1828)
 - @brief Restores notification-related settings to their documented defaults.
 - @details Copies the command-notify, sound, and Pushover configuration subtree from a fresh default config into the supplied mutable project config. Runtime is O(1). Side effect: mutates `config`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 - @satisfies REQ-174, REQ-178, REQ-184, REQ-195, REQ-196
 
-### fn `function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string` (L1683-1685)
+### fn `function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string` (L1837-1839)
 - @brief Formats one persisted Pushover priority for menu display.
 - @details Maps the canonical `0|1` priority domain to deterministic `Normal|High` labels reused by the Pushover configuration UI. Runtime is O(1). No external state is mutated.
 - @param[in] priority {PiNotifyPushoverPriority} Persisted Pushover priority.
 - @return {string} Menu-display label.
 - @satisfies REQ-172
 
-### fn `function formatPiNotifyEventMenuSummary(` (L1762-1770)
+### fn `function formatPiNotifyEventMenuSummary(` (L1923-1931)
 - @brief Formats the top-level summary value for one notification event submenu.
 - @details Counts enabled completed/interrupted/failed toggles for the selected transport and renders the result as `n/3 on` for right-aligned menu display. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -4874,7 +4980,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Compact enabled-toggle summary.
 - @satisfies REQ-198
 
-### fn `function buildPiNotifyEventLauncherChoice(` (L1780-1790)
+### fn `function buildPiNotifyEventLauncherChoice(` (L1941-1951)
 - @brief Builds the top-level launcher row for one notification event submenu.
 - @details Reuses the shared completed/interrupted/failed summary renderer so the `Notifications` menu can expose dedicated event editors for command-notify, sound, and Pushover in a uniform shape. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -4882,7 +4988,7 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice} Launcher row for the selected event submenu.
 - @satisfies REQ-181, REQ-183, REQ-165, REQ-198
 
-### fn `function buildPiNotifyEventMenuChoices(` (L1800-1815)
+### fn `function buildPiNotifyEventMenuChoices(` (L1961-1977)
 - @brief Builds the shared settings-menu choices for one notification event submenu.
 - @details Serializes completed/interrupted/failed rows with right-aligned `on|off` values, then appends a value-less `Reset defaults` row for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -4890,7 +4996,7 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered event-submenu choice vector.
 - @satisfies REQ-188, REQ-193, REQ-198
 
-### fn `function resetPiNotifyEventMenuToDefaults(` (L1825-1833)
+### fn `function resetPiNotifyEventMenuToDefaults(` (L1987-1995)
 - @brief Restores one notification event submenu to its documented defaults.
 - @details Copies only the completed/interrupted/failed toggles referenced by the supplied submenu contract from a fresh default config into the mutable project config. Runtime is O(1). Side effect: mutates `config`.
 - @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
@@ -4898,7 +5004,7 @@ registered hook count. Side effects include hook registration.
 - @return {void} No return value.
 - @satisfies REQ-174, REQ-178, REQ-184, REQ-195
 
-### fn `function resolvePiNotifyEventLabel(` (L1843-1850)
+### fn `function resolvePiNotifyEventLabel(` (L2005-2012)
 - @brief Resolves the human-readable event label for one event-toggle config key.
 - @details Matches the supplied config key against the submenu contract and returns the corresponding completed/interrupted/failed menu label for deterministic notification toasts. Runtime is O(1). No external state is mutated.
 - @param[in] key {PiNotifyEventBooleanConfigKey} Event-toggle configuration key.
@@ -4906,7 +5012,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Human-readable event label.
 - @satisfies REQ-188, REQ-198
 
-### fn `async function configurePiNotifyEventMenu(` (L1861-1921)
+### fn `async function configurePiNotifyEventMenu(` (L2023-2099)
 - @brief Runs one dedicated notification event submenu.
 - @details Reuses the shared settings-menu renderer to toggle completed/interrupted/failed delivery flags, preserve row focus, and apply submenu-scoped reset semantics for command-notify, sound, or Pushover events. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4915,14 +5021,14 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<void>} Promise resolved when the submenu closes.
 - @satisfies REQ-188, REQ-192, REQ-193, REQ-195, REQ-198
 
-### fn `function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1930-1979)
+### fn `function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2108-2158)
 - @brief Builds the direct Pushover rows rendered inside `Notifications`.
-- @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows, dims and disables the enable row until both credentials are populated, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
+- @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows, dims and disables the enable row until both credentials are populated, renders the locked value as `configure user/token keys first`, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered direct Pushover rows.
 - @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198, REQ-234, REQ-235
 
-### fn `async function selectPiNotifyPushoverPriority(` (L1989-2017)
+### fn `async function selectPiNotifyPushoverPriority(` (L2168-2196)
 - @brief Opens the shared settings-menu selector for Pushover priority.
 - @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the notification menus and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4930,58 +5036,82 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<PiNotifyPushoverPriority | "reset-defaults" | undefined>} Selected priority, reset action, or `undefined` when cancelled.
 - @satisfies REQ-172, REQ-192
 
-### fn `function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2026-2083)
+### fn `function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2205-2263)
 - @brief Builds the shared settings-menu choices for notification configuration.
-- @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface, including locked Pushover enablement and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. No external state is mutated.
+- @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface, including locked Pushover enablement, persisted boot-sound rows that stay decoupled from the active runtime sound level, and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered notification-menu choice vector.
-- @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198, REQ-234, REQ-235
+- @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198, REQ-234, REQ-235, REQ-289
 
-### fn `async function selectPiNotifySoundLevel(` (L2093-2133)
-- @brief Opens the shared settings-menu selector for the active sound level.
-- @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+### fn `async function selectPiNotifySoundLevel(` (L2273-2313)
+- @brief Opens the shared settings-menu selector for the persisted boot sound level.
+- @details Reuses the pi-usereq settings-menu renderer so boot-sound selection remains stylistically aligned with the notification menu, keeps the active runtime sound level unchanged, and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
-- @param[in] currentLevel {PiNotifySoundLevel} Currently selected sound level.
-- @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected sound level, reset action, or `undefined` when cancelled.
-- @satisfies REQ-131, REQ-179, REQ-192
+- @param[in] currentLevel {PiNotifySoundLevel} Persisted boot sound level.
+- @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected boot sound level, reset action, or `undefined` when cancelled.
+- @satisfies REQ-131, REQ-179, REQ-192, REQ-289
 
-### fn `async function configurePiNotifyMenu(` (L2143-2409)
+### fn `async function configurePiNotifyMenu(` (L2323-2609)
 - @brief Runs the interactive notification-configuration menu.
-- @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+- @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, persists boot-sound changes without altering the active runtime sound level, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {Promise<boolean>} `true` when the sound-toggle shortcut changed.
-- @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198, REQ-234, REQ-235
+- @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198, REQ-234, REQ-235, REQ-288, REQ-289
 
-### fn `function registerPiNotifyShortcut(` (L2424-2444)
+### fn `function registerPiNotifyShortcut(` (L2624-2647)
 - @brief Registers the configurable notification-sound shortcut when supported.
 - @details Loads the current project config, registers one raw pi shortcut when
-the runtime exposes `registerShortcut(...)`, cycles persisted sound state on
-invocation, saves the config, refreshes the status bar, and emits one info
-notification. Runtime is O(1) for registration plus config I/O per shortcut
-use. Side effects include shortcut registration, config writes, and status
-updates.
+the runtime exposes `registerShortcut(...)`, cycles only the active runtime
+sound level on invocation, leaves `.pi-usereq.json` unchanged, refreshes the
+status bar, and emits one info notification. Runtime is O(1) for registration
+plus one status update per shortcut use. Side effects include shortcut
+registration and status updates.
+- @param[in] pi {ExtensionAPI} Active extension API instance.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-134, REQ-180, REQ-286, REQ-287
+
+### fn `function resolveReqResetPromptRequest(` (L2655-2681)
+- @brief Resolves the prompt execution plan targeted by `req-reset` recovery.
+- @details Prefers the current in-memory active request, then the current in-memory pending request, then the process-scoped persisted prompt runtime state so the dedicated reset command can recover from same-host unclean prompt termination after session replacement. Runtime is O(1). No external state is mutated.
+- @param[in] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {PromptCommandExecutionPlan | undefined} Recoverable prompt execution plan when one remains available.
+
+### fn `const isWorktreeBacked = (request: PromptCommandExecutionPlan | undefined): request is PromptCommandExecutionPlan =>` (L2658-2665)
+
+### fn `function registerReqResetCommand(` (L2691-2745)
+- @brief Registers the specialized `req-reset` slash command.
+- @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, and user notifications.
+- @param[in] pi {ExtensionAPI} Active extension API instance.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313
+
+### fn `function registerReqReferencesCommand(` (L2755-2795)
+- @brief Registers the specialized `req-references` slash command.
+- @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, and user notifications.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
-- @satisfies REQ-131, REQ-134, REQ-180
+- @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303
 
-### fn `function registerPromptCommands(` (L2454-2572)
-- @brief Registers bundled prompt commands with the extension.
-- @details Creates one `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state, transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
+### fn `function registerPromptCommands(` (L2805-2921)
+- @brief Registers bundled prompt-backed commands with the extension.
+- @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 - @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281
 
-### fn `function registerAgentTools(pi: ExtensionAPI): void` (L2582-2881)
+### fn `function registerAgentTools(pi: ExtensionAPI): void` (L2931-3230)
 - @brief Registers pi-usereq agent tools exposed to the model.
 - @details Defines the tool schemas, prompt metadata, and execution handlers that bridge extension tool calls into tool-runner operations without registering duplicate custom slash commands for the same capabilities. Runtime is O(t) for registration; execution cost depends on the selected tool. Side effects include tool registration.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @return {void} No return value.
-- @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102
+- @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102, REQ-293, REQ-294, REQ-295, REQ-296, REQ-297
 
-### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2899-2924)
+### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3275-3300)
 - @brief Builds the shared settings-menu choices for startup-tool management.
 - @details Serializes startup-tool actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting the removed status-reference action. Runtime is O(t) in configurable-tool count. No external state is mutated.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4989,7 +5119,7 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered startup-tool menu choices.
 - @satisfies REQ-007, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
 
-### fn `function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2934-2947)
+### fn `function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3310-3324)
 - @brief Builds the shared settings-menu choices for per-tool startup toggles.
 - @details Exposes every configurable startup tool as one row whose right-side value reports the current enabled state, preserves the documented custom/files/embedded/default-disabled ordering, and appends a value-less subtree-local `Reset defaults` row. Runtime is O(t) in configurable-tool count. No external state is mutated.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4997,7 +5127,7 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered per-tool toggle choices.
 - @satisfies REQ-007, REQ-151, REQ-152, REQ-153, REQ-154, REQ-231, REQ-232
 
-### fn `async function configurePiUsereqToolsMenu(` (L2958-3053)
+### fn `async function configurePiUsereqToolsMenu(` (L3335-3452)
 - @brief Runs the interactive active-tool configuration menu.
 - @details Synchronizes runtime active tools with persisted config, renders startup-tool actions through the shared settings-menu UI, preserves the documented per-tool ordering, and updates configuration state in response to selections until the user exits. Runtime depends on user interaction count. Side effects include UI updates, active-tool changes, and config mutation.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -5006,58 +5136,58 @@ updates.
 - @return {Promise<void>} Promise resolved when the menu closes.
 - @satisfies REQ-007, REQ-063, REQ-064, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193, REQ-231, REQ-232
 
-### fn `function getStaticCheckLanguageConfigForMenu(` (L3062-3067)
+### fn `function getStaticCheckLanguageConfigForMenu(` (L3461-3466)
 - @brief Resolves one static-check language config for menu rendering.
 - @details Returns the configured per-language static-check object when present and otherwise synthesizes a disabled empty-language object so menu code can render all supported languages deterministically. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in] language {string} Canonical language name.
 - @return {StaticCheckLanguageConfig} Resolved per-language config object.
 
-### fn `function countConfiguredStaticCheckLanguages(config: UseReqConfig): number` (L3075-3077)
+### fn `function countConfiguredStaticCheckLanguages(config: UseReqConfig): number` (L3474-3476)
 - @brief Counts languages that currently expose at least one configured checker.
 - @details Treats configured-but-disabled languages as configured when their checker list is non-empty so removal actions remain deterministic. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {number} Number of languages with at least one configured checker.
 
-### fn `function countEnabledStaticCheckLanguages(config: UseReqConfig): number` (L3085-3087)
+### fn `function countEnabledStaticCheckLanguages(config: UseReqConfig): number` (L3484-3486)
 - @brief Counts languages whose static-check enable flag is on.
 - @details Counts only languages whose persisted per-language config explicitly sets `enabled=enable`, regardless of checker count. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {number} Number of enabled languages.
 
-### fn `function resetStaticCheckConfig(config: UseReqConfig): void` (L3096-3098)
+### fn `function resetStaticCheckConfig(config: UseReqConfig): void` (L3495-3497)
 - @brief Restores the documented static-check default configuration.
 - @details Replaces the mutable config subtree with a fresh clone of the documented per-language defaults so menu reset actions restore both enable flags and checker lists in one step. Runtime is O(l + c). Side effect: mutates `config`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 - @satisfies REQ-250, REQ-251, REQ-252
 
-### fn `function formatStaticCheckLanguagesSummary(config: UseReqConfig): string` (L3106-3108)
+### fn `function formatStaticCheckLanguagesSummary(config: UseReqConfig): string` (L3505-3507)
 - @brief Summarizes enabled and configured static-check languages.
 - @details Counts enabled languages and languages with at least one checker, then emits one compact summary string suitable for the top-level configuration menu. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Compact summary string.
 
-### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3117-3148)
+### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3516-3548)
 - @brief Builds the shared settings-menu choices for static-check management.
 - @details Serializes guided Command-oriented add and remove actions, renders one direct on/off toggle row for every supported language, and appends canonical terminal rows while omitting raw-spec and reference-only actions. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
 - @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248
 
-### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3156-3173)
+### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3556-3573)
 - @brief Builds the shared settings-menu choices for supported static-check languages.
 - @details Exposes every supported language as one row whose right-side value reports extensions, enablement, and configured checker count for guided Command configuration flows, then appends subtree-local terminal rows. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered language-choice vector.
 
-### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3181-3198)
+### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3581-3598)
 - @brief Builds the shared settings-menu choices for configured static-check languages.
 - @details Exposes only languages whose checker lists are non-empty so removal remains deterministic, then appends subtree-local terminal rows. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered configured-language vector.
 
-### fn `async function configureStaticCheckMenu(` (L3208-3341)
+### fn `async function configureStaticCheckMenu(` (L3608-3754)
 - @brief Runs the interactive static-check configuration menu.
 - @details Lets the user add Command entries by guided prompts, remove configured language entries, toggle direct per-language enable flags, and reset the subtree to documented defaults through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -5065,7 +5195,7 @@ updates.
 - @return {Promise<void>} Promise resolved when the menu closes.
 - @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253
 
-### fn `function buildPiUsereqMenuChoices(` (L3351-3440)
+### fn `function buildPiUsereqMenuChoices(` (L3764-3856)
 - @brief Builds the shared settings-menu choices for the top-level pi-usereq configuration UI.
 - @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and the display-only config path beside `show-config`. Runtime is O(s) in source-directory count. No external state is mutated.
 - @param[in] cwd {string} Current working directory.
@@ -5073,21 +5203,21 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
 - @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240
 
-### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3449-3467)
+### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3865-3883)
 - @brief Builds the shared settings-menu choices for source-directory management.
 - @details Exposes add and remove actions for `src-dir` entries through right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(s) in source-directory count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered source-directory management choices.
 - @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
 
-### fn `function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3476-3488)
+### fn `function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3892-3904)
 - @brief Builds the shared settings-menu choices for removing one source-directory entry.
 - @details Exposes every configured `src-dir` entry as one removable row and appends a value-less subtree-local `Reset defaults` row. Runtime is O(s) in source-directory count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered removable source-directory choices.
 - @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
 
-### fn `async function configurePiUsereq(` (L3499-3719)
+### fn `async function configurePiUsereq(` (L3915-4164)
 - @brief Runs the top-level pi-usereq configuration menu.
 - @details Loads project config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show configuration`, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -5096,9 +5226,9 @@ updates.
 - @return {Promise<void>} Promise resolved when configuration is saved and the menu closes.
 - @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243
 
-### fn `const persistConfigChange = () =>` (L3510-3515)
+### fn `const persistConfigChange = () =>` (L3926-3931)
 
-### fn `function registerConfigCommands(` (L3729-3739)
+### fn `function registerConfigCommands(` (L4174-4184)
 - @brief Registers configuration-management commands.
 - @details Adds the interactive `pi-usereq` configuration command only; the config-viewer action is now exposed exclusively inside that menu. Runtime is O(1) for registration. Side effects include command registration.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -5106,110 +5236,107 @@ updates.
 - @return {void} No return value.
 - @satisfies REQ-006, REQ-031
 
-### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L3757-3765)
+### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L4193-4203)
 - @brief Registers the complete pi-usereq extension.
-- @details Validates installation-owned bundled resources, registers prompt and
-configuration commands plus agent tools, registers the configurable
-notification-sound shortcut when the runtime supports shortcuts, and
-installs shared wrappers for all supported pi lifecycle hooks so status
-telemetry, context usage, prompt timing, cumulative runtime, prompt-specific
-Pushover metadata, tool-result debug logging, and prompt-orchestration debug
-effects remain synchronized with runtime events. Runtime is O(h) in hook
-count during registration. Side effects include filesystem reads,
-command/tool/shortcut registration, UI updates, active-tool changes,
-optional debug-log writes, and timer scheduling.
+- @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @return {void} No return value.
-- @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247
+- @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiShortcutRegistrar`|iface||161-169|interface PiShortcutRegistrar|
-|`getProjectBase`|fn||177-186|function getProjectBase(cwd: string): string|
-|`getProcessCwdSafe`|fn||193-202|function getProcessCwdSafe(): string|
-|`resolveLiveBootstrapCwd`|fn||210-222|function resolveLiveBootstrapCwd(cwd: string): string|
-|`syncContextCwdMirror`|fn||231-240|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
-|`loadProjectConfig`|fn||249-252|function loadProjectConfig(cwd: string): UseReqConfig|
-|`saveProjectConfig`|fn||262-265|function saveProjectConfig(cwd: string, config: UseReqCon...|
-|`formatProjectConfigPathForMenu`|fn||274-278|function formatProjectConfigPathForMenu(cwd: string): string|
-|`buildTerminalSettingsMenuChoices`|fn||287-298|function buildTerminalSettingsMenuChoices(options:|
-|`ResetConfirmationChange`|iface||304-308|interface ResetConfirmationChange|
-|`formatResetConfirmationValue`|fn||317-319|function formatResetConfirmationValue(previousValue: stri...|
-|`buildResetConfirmationChoices`|fn||329-368|function buildResetConfirmationChoices(|
-|`confirmResetChanges`|fn||380-393|async function confirmResetChanges(|
-|`writePersistedProjectConfigToEditor`|fn||404-411|function writePersistedProjectConfigToEditor(|
-|`buildSearchToolSupportedTagGuidelines`|fn||472-476|function buildSearchToolSupportedTagGuidelines(): string[]|
-|`buildSearchToolSchemaDescription`|fn||484-489|function buildSearchToolSchemaDescription(scope: FindTool...|
-|`buildSearchToolPromptGuidelines`|fn||497-510|function buildSearchToolPromptGuidelines(scope: FindToolS...|
-|`MonolithicToolRenderResult`|type||516||
-|`getMonolithicToolText`|fn||533-536|function getMonolithicToolText(result: MonolithicToolRend...|
-|`getMonolithicToolErrorText`|fn||544-554|function getMonolithicToolErrorText(result: MonolithicToo...|
-|`formatCompactToolArgumentValue`|fn||562-601|function formatCompactToolArgumentValue(value: unknown): ...|
-|`buildCompactToolInvocationText`|fn||609-620|function buildCompactToolInvocationText(args: Record<stri...|
-|`summarizeStructuredToolResult`|fn||630-645|function summarizeStructuredToolResult(|
-|`buildStructuredToolRenderResult`|fn||654-673|function buildStructuredToolRenderResult(toolName: string)|
-|`executeMonolithicTool`|fn||681-687|function executeMonolithicTool(operation: () => ToolResul...|
-|`deliverPromptCommand`|fn||698-716|function deliverPromptCommand(|
-|`shouldIgnoreLatePromptDeliveryFailure`|fn||727-743|function shouldIgnoreLatePromptDeliveryFailure(|
-|`logPromptWorkflowStateChange`|fn||756-775|function logPromptWorkflowStateChange(|
-|`logPromptWorkflowEvent`|fn||791-811|function logPromptWorkflowEvent(|
-|`transitionPromptWorkflowState`|fn||824-837|function transitionPromptWorkflowState(|
-|`resolvePromptCommandDescription`|fn||845-849|function resolvePromptCommandDescription(|
-|`resolveDebugProjectBase`|fn||858-862|function resolveDebugProjectBase(cwd: string, statusContr...|
-|`notifyContextSafely`|fn||873-890|function notifyContextSafely(|
-|`getPiUsereqStartupTools`|fn||899-907|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
-|`getConfiguredEnabledPiUsereqTools`|fn||915-919|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
-|`applyConfiguredPiUsereqTools`|fn||929-946|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
-|`handleExtensionStatusEvent`|fn||959-1219|async function handleExtensionStatusEvent(|
-|`registerExtensionStatusHooks`|fn||1235-1254|function registerExtensionStatusHooks(|
-|`setConfiguredPiUsereqTools`|fn||1264-1267|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
-|`getDebugToolToggleNames`|fn||1275-1277|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
-|`resetDebugConfigToDefaults`|fn||1286-1294|function resetDebugConfigToDefaults(config: UseReqConfig)...|
-|`formatDebugMenuSummary`|fn||1302-1308|function formatDebugMenuSummary(config: UseReqConfig): st...|
-|`buildDebugMenuChoice`|fn||1318-1331|function buildDebugMenuChoice(|
-|`selectDebugLogOnStatus`|fn||1340-1368|async function selectDebugLogOnStatus(|
-|`buildDebugMenuChoices`|fn||1377-1448|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
-|`configureDebugMenu`|fn||1458-1575|async function configureDebugMenu(|
-|`PiNotifyBooleanConfigKey`|type||1581||
-|`PiNotifyEventBooleanConfigKey`|type||1598||
-|`PiNotifyEventId`|type||1607||
-|`PiNotifyEventRowDefinition`|iface||1613-1617|interface PiNotifyEventRowDefinition|
-|`PiNotifyEventMenuDefinition`|iface||1623-1629|interface PiNotifyEventMenuDefinition|
-|`togglePiNotifyFlag`|fn||1638-1641|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
-|`resetPiNotifyConfigToDefaults`|fn||1650-1674|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
-|`formatPiNotifyPushoverPriority`|fn||1683-1685|function formatPiNotifyPushoverPriority(priority: PiNotif...|
-|`formatPiNotifyEventMenuSummary`|fn||1762-1770|function formatPiNotifyEventMenuSummary(|
-|`buildPiNotifyEventLauncherChoice`|fn||1780-1790|function buildPiNotifyEventLauncherChoice(|
-|`buildPiNotifyEventMenuChoices`|fn||1800-1815|function buildPiNotifyEventMenuChoices(|
-|`resetPiNotifyEventMenuToDefaults`|fn||1825-1833|function resetPiNotifyEventMenuToDefaults(|
-|`resolvePiNotifyEventLabel`|fn||1843-1850|function resolvePiNotifyEventLabel(|
-|`configurePiNotifyEventMenu`|fn||1861-1921|async function configurePiNotifyEventMenu(|
-|`buildPiNotifyPushoverRows`|fn||1930-1979|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
-|`selectPiNotifyPushoverPriority`|fn||1989-2017|async function selectPiNotifyPushoverPriority(|
-|`buildPiNotifyMenuChoices`|fn||2026-2083|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
-|`selectPiNotifySoundLevel`|fn||2093-2133|async function selectPiNotifySoundLevel(|
-|`configurePiNotifyMenu`|fn||2143-2409|async function configurePiNotifyMenu(|
-|`registerPiNotifyShortcut`|fn||2424-2444|function registerPiNotifyShortcut(|
-|`registerPromptCommands`|fn||2454-2572|function registerPromptCommands(|
-|`registerAgentTools`|fn||2582-2881|function registerAgentTools(pi: ExtensionAPI): void|
-|`buildPiUsereqToolsMenuChoices`|fn||2899-2924|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
-|`buildPiUsereqToolToggleChoices`|fn||2934-2947|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
-|`configurePiUsereqToolsMenu`|fn||2958-3053|async function configurePiUsereqToolsMenu(|
-|`getStaticCheckLanguageConfigForMenu`|fn||3062-3067|function getStaticCheckLanguageConfigForMenu(|
-|`countConfiguredStaticCheckLanguages`|fn||3075-3077|function countConfiguredStaticCheckLanguages(config: UseR...|
-|`countEnabledStaticCheckLanguages`|fn||3085-3087|function countEnabledStaticCheckLanguages(config: UseReqC...|
-|`resetStaticCheckConfig`|fn||3096-3098|function resetStaticCheckConfig(config: UseReqConfig): void|
-|`formatStaticCheckLanguagesSummary`|fn||3106-3108|function formatStaticCheckLanguagesSummary(config: UseReq...|
-|`buildStaticCheckMenuChoices`|fn||3117-3148|function buildStaticCheckMenuChoices(config: UseReqConfig...|
-|`buildSupportedStaticCheckLanguageChoices`|fn||3156-3173|function buildSupportedStaticCheckLanguageChoices(config:...|
-|`buildConfiguredStaticCheckLanguageChoices`|fn||3181-3198|function buildConfiguredStaticCheckLanguageChoices(config...|
-|`configureStaticCheckMenu`|fn||3208-3341|async function configureStaticCheckMenu(|
-|`buildPiUsereqMenuChoices`|fn||3351-3440|function buildPiUsereqMenuChoices(|
-|`buildSrcDirMenuChoices`|fn||3449-3467|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
-|`buildSrcDirRemovalChoices`|fn||3476-3488|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
-|`configurePiUsereq`|fn||3499-3719|async function configurePiUsereq(|
-|`persistConfigChange`|fn||3510-3515|const persistConfigChange = () =>|
-|`registerConfigCommands`|fn||3729-3739|function registerConfigCommands(|
-|`piUsereqExtension`|fn||3757-3765|export default function piUsereqExtension(pi: ExtensionAP...|
+|`PiShortcutRegistrar`|iface||177-185|interface PiShortcutRegistrar|
+|`getProjectBase`|fn||193-202|function getProjectBase(cwd: string): string|
+|`getProcessCwdSafe`|fn||209-218|function getProcessCwdSafe(): string|
+|`resolveLiveBootstrapCwd`|fn||226-238|function resolveLiveBootstrapCwd(cwd: string): string|
+|`syncContextCwdMirror`|fn||247-256|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
+|`loadProjectConfig`|fn||265-268|function loadProjectConfig(cwd: string): UseReqConfig|
+|`saveProjectConfig`|fn||278-281|function saveProjectConfig(cwd: string, config: UseReqCon...|
+|`formatProjectConfigPathForMenu`|fn||290-294|function formatProjectConfigPathForMenu(cwd: string): string|
+|`buildTerminalSettingsMenuChoices`|fn||303-314|function buildTerminalSettingsMenuChoices(options:|
+|`ResetConfirmationChange`|iface||320-324|interface ResetConfirmationChange|
+|`formatResetConfirmationValue`|fn||333-335|function formatResetConfirmationValue(previousValue: stri...|
+|`buildResetConfirmationChoices`|fn||345-384|function buildResetConfirmationChoices(|
+|`confirmResetChanges`|fn||396-409|async function confirmResetChanges(|
+|`writePersistedProjectConfigToEditor`|fn||420-427|function writePersistedProjectConfigToEditor(|
+|`buildSearchToolSupportedTagGuidelines`|fn||488-492|function buildSearchToolSupportedTagGuidelines(): string[]|
+|`buildSearchToolSchemaDescription`|fn||500-505|function buildSearchToolSchemaDescription(scope: FindTool...|
+|`buildSearchToolPromptGuidelines`|fn||513-526|function buildSearchToolPromptGuidelines(scope: FindToolS...|
+|`MonolithicToolRenderResult`|type||532||
+|`getMonolithicToolText`|fn||549-552|function getMonolithicToolText(result: MonolithicToolRend...|
+|`getMonolithicToolErrorText`|fn||560-570|function getMonolithicToolErrorText(result: MonolithicToo...|
+|`formatCompactToolArgumentValue`|fn||578-617|function formatCompactToolArgumentValue(value: unknown): ...|
+|`buildCompactToolInvocationText`|fn||625-636|function buildCompactToolInvocationText(args: Record<stri...|
+|`summarizeStructuredToolResult`|fn||646-661|function summarizeStructuredToolResult(|
+|`buildStructuredToolRenderResult`|fn||670-689|function buildStructuredToolRenderResult(toolName: string)|
+|`executeMonolithicTool`|fn||697-703|function executeMonolithicTool(operation: () => ToolResul...|
+|`executeStatusTool`|fn||712-741|function executeStatusTool(operation: () => ToolResult): ...|
+|`deliverPromptCommand`|fn||752-770|function deliverPromptCommand(|
+|`shouldIgnoreLatePromptDeliveryFailure`|fn||781-797|function shouldIgnoreLatePromptDeliveryFailure(|
+|`logPromptWorkflowStateChange`|fn||810-829|function logPromptWorkflowStateChange(|
+|`logPromptWorkflowEvent`|fn||845-865|function logPromptWorkflowEvent(|
+|`transitionPromptWorkflowState`|fn||878-891|function transitionPromptWorkflowState(|
+|`resolvePromptCommandDescription`|fn||899-903|function resolvePromptCommandDescription(|
+|`resolveDebugProjectBase`|fn||912-916|function resolveDebugProjectBase(cwd: string, statusContr...|
+|`notifyContextSafely`|fn||927-944|function notifyContextSafely(|
+|`rejectNonIdleReqCommand`|fn||956-976|function rejectNonIdleReqCommand(|
+|`getPiUsereqStartupTools`|fn||985-993|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
+|`getConfiguredEnabledPiUsereqTools`|fn||1001-1005|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
+|`applyConfiguredPiUsereqTools`|fn||1015-1032|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
+|`handleExtensionStatusEvent`|fn||1045-1316|async function handleExtensionStatusEvent(|
+|`registerExtensionStatusHooks`|fn||1332-1351|function registerExtensionStatusHooks(|
+|`setConfiguredPiUsereqTools`|fn||1361-1364|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
+|`getDebugToolToggleNames`|fn||1372-1374|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
+|`resetDebugConfigToDefaults`|fn||1383-1391|function resetDebugConfigToDefaults(config: UseReqConfig)...|
+|`formatDebugMenuSummary`|fn||1399-1405|function formatDebugMenuSummary(config: UseReqConfig): st...|
+|`buildDebugMenuChoice`|fn||1415-1428|function buildDebugMenuChoice(|
+|`selectDebugLogOnStatus`|fn||1437-1465|async function selectDebugLogOnStatus(|
+|`buildDebugMenuChoices`|fn||1474-1550|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
+|`configureDebugMenu`|fn||1560-1729|async function configureDebugMenu(|
+|`PiNotifyBooleanConfigKey`|type||1735||
+|`PiNotifyEventBooleanConfigKey`|type||1752||
+|`PiNotifyEventId`|type||1761||
+|`PiNotifyEventRowDefinition`|iface||1767-1771|interface PiNotifyEventRowDefinition|
+|`PiNotifyEventMenuDefinition`|iface||1777-1783|interface PiNotifyEventMenuDefinition|
+|`togglePiNotifyFlag`|fn||1792-1795|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
+|`resetPiNotifyConfigToDefaults`|fn||1804-1828|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
+|`formatPiNotifyPushoverPriority`|fn||1837-1839|function formatPiNotifyPushoverPriority(priority: PiNotif...|
+|`formatPiNotifyEventMenuSummary`|fn||1923-1931|function formatPiNotifyEventMenuSummary(|
+|`buildPiNotifyEventLauncherChoice`|fn||1941-1951|function buildPiNotifyEventLauncherChoice(|
+|`buildPiNotifyEventMenuChoices`|fn||1961-1977|function buildPiNotifyEventMenuChoices(|
+|`resetPiNotifyEventMenuToDefaults`|fn||1987-1995|function resetPiNotifyEventMenuToDefaults(|
+|`resolvePiNotifyEventLabel`|fn||2005-2012|function resolvePiNotifyEventLabel(|
+|`configurePiNotifyEventMenu`|fn||2023-2099|async function configurePiNotifyEventMenu(|
+|`buildPiNotifyPushoverRows`|fn||2108-2158|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
+|`selectPiNotifyPushoverPriority`|fn||2168-2196|async function selectPiNotifyPushoverPriority(|
+|`buildPiNotifyMenuChoices`|fn||2205-2263|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
+|`selectPiNotifySoundLevel`|fn||2273-2313|async function selectPiNotifySoundLevel(|
+|`configurePiNotifyMenu`|fn||2323-2609|async function configurePiNotifyMenu(|
+|`registerPiNotifyShortcut`|fn||2624-2647|function registerPiNotifyShortcut(|
+|`resolveReqResetPromptRequest`|fn||2655-2681|function resolveReqResetPromptRequest(|
+|`isWorktreeBacked`|fn||2658-2665|const isWorktreeBacked = (request: PromptCommandExecution...|
+|`registerReqResetCommand`|fn||2691-2745|function registerReqResetCommand(|
+|`registerReqReferencesCommand`|fn||2755-2795|function registerReqReferencesCommand(|
+|`registerPromptCommands`|fn||2805-2921|function registerPromptCommands(|
+|`registerAgentTools`|fn||2931-3230|function registerAgentTools(pi: ExtensionAPI): void|
+|`buildPiUsereqToolsMenuChoices`|fn||3275-3300|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
+|`buildPiUsereqToolToggleChoices`|fn||3310-3324|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
+|`configurePiUsereqToolsMenu`|fn||3335-3452|async function configurePiUsereqToolsMenu(|
+|`getStaticCheckLanguageConfigForMenu`|fn||3461-3466|function getStaticCheckLanguageConfigForMenu(|
+|`countConfiguredStaticCheckLanguages`|fn||3474-3476|function countConfiguredStaticCheckLanguages(config: UseR...|
+|`countEnabledStaticCheckLanguages`|fn||3484-3486|function countEnabledStaticCheckLanguages(config: UseReqC...|
+|`resetStaticCheckConfig`|fn||3495-3497|function resetStaticCheckConfig(config: UseReqConfig): void|
+|`formatStaticCheckLanguagesSummary`|fn||3505-3507|function formatStaticCheckLanguagesSummary(config: UseReq...|
+|`buildStaticCheckMenuChoices`|fn||3516-3548|function buildStaticCheckMenuChoices(config: UseReqConfig...|
+|`buildSupportedStaticCheckLanguageChoices`|fn||3556-3573|function buildSupportedStaticCheckLanguageChoices(config:...|
+|`buildConfiguredStaticCheckLanguageChoices`|fn||3581-3598|function buildConfiguredStaticCheckLanguageChoices(config...|
+|`configureStaticCheckMenu`|fn||3608-3754|async function configureStaticCheckMenu(|
+|`buildPiUsereqMenuChoices`|fn||3764-3856|function buildPiUsereqMenuChoices(|
+|`buildSrcDirMenuChoices`|fn||3865-3883|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
+|`buildSrcDirRemovalChoices`|fn||3892-3904|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
+|`configurePiUsereq`|fn||3915-4164|async function configurePiUsereq(|
+|`persistConfigChange`|fn||3926-3931|const persistConfigChange = () =>|
+|`registerConfigCommands`|fn||4174-4184|function registerConfigCommands(|
+|`piUsereqExtension`|fn||4193-4203|export default function piUsereqExtension(pi: ExtensionAP...|