pi-usereq 0.11.0 → 0.13.0

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.11.0";
+export const VERSION = "0.13.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -32,6 +32,7 @@ import {
   createStaticCheckLanguageConfig,
   getDefaultConfig,
   getDefaultStaticCheckConfig,
+  getGlobalConfigPath,
   getProjectConfigPath,
   loadConfig,
   normalizeConfigPaths,
@@ -91,6 +92,18 @@ import {
   restorePromptCommandExecution,
   type PromptCommandExecutionPlan,
 } from "./core/prompt-command-runtime.js";
+import {
+  REQ_REFERENCES_COMMAND_DESCRIPTION,
+  executeReqReferencesCommandExecution,
+  prepareReqReferencesCommandExecution,
+} from "./core/req-references-command.js";
+import {
+  REQ_RESET_COMMAND_DESCRIPTION,
+  executeReqResetCommandExecution,
+  prepareReqResetCommandExecution,
+  type ReqResetCommandExecutionResult,
+  type ReqResetCommandPlan,
+} from "./core/req-reset-command.js";
 import {
   DEBUG_PROMPT_NAMES,
   DEBUG_WORKFLOW_STATES,
@@ -114,6 +127,7 @@ import {
 import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import {
+  clearPersistedPromptCommandRuntimeState,
   readPersistedPromptCommandRuntimeState,
   writePersistedPromptCommandRuntimeState,
 } from "./core/prompt-command-state.js";
@@ -123,8 +137,10 @@ import {
   PI_USEREQ_STATUS_HOOK_NAMES,
   createPiUsereqStatusController,
   disposePiUsereqStatusController,
+  getPiUsereqRuntimeSoundLevel,
   isStaleExtensionContextError,
   renderPiUsereqStatus,
+  setPiUsereqRuntimeSoundLevel,
   setPiUsereqStatusConfig,
   setPiUsereqWorkflowState,
   shouldPreservePromptCommandStateOnShutdown,
@@ -135,13 +151,14 @@ import {
 import {
   runCompress,
   runFilesCompress,
-  runFilesReferences,
   runFilesSearch,
   runFilesStaticCheck,
+  runFilesSummarize,
   runFilesTokens,
   runProjectStaticCheck,
   runReferences,
   runSearch,
+  runSummarize,
   runTokens,
   type ToolResult,
 } from "./core/tool-runner.js";
@@ -252,12 +269,12 @@ function loadProjectConfig(cwd: string): UseReqConfig {
 }
 
 /**
- * @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.
+ * @brief Persists effective project configuration from the extension runtime.
+ * @details Resolves the project base, normalizes configured local directory paths into project-relative form, and delegates split local/global 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.
- * @param[in] config {UseReqConfig} Configuration to persist.
+ * @param[in] config {UseReqConfig} Effective configuration to persist.
  * @return {void} No return value.
- * @satisfies REQ-146
+ * @satisfies REQ-146, REQ-315
  */
 function saveProjectConfig(cwd: string, config: UseReqConfig): void {
   const projectBase = getProjectBase(cwd);
@@ -265,18 +282,28 @@ function saveProjectConfig(cwd: string, config: UseReqConfig): void {
 }
 
 /**
- * @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.
+ * @brief Formats the current local config path for top-level menu display.
+ * @details Resolves `<base-path>/.pi-usereq.json` from the cwd-derived project base and reuses the shared runtime-path formatter so the `Show local configuration` row uses the documented `~`-relative display contract. 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.
+ * @return {string} `~`-relative or absolute local config-path display value.
  * @satisfies REQ-162
  */
-function formatProjectConfigPathForMenu(cwd: string): string {
+function formatLocalConfigPathForMenu(cwd: string): string {
   return formatRuntimePathForDisplay(
     getProjectConfigPath(getProjectBase(cwd)),
   );
 }
 
+/**
+ * @brief Formats the current global config path for top-level menu display.
+ * @details Resolves `~/.config/pi-usereq/config.json` through the shared runtime-path formatter so the `Show global configuration` row uses the documented `~`-relative display contract. Runtime is O(p) in path length. No external state is mutated.
+ * @return {string} `~`-relative or absolute global config-path display value.
+ * @satisfies REQ-319
+ */
+function formatGlobalConfigPathForMenu(): string {
+  return formatRuntimePathForDisplay(getGlobalConfigPath());
+}
+
 /**
  * @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.
@@ -393,21 +420,46 @@ async function confirmResetChanges(
 }
 
 /**
- * @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.
+ * @brief Writes one already-persisted config file text into the editor.
+ * @details Reads the target config file from disk after the caller has saved any pending changes and forwards the 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.
+ * @param[in] configPath {string} Absolute persisted config path.
+ * @return {void} No return value.
+ */
+function writePersistedConfigToEditor(
+  ctx: ExtensionCommandContext,
+  configPath: string,
+): void {
+  ctx.ui.setEditorText(fs.readFileSync(configPath, "utf8"));
+}
+
+/**
+ * @brief Writes the already-persisted local configuration file text into the editor.
+ * @details Reads `<base-path>/.pi-usereq.json` from disk after the caller has saved any pending local and global configuration changes, then 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.
  * @param[in] cwd {string} Current working directory.
- * @param[in] _config {UseReqConfig} Unused effective project configuration retained for stable call-site shape.
  * @return {void} No return value.
  * @satisfies REQ-031
  */
-function writePersistedProjectConfigToEditor(
+function writePersistedLocalConfigToEditor(
   ctx: ExtensionCommandContext,
   cwd: string,
-  _config: UseReqConfig,
 ): void {
   const projectBase = getProjectBase(cwd);
-  ctx.ui.setEditorText(fs.readFileSync(getProjectConfigPath(projectBase), "utf8"));
+  writePersistedConfigToEditor(ctx, getProjectConfigPath(projectBase));
+}
+
+/**
+ * @brief Writes the already-persisted global configuration file text into the editor.
+ * @details Reads `~/.config/pi-usereq/config.json` from disk after the caller has saved any pending local and global configuration changes, then 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.
+ * @return {void} No return value.
+ * @satisfies REQ-318
+ */
+function writePersistedGlobalConfigToEditor(
+  ctx: ExtensionCommandContext,
+): void {
+  writePersistedConfigToEditor(ctx, getGlobalConfigPath());
 }
 
 /**
@@ -686,6 +738,44 @@ function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof b
   }
 }
 
+/**
+ * @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
+ */
+function executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult> {
+  const normalizeExecution = (
+    payload: ReturnType<typeof buildMonolithicToolExecuteResult>,
+  ): ReturnType<typeof buildMonolithicToolExecuteResult> => {
+    const execution = payload.details.execution;
+    return {
+      content: payload.content,
+      details: {
+        execution: {
+          code: execution.code,
+          ...(Array.isArray(execution.stderr_lines) && execution.stderr_lines.length > 0
+            ? { stderr_lines: execution.stderr_lines }
+            : {}),
+        },
+      },
+    };
+  };
+
+  try {
+    return normalizeExecution(buildMonolithicToolExecuteResult(operation()));
+  } catch (error) {
+    const failure = normalizeToolFailure(error);
+    const diagnostic = failure.stderr.trim().replace(/^(Error|error):\s*/u, "") || "unknown failure";
+    return normalizeExecution(buildMonolithicToolExecuteResult({
+      stdout: "",
+      stderr: `error: ${diagnostic}`,
+      code: failure.code,
+    }));
+  }
+}
+
 /**
  * @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.
@@ -838,7 +928,7 @@ function transitionPromptWorkflowState(
 
 /**
  * @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.
  */
@@ -889,6 +979,38 @@ function notifyContextSafely(
   }
 }
 
+/**
+ * @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,out] statusController {PiUsereqStatusController} Mutable status controller.
+ * @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.
+ * @return {never} This helper always throws a deterministic `ReqError`.
+ * @throws {ReqError} Always throws because non-`idle` req commands are rejected.
+ * @satisfies REQ-224
+ */
+function rejectNonIdleReqCommand(
+  statusController: PiUsereqStatusController,
+  ctx: ExtensionContext | ExtensionCommandContext,
+  promptName?: import("./core/prompt-command-catalog.js").PromptCommandName,
+): never {
+  const message = `ERROR: Prompt workflow state is ${statusController.state.workflowState}, expected idle.`;
+  if (promptName !== undefined && statusController.config !== undefined) {
+    transitionPromptWorkflowState(
+      statusController,
+      ctx,
+      resolveDebugProjectBase(ctx.cwd, statusController),
+      statusController.config,
+      promptName,
+      "error",
+    );
+  } else {
+    setPiUsereqWorkflowState(statusController, "error", ctx);
+  }
+  notifyContextSafely(ctx, message, "error");
+  throw new ReqError(message, 1);
+}
+
 /**
  * @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.
@@ -947,14 +1069,14 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
 
 /**
  * @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,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @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
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1025,7 +1147,10 @@ async function handleExtensionStatusEvent(
   if (hookName === "agent_end") {
     if (statusController.config) {
       runPiNotifyEffects(
-        statusController.config,
+        {
+          ...statusController.config,
+          "notify-sound": getPiUsereqRuntimeSoundLevel(statusController),
+        },
         event as { messages: AgentEndEvent["messages"] },
         notifyRequest,
       );
@@ -1041,7 +1166,6 @@ async function handleExtensionStatusEvent(
         ? `ERROR: Prompt closure retained worktree ${activePromptRequest.worktreeDir} after ${outcome} outcome.`
         : undefined;
       const shouldFinalizeMatchedSuccess = outcome === "completed"
-        && statusController.state.workflowState === "running"
         && activePromptRequest.worktreeDir !== undefined;
       if (debugConfig) {
         logPromptWorkflowEvent(
@@ -1080,6 +1204,7 @@ async function handleExtensionStatusEvent(
             mergeSucceeded: boolean;
             cleanupSucceeded: boolean;
             errorMessage?: string;
+            warningMessage?: string;
             activeContext?: unknown;
           }
           | undefined;
@@ -1134,6 +1259,14 @@ async function handleExtensionStatusEvent(
           }
           notifyContextSafely(promptContext, finalization.errorMessage, "error");
         }
+        if (
+          finalization.warningMessage
+          && finalization.cleanupSucceeded
+          && finalization.mergeSucceeded
+          && !finalization.errorMessage
+        ) {
+          notifyContextSafely(promptContext, finalization.warningMessage, "info");
+        }
       } else {
         try {
           promptContext = (await restorePromptCommandExecution(
@@ -1383,6 +1516,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       id: "debug-enabled",
       label: "Debug",
       value: config.DEBUG_ENABLED,
+      values: ["enable", "disable"],
       description: "Enable or disable all debug logging behavior and unlock the remaining Debug rows.",
     },
     buildDebugMenuChoice(
@@ -1408,6 +1542,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: "debug-status-changes",
         label: "Status changes",
         value: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES),
+        values: ["enable", "disable"],
         description: "Enable or disable `workflow_state` debug entries for prompt-orchestration transitions.",
       },
       debugEnabled,
@@ -1417,6 +1552,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: "debug-workflow-events",
         label: "Workflow events",
         value: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS),
+        values: ["enable", "disable"],
         description: "Enable or disable dedicated workflow debug entries for activation, restoration, closure, and session-shutdown diagnostics.",
       },
       debugEnabled,
@@ -1426,6 +1562,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: `debug-tool:${toolName}`,
         label: toolName,
         value: enabledTools.has(toolName) ? "enable" : "disable",
+        values: ["enable", "disable"],
         description: PI_USEREQ_CUSTOM_TOOL_NAMES.includes(toolName as never)
           ? `Toggle debug logging for custom tool ${toolName}.`
           : `Toggle debug logging for embedded tool ${toolName}.`,
@@ -1437,6 +1574,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: `debug-prompt:${promptName}`,
         label: promptName,
         value: enabledPrompts.has(promptName) ? "enable" : "disable",
+        values: ["enable", "disable"],
         description: `Toggle prompt-orchestration debug logging for /${promptName}.`,
       },
       debugEnabled,
@@ -1464,6 +1602,58 @@ async function configureDebugMenu(
   while (true) {
     const choice = await showPiUsereqSettingsMenu(ctx, "Debug", buildDebugMenuChoices(config), {
       initialSelectedId: focusedChoiceId,
+      getChoices: () => buildDebugMenuChoices(config),
+      onChange: (choiceId, newValue) => {
+        if (choiceId === "debug-enabled") {
+          config.DEBUG_ENABLED = newValue === "enable" ? "enable" : "disable";
+          onConfigChange();
+          ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
+          return;
+        }
+        if (choiceId === "debug-status-changes") {
+          config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(newValue);
+          onConfigChange();
+          ctx.ui.notify(`Debug status-change logging ${config.DEBUG_STATUS_CHANGES}`, "info");
+          return;
+        }
+        if (choiceId === "debug-workflow-events") {
+          config.DEBUG_WORKFLOW_EVENTS = normalizeDebugWorkflowEvents(newValue);
+          onConfigChange();
+          ctx.ui.notify(`Debug workflow-event logging ${config.DEBUG_WORKFLOW_EVENTS}`, "info");
+          return;
+        }
+        if (choiceId.startsWith("debug-tool:")) {
+          const toolName = choiceId.slice("debug-tool:".length) as PiUsereqStartupToolName;
+          const enabledTools = new Set(normalizeDebugEnabledTools(config.DEBUG_ENABLED_TOOLS));
+          if (newValue === "enable") {
+            enabledTools.add(toolName);
+          } else {
+            enabledTools.delete(toolName);
+          }
+          config.DEBUG_ENABLED_TOOLS = getDebugToolToggleNames().filter((name) => enabledTools.has(name));
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "enable" ? "Enabled" : "Disabled"} debug logging for ${toolName}`,
+            "info",
+          );
+          return;
+        }
+        if (choiceId.startsWith("debug-prompt:")) {
+          const promptName = choiceId.slice("debug-prompt:".length) as (typeof DEBUG_PROMPT_NAMES)[number];
+          const enabledPrompts = new Set(normalizeDebugEnabledPrompts(config.DEBUG_ENABLED_PROMPTS));
+          if (newValue === "enable") {
+            enabledPrompts.add(promptName);
+          } else {
+            enabledPrompts.delete(promptName);
+          }
+          config.DEBUG_ENABLED_PROMPTS = DEBUG_PROMPT_NAMES.filter((name) => enabledPrompts.has(name));
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "enable" ? "Enabled" : "Disabled"} debug logging for ${promptName}`,
+            "info",
+          );
+        }
+      },
     });
     if (!choice) {
       return;
@@ -1751,6 +1941,13 @@ const PI_NOTIFY_EVENT_MENU_DEFINITIONS: Record<
   },
 };
 
+/**
+ * @brief Defines the canonical label used for persisted boot-sound menu rows.
+ * @details Reuses one shared string literal across notification menu rows, selectors, reset previews, and tests so the persisted boot-sound terminology remains stable. Access complexity is O(1).
+ * @satisfies REQ-149, REQ-179
+ */
+const PI_NOTIFY_BOOT_SOUND_LABEL = "Enable sound (boot value)";
+
 /**
  * @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.
@@ -1806,6 +2003,7 @@ function buildPiNotifyEventMenuChoices(
       id: eventMenu.keys[row.eventId],
       label: row.label,
       value: config[eventMenu.keys[row.eventId]] ? "on" : "off",
+      values: ["on", "off"],
       description: `${eventMenu.systemLabel}: ${row.description}`,
     })),
     ...buildTerminalSettingsMenuChoices({
@@ -1870,7 +2068,23 @@ async function configurePiNotifyEventMenu(
       ctx,
       eventMenu.submenuTitle,
       buildPiNotifyEventMenuChoices(config, eventMenu),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiNotifyEventMenuChoices(config, eventMenu),
+        onChange: (choiceId, newValue) => {
+          const enabled = newValue === "on";
+          config[choiceId as PiNotifyEventBooleanConfigKey] = enabled;
+          onConfigChange();
+          const eventLabel = resolvePiNotifyEventLabel(
+            choiceId as PiNotifyEventBooleanConfigKey,
+            eventMenu,
+          );
+          ctx.ui.notify(
+            `${eventMenu.systemLabel} ${eventLabel} ${enabled ? "enabled" : "disabled"}`,
+            "info",
+          );
+        },
+      },
     );
     if (!choice) {
       return;
@@ -1922,7 +2136,7 @@ async function configurePiNotifyEventMenu(
 
 /**
  * @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
@@ -1934,8 +2148,9 @@ function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuCh
       id: "notify-pushover-enabled",
       label: "Enable pushover",
       labelTone: pushoverCredentialsReady ? undefined : "dim",
-      value: pushoverCredentialsReady ? formatPiNotifyPushoverStatus(config) : "off",
+      value: pushoverCredentialsReady ? formatPiNotifyPushoverStatus(config) : "configure user/token keys first",
       valueTone: pushoverCredentialsReady ? undefined : "dim",
+      values: ["on", "off"],
       disabled: !pushoverCredentialsReady,
       description: pushoverCredentialsReady
         ? "Enable or disable all Pushover delivery globally."
@@ -2018,10 +2233,10 @@ async function selectPiNotifyPushoverPriority(
 
 /**
  * @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
  */
 function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
@@ -2029,6 +2244,7 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
       id: "notify-enabled",
       label: "Enable notification",
       value: formatPiNotifyStatus(config),
+      values: ["on", "off"],
       description: "Enable or disable command-notify delivery globally.",
     },
     buildPiNotifyEventLauncherChoice(
@@ -2043,9 +2259,9 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
     },
     {
       id: "selected-sound-command",
-      label: "Enable sound",
+      label: PI_NOTIFY_BOOT_SOUND_LABEL,
       value: config["notify-sound"],
-      description: "Select which sound command level is currently active.",
+      description: "Edit the persisted boot sound level without changing the active runtime sound level.",
     },
     buildPiNotifyEventLauncherChoice(
       config,
@@ -2055,25 +2271,25 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
       id: "sound-toggle-hotkey-bind",
       label: "Sound toggle hotkey bind",
       value: config["notify-sound-toggle-shortcut"],
-      description: "Edit the keyboard shortcut that cycles the selected sound command.",
+      description: "Edit the keyboard shortcut that cycles the active runtime sound level.",
     },
     {
       id: "sound-command-low",
       label: "Sound command (low vol.)",
       value: config.PI_NOTIFY_SOUND_LOW_CMD,
-      description: "Edit the shell command used when the selected sound command is `low`.",
+      description: "Edit the shell command used when the active runtime sound level is `low`.",
     },
     {
       id: "sound-command-mid",
       label: "Sound command (mid vol.)",
       value: config.PI_NOTIFY_SOUND_MID_CMD,
-      description: "Edit the shell command used when the selected sound command is `mid`.",
+      description: "Edit the shell command used when the active runtime sound level is `mid`.",
     },
     {
       id: "sound-command-high",
       label: "Sound command (high vol.)",
       value: config.PI_NOTIFY_SOUND_HIGH_CMD,
-      description: "Edit the shell command used when the selected sound command is `high`.",
+      description: "Edit the shell command used when the active runtime sound level is `high`.",
     },
     ...buildPiNotifyPushoverRows(config),
     ...buildTerminalSettingsMenuChoices({
@@ -2083,44 +2299,44 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
 }
 
 /**
- * @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.
+ * @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
  */
 async function selectPiNotifySoundLevel(
   ctx: ExtensionCommandContext,
   currentLevel: PiNotifySoundLevel,
 ): Promise<PiNotifySoundLevel | "reset-defaults" | undefined> {
-  const choice = await showPiUsereqSettingsMenu(ctx, "Enable sound", [
+  const choice = await showPiUsereqSettingsMenu(ctx, PI_NOTIFY_BOOT_SOUND_LABEL, [
     {
       id: "none",
       label: "none",
       value: currentLevel === "none" ? "selected" : "",
-      description: "Disable sound-command delivery while preserving per-event sound toggles.",
+      description: "Persist `none` as the boot sound level loaded during the next session start.",
     },
     {
       id: "low",
       label: "low",
       value: currentLevel === "low" ? "selected" : "",
-      description: "Use the low-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `low` as the boot sound level loaded during the next session start.",
     },
     {
       id: "mid",
       label: "mid",
       value: currentLevel === "mid" ? "selected" : "",
-      description: "Use the mid-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `mid` as the boot sound level loaded during the next session start.",
     },
     {
       id: "high",
       label: "high",
       value: currentLevel === "high" ? "selected" : "",
-      description: "Use the high-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `high` as the boot sound level loaded during the next session start.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsDescription: "Restore the documented default sound level.",
+      resetDefaultsDescription: "Restore the documented default boot sound level.",
     }),
   ], { initialSelectedId: currentLevel });
   if (!choice) {
@@ -2134,11 +2350,11 @@ async function selectPiNotifySoundLevel(
 
 /**
  * @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, persists every notification subtree mutation into global configuration, delegates completed/interrupted/failed toggles to dedicated event submenus, preserves boot-sound edits 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
  */
 async function configurePiNotifyMenu(
   ctx: ExtensionCommandContext,
@@ -2152,7 +2368,27 @@ async function configurePiNotifyMenu(
       ctx,
       "Notifications",
       buildPiNotifyMenuChoices(config),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiNotifyMenuChoices(config),
+        onChange: (choiceId, newValue) => {
+          if (choiceId === "notify-enabled" || choiceId === "notify-pushover-enabled") {
+            if (choiceId === "notify-pushover-enabled" && !hasPiNotifyPushoverCredentials(config)) {
+              config["notify-pushover-enabled"] = false;
+              ctx.ui.notify("Populate both Pushover credential fields before enabling Pushover", "info");
+              return;
+            }
+            const enabled = newValue === "on";
+            config[choiceId as PiNotifyBooleanConfigKey] = enabled;
+            onConfigChange();
+            const labelMap: Record<string, string> = {
+              "notify-enabled": "Notification",
+              "notify-pushover-enabled": "Pushover",
+            };
+            ctx.ui.notify(`${labelMap[choiceId]} ${enabled ? "enabled" : "disabled"}`, "info");
+          }
+        },
+      },
     );
     if (!choice) {
       return config["notify-sound-toggle-shortcut"] !== originalShortcut;
@@ -2216,22 +2452,22 @@ async function configurePiNotifyMenu(
         const approved = await confirmResetChanges(
           ctx,
           "Confirm sound reset",
-          [{ label: "Enable sound", previousValue: config["notify-sound"], nextValue: defaultSoundLevel }]
+          [{ label: PI_NOTIFY_BOOT_SOUND_LABEL, previousValue: config["notify-sound"], nextValue: defaultSoundLevel }]
             .filter((change) => change.previousValue !== change.nextValue),
-          "Approve restoring the documented default sound level.",
-          "Abort the sound reset and keep the current value.",
+          "Approve restoring the documented default boot sound level.",
+          "Abort the boot sound reset and keep the current value.",
         );
         if (!approved) {
-          ctx.ui.notify("Aborted sound reset", "info");
+          ctx.ui.notify("Aborted boot sound reset", "info");
         } else {
           config["notify-sound"] = defaultSoundLevel;
           onConfigChange();
-          ctx.ui.notify("Restored default sound level", "info");
+          ctx.ui.notify("Restored default boot sound level; active runtime sound is unchanged", "info");
         }
       } else if (nextLevel !== undefined) {
         config["notify-sound"] = nextLevel;
         onConfigChange();
-        ctx.ui.notify(`Enable sound set to ${nextLevel}`, "info");
+        ctx.ui.notify(`Stored ${PI_NOTIFY_BOOT_SOUND_LABEL.toLowerCase()} as ${nextLevel}; active runtime sound is unchanged`, "info");
       }
       continue;
     }
@@ -2376,7 +2612,7 @@ async function configurePiNotifyMenu(
       const defaults = getDefaultConfig("");
       const resetPreview: ResetConfirmationChange[] = [
         { label: "Enable notification", previousValue: formatPiNotifyStatus(config), nextValue: formatPiNotifyStatus(defaults) },
-        { label: "Enable sound", previousValue: config["notify-sound"], nextValue: defaults["notify-sound"] },
+        { label: PI_NOTIFY_BOOT_SOUND_LABEL, previousValue: config["notify-sound"], nextValue: defaults["notify-sound"] },
         { label: "Sound toggle hotkey bind", previousValue: config["notify-sound-toggle-shortcut"], nextValue: defaults["notify-sound-toggle-shortcut"] },
         { label: "Notify command", previousValue: config.PI_NOTIFY_CMD, nextValue: defaults.PI_NOTIFY_CMD },
         { label: "Sound command (low vol.)", previousValue: config.PI_NOTIFY_SOUND_LOW_CMD, nextValue: defaults.PI_NOTIFY_SOUND_LOW_CMD },
@@ -2410,16 +2646,16 @@ async function configurePiNotifyMenu(
 
 /**
  * @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.
+ * @details Loads the current effective config, registers one raw pi shortcut when
+ * the runtime exposes `registerShortcut(...)`, cycles only the active runtime
+ * sound level on invocation, leaves persisted local and global configuration
+ * 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-131, REQ-134, REQ-180
+ * @satisfies REQ-134, REQ-180, REQ-286, REQ-287
  */
 function registerPiNotifyShortcut(
   pi: ExtensionAPI,
@@ -2433,19 +2669,170 @@ function registerPiNotifyShortcut(
   shortcutRegistrar.registerShortcut(config["notify-sound-toggle-shortcut"], {
     description: "Cycle pi-usereq notification sound level",
     handler: async (ctx) => {
-      const nextConfig = loadProjectConfig(ctx.cwd);
-      nextConfig["notify-sound"] = cyclePiNotifySoundLevel(nextConfig["notify-sound"]);
-      saveProjectConfig(ctx.cwd, nextConfig);
-      setPiUsereqStatusConfig(statusController, nextConfig);
-      renderPiUsereqStatus(statusController, ctx);
-      ctx.ui.notify(`pi-usereq sound:${nextConfig["notify-sound"]}`, "info");
+      const nextRuntimeSoundLevel = cyclePiNotifySoundLevel(
+        getPiUsereqRuntimeSoundLevel(statusController),
+      );
+      setPiUsereqRuntimeSoundLevel(
+        statusController,
+        nextRuntimeSoundLevel,
+        ctx,
+      );
+      ctx.ui.notify(`pi-usereq sound:${nextRuntimeSoundLevel}`, "info");
+    },
+  });
+}
+
+/**
+ * @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.
+ */
+function resolveReqResetPromptRequest(
+  statusController: PiUsereqStatusController,
+): PromptCommandExecutionPlan | undefined {
+  const isWorktreeBacked = (request: PromptCommandExecutionPlan | undefined): request is PromptCommandExecutionPlan =>
+    request?.worktreeDir !== undefined
+      && request.worktreeRootPath !== undefined
+      && request.worktreePath !== undefined;
+  const inMemoryActiveRequest = statusController.state.activePromptRequest;
+  if (isWorktreeBacked(inMemoryActiveRequest)) {
+    return inMemoryActiveRequest;
+  }
+  const inMemoryPendingRequest = statusController.state.pendingPromptRequest;
+  if (isWorktreeBacked(inMemoryPendingRequest)) {
+    return inMemoryPendingRequest;
+  }
+  const persistedRuntimeState = readPersistedPromptCommandRuntimeState();
+  if (isWorktreeBacked(persistedRuntimeState.activePromptRequest)) {
+    return persistedRuntimeState.activePromptRequest;
+  }
+  if (isWorktreeBacked(persistedRuntimeState.pendingPromptRequest)) {
+    return persistedRuntimeState.pendingPromptRequest;
+  }
+  return inMemoryActiveRequest
+    ?? inMemoryPendingRequest
+    ?? persistedRuntimeState.activePromptRequest
+    ?? persistedRuntimeState.pendingPromptRequest;
+}
+
+/**
+ * @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
+ */
+function registerReqResetCommand(
+  pi: ExtensionAPI,
+  statusController: PiUsereqStatusController,
+): void {
+  pi.registerCommand("req-reset", {
+    description: REQ_RESET_COMMAND_DESCRIPTION,
+    handler: async (_args, ctx) => {
+      const promptRequest = resolveReqResetPromptRequest(statusController);
+      const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+      syncContextCwdMirror(ctx, commandCwd);
+      const projectBase = path.resolve(promptRequest?.basePath ?? getProjectBase(commandCwd));
+      bootstrapRuntimePathState(projectBase, {
+        gitPath: resolveRuntimeGitPath(projectBase),
+      });
+      const config = loadProjectConfig(projectBase);
+      let executionPlan: ReqResetCommandPlan;
+      let executionResult: ReqResetCommandExecutionResult;
+      let resetContext = ctx;
+
+      setPiUsereqStatusConfig(statusController, config);
+      setPiUsereqWorkflowState(statusController, "running", ctx);
+
+      try {
+        executionPlan = prepareReqResetCommandExecution(projectBase, config, promptRequest);
+        executionResult = await executeReqResetCommandExecution(executionPlan, ctx);
+        resetContext = (executionResult.activeContext ?? resetContext) as typeof ctx;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        setPiUsereqWorkflowState(statusController, "error", resetContext);
+        notifyContextSafely(resetContext, message, "error");
+        throw error;
+      }
+
+      const shouldClearPromptState = executionResult.restoredBasePath
+        || executionPlan.promptRequest === undefined;
+      if (shouldClearPromptState) {
+        statusController.state.pendingPromptRequest = undefined;
+        statusController.state.activePromptRequest = undefined;
+        clearPersistedPromptCommandRuntimeState();
+      }
+
+      if (executionResult.errorMessage) {
+        setPiUsereqWorkflowState(statusController, "error", resetContext);
+        notifyContextSafely(resetContext, executionResult.errorMessage, "error");
+        throw new ReqError(executionResult.errorMessage, 1);
+      }
+
+      setPiUsereqWorkflowState(statusController, "idle", resetContext);
+      const successMessage = executionPlan.promptRequest !== undefined
+        ? `SUCCESS: req-reset restored base-path and removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es).`
+        : `SUCCESS: req-reset removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es) and restored idle state.`;
+      notifyContextSafely(resetContext, successMessage, "info");
     },
   });
 }
 
 /**
- * @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.
+ * @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-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303
+ */
+function registerReqReferencesCommand(
+  pi: ExtensionAPI,
+  statusController: PiUsereqStatusController,
+): void {
+  pi.registerCommand("req-references", {
+    description: REQ_REFERENCES_COMMAND_DESCRIPTION,
+    handler: async (_args, ctx) => {
+      if (statusController.state.workflowState !== "idle") {
+        rejectNonIdleReqCommand(statusController, ctx);
+      }
+      const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+      syncContextCwdMirror(ctx, commandCwd);
+      bootstrapRuntimePathState(commandCwd, {
+        gitPath: resolveRuntimeGitPath(commandCwd),
+      });
+      const projectBase = getProjectBase(commandCwd);
+      const config = loadProjectConfig(commandCwd);
+      setPiUsereqStatusConfig(statusController, config);
+      statusController.state.pendingPromptRequest = undefined;
+      statusController.state.activePromptRequest = undefined;
+      setPiUsereqWorkflowState(statusController, "checking", ctx);
+      try {
+        const executionPlan = prepareReqReferencesCommandExecution(projectBase, config);
+        setPiUsereqWorkflowState(statusController, "running", ctx);
+        executeReqReferencesCommandExecution(executionPlan, config);
+        setPiUsereqWorkflowState(statusController, "idle", ctx);
+        ctx.ui.notify(
+          `SUCCESS: Updated ${formatRuntimePathForDisplay(executionPlan.referencesPath)} and committed changes.`,
+          "info",
+        );
+      } catch (error) {
+        statusController.state.pendingPromptRequest = undefined;
+        statusController.state.activePromptRequest = undefined;
+        setPiUsereqWorkflowState(statusController, "error", ctx);
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(message, "error");
+        throw error;
+      }
+    },
+  });
+}
+
+/**
+ * @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.
@@ -2460,9 +2847,7 @@ function registerPromptCommands(
       description: resolvePromptCommandDescription(promptName),
       handler: async (args, ctx) => {
         if (statusController.state.workflowState !== "idle") {
-          const message = `ERROR: Prompt workflow state is ${statusController.state.workflowState}, expected idle.`;
-          ctx.ui.notify(message, "error");
-          throw new ReqError(message, 1);
+          rejectNonIdleReqCommand(statusController, ctx, promptName);
         }
         const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
         syncContextCwdMirror(ctx, commandCwd);
@@ -2577,10 +2962,10 @@ function registerPromptCommands(
  * @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
  */
 function registerAgentTools(pi: ExtensionAPI): void {
-  const filesReferencesSchema = Type.Object(
+  const filesSummarizeSchema = Type.Object(
     {
       files: Type.Array(
         Type.String({ description: "Project-relative or absolute source file path resolved from the current working directory when not already absolute" }),
@@ -2632,21 +3017,21 @@ function registerAgentTools(pi: ExtensionAPI): void {
   });
 
   pi.registerTool({
-    name: "files-references",
-    label: "files-references",
-    description: "Scope: explicit source files. Return the monolithic references markdown report in content[0].text and keep only execution metadata in details.execution.",
-    promptSnippet: "Return the monolithic references markdown report for caller-selected source files.",
+    name: "files-summarize",
+    label: "files-summarize",
+    description: "Scope: explicit source files. Return the monolithic summary markdown report in content[0].text and keep only execution metadata in details.execution.",
+    promptSnippet: "Return the monolithic summary markdown report for caller-selected source files.",
     promptGuidelines: [
       "Scope: explicit source files selected by files[]; caller order is preserved; each item may be project-relative or absolute.",
       "Output contract: monolithic markdown in content[0].text; details.execution preserves only exit code and residual diagnostics.",
-      "Formatting contract: content matches the Python reference renderer used by `generate_markdown.py`.",
+      "Formatting contract: content matches the Python summary renderer used by `generate_markdown.py`.",
       "Behavior contract: missing inputs, non-file inputs, unsupported extensions, and analysis failures surface through details.execution diagnostics.",
     ],
-    renderResult: buildStructuredToolRenderResult("files-references"),
-    parameters: filesReferencesSchema,
+    renderResult: buildStructuredToolRenderResult("files-summarize"),
+    parameters: filesSummarizeSchema,
     async execute(_toolCallId, params) {
       const contextPath = getRuntimeContextPath(process.cwd());
-      return executeMonolithicTool(() => runFilesReferences(params.files, contextPath));
+      return executeMonolithicTool(() => runFilesSummarize(params.files, contextPath));
     },
   });
 
@@ -2717,12 +3102,18 @@ function registerAgentTools(pi: ExtensionAPI): void {
     },
   });
 
-  const referencesSchema = Type.Object(
+  const summarizeSchema = Type.Object(
     {},
     {
       description: "Input contract: no params. Scope is the configured src-dir list resolved from the current project configuration. Output contract: monolithic markdown in content[0].text plus details.execution diagnostics.",
     },
   );
+  const referencesSchema = Type.Object(
+    {},
+    {
+      description: "Input contract: no params. Scope is the configured src-dir list plus configured docs-dir resolved from the current project configuration. Output contract: content[0].text returns only `success` or `error: <diagnostic>`; the tool overwrites `<docs-dir>/REFERENCES.md` and keeps details.execution diagnostics.",
+    },
+  );
   const tokensSchema = Type.Object(
     {},
     {
@@ -2731,23 +3122,44 @@ function registerAgentTools(pi: ExtensionAPI): void {
   );
 
   pi.registerTool({
-    name: "references",
-    label: "references",
-    description: "Scope: configured project source directories. Return the monolithic references markdown report in content[0].text and keep only execution metadata in details.execution.",
-    promptSnippet: "Return the monolithic project references markdown report from the configured source directories.",
+    name: "summarize",
+    label: "summarize",
+    description: "Scope: configured project source directories. Return the monolithic summary markdown report in content[0].text and keep only execution metadata in details.execution.",
+    promptSnippet: "Return the monolithic project summary markdown report from the configured source directories.",
     promptGuidelines: [
       "Scope: no params; resolve src-dir from the current project configuration and scan the configured source surface from the current working directory.",
       "Output contract: monolithic markdown in content[0].text; details.execution preserves only exit code and residual diagnostics.",
       "Formatting contract: content prepends the file-structure markdown block before the per-file markdown produced by `generate_markdown.py`.",
       "Configuration contract: output changes with cwd-derived project config and src-dir values; the tool does not accept explicit file overrides.",
     ],
+    renderResult: buildStructuredToolRenderResult("summarize"),
+    parameters: summarizeSchema,
+    async execute() {
+      const contextPath = getRuntimeContextPath(process.cwd());
+      const projectBase = getProjectBase(contextPath);
+      const config = loadProjectConfig(projectBase);
+      return executeMonolithicTool(() => runSummarize(contextPath, config));
+    },
+  });
+
+  pi.registerTool({
+    name: "references",
+    label: "references",
+    description: "Scope: configured project source directories and configured docs-dir. Overwrite REFERENCES.md and return only success or error in content[0].text while keeping execution metadata in details.execution.",
+    promptSnippet: "Generate REFERENCES.md from the configured source directories without returning the generated markdown.",
+    promptGuidelines: [
+      "Scope: no params; resolve src-dir and docs-dir from the current project configuration and current working directory.",
+      "Behavior contract: generate the same file-structure-plus-summary markdown as `summarize` and overwrite `<docs-dir>/REFERENCES.md`.",
+      "Output contract: `content[0].text` is `success` on success or `error: <diagnostic>` on failure; generated markdown is never returned to the LLM.",
+      "Failure contract: source discovery, markdown generation, and file-write errors surface through the status text plus details.execution diagnostics.",
+    ],
     renderResult: buildStructuredToolRenderResult("references"),
     parameters: referencesSchema,
     async execute() {
       const contextPath = getRuntimeContextPath(process.cwd());
       const projectBase = getProjectBase(contextPath);
       const config = loadProjectConfig(projectBase);
-      return executeMonolithicTool(() => runReferences(contextPath, config));
+      return executeStatusTool(() => runReferences(contextPath, config));
     },
   });
 
@@ -2938,6 +3350,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
       id: tool.name,
       label: tool.name,
       value: enabledTools.has(tool.name) ? "on" : "off",
+      values: ["on", "off"],
       description: tool.description ?? `Toggle startup activation for ${tool.name}.`,
     })),
     ...buildTerminalSettingsMenuChoices({
@@ -2948,7 +3361,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
 
 /**
  * @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.
+ * @details Synchronizes runtime active tools with the effective config, renders startup-tool actions through the shared settings-menu UI, persists enablement changes into global configuration, 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.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
@@ -3012,7 +3425,29 @@ async function configurePiUsereqToolsMenu(
     }
 
     if (choice === "enable-tools") {
-      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config));
+      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config), {
+        getChoices: () => buildPiUsereqToolToggleChoices(pi, config),
+        onChange: (toolName, newValue) => {
+          const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
+          if (newValue === "on") {
+            enabledTools.add(toolName as PiUsereqStartupToolName);
+          } else {
+            enabledTools.delete(toolName as PiUsereqStartupToolName);
+          }
+          setConfiguredPiUsereqTools(
+            pi,
+            config,
+            getPiUsereqStartupTools(pi)
+              .map((tool) => tool.name)
+              .filter((currentToolName) => enabledTools.has(currentToolName)),
+          );
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "on" ? "Enabled" : "Disabled"} ${toolName}`,
+            "info",
+          );
+        },
+      });
       if (!selectedToolName) {
         continue;
       }
@@ -3138,6 +3573,7 @@ function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenu
         id: `toggle-static-check-language:${language}`,
         label: language,
         value: languageConfig.enabled === "enable" ? "on" : "off",
+        values: ["on", "off"],
         description: `Toggle static-check execution for ${language}. Configured ${configuredCount} ${suffix}. Supported extensions: ${extensions.join(", ")}.`,
       };
     }),
@@ -3199,7 +3635,7 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
 
 /**
  * @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.
+ * @details Lets the user add and remove global Command entries, toggle direct local 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.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
@@ -3214,6 +3650,19 @@ async function configureStaticCheckMenu(
   while (true) {
     const staticChoice = await showPiUsereqSettingsMenu(ctx, "Language static code checkers", buildStaticCheckMenuChoices(config), {
       initialSelectedId: focusedChoiceId,
+      getChoices: () => buildStaticCheckMenuChoices(config),
+      onChange: (choiceId, newValue) => {
+        if (choiceId.startsWith("toggle-static-check-language:")) {
+          const language = choiceId.slice("toggle-static-check-language:".length);
+          config["static-check"][language] ??= createStaticCheckLanguageConfig([]);
+          config["static-check"][language]!.enabled = newValue === "on" ? "enable" : "disable";
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "on" ? "Enabled" : "Disabled"} static-check for ${language}`,
+            "info",
+          );
+        }
+      },
     });
 
     if (!staticChoice) {
@@ -3342,11 +3791,11 @@ async function configureStaticCheckMenu(
 
 /**
  * @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.
+ * @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 display-only local plus global config paths. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @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
+ * @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, REQ-314, REQ-318, REQ-319, REQ-320
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -3380,6 +3829,7 @@ function buildPiUsereqMenuChoices(
       id: "auto-git-commit",
       label: "Auto git commit",
       value: config.AUTO_GIT_COMMIT,
+      values: ["enable", "disable"],
       description: "Select bundled `git_commit.md` or `git_read-only.md` for `%%COMMIT%%`; disabling also forces prompt-command worktrees off.",
     },
     {
@@ -3388,6 +3838,8 @@ function buildPiUsereqMenuChoices(
       labelTone: autoGitCommitDisabled ? "dim" : undefined,
       value: effectiveGitWorktreeEnabled,
       valueTone: autoGitCommitDisabled ? "dim" : undefined,
+      values: ["enable", "disable"],
+      disabled: autoGitCommitDisabled,
       description: autoGitCommitDisabled
         ? "Forced to `disable` while `Auto git commit` is disabled."
         : "Enable or disable prompt-command worktree orchestration.",
@@ -3406,32 +3858,39 @@ function buildPiUsereqMenuChoices(
       id: "static-check",
       label: "Language static code checkers",
       value: formatStaticCheckLanguagesSummary(config),
-      description: "Manage guided Command static-check entries and per-language enable flags.",
+      description: "Manage global Command static-check entries and local per-language enable flags.",
     },
     {
       id: "startup-tools",
       label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
-      description: "Manage which configurable tools become active during session_start.",
+      description: "Manage the global configurable tool set activated during session_start.",
     },
     {
       id: "notifications",
       label: "Notifications",
       value: `notification:${formatPiNotifyStatus(config)} • sound:${config["notify-sound"]} • pushover:${formatPiNotifyPushoverStatus(config)}`,
-      description: "Manage command-notify, sound, and Pushover settings with dedicated event submenus.",
+      description: "Manage global command-notify, sound, and Pushover settings with dedicated event submenus.",
     },
     {
       id: "debug",
       label: "Debug",
       value: formatDebugMenuSummary(config),
-      description: "Manage debug logging for tools and `req-*` prompt orchestration.",
+      description: "Manage project-local debug logging for tools and `req-*` prompt orchestration.",
+    },
+    {
+      id: "show-local-config",
+      label: "Show local configuration",
+      value: formatLocalConfigPathForMenu(cwd),
+      valueTone: "dim",
+      description: "Persist pending configuration changes and write the exact local config file text into the editor.",
     },
     {
-      id: "show-config",
-      label: "Show configuration",
-      value: formatProjectConfigPathForMenu(cwd),
+      id: "show-global-config",
+      label: "Show global configuration",
+      value: formatGlobalConfigPathForMenu(),
       valueTone: "dim",
-      description: "Persist the current project configuration file and write its exact text into the editor.",
+      description: "Persist pending configuration changes and write the exact global config file text into the editor.",
     },
     ...buildTerminalSettingsMenuChoices({
       resetDefaultsDescription: "Restore the default pi-usereq configuration for the current project base.",
@@ -3489,12 +3948,12 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
 
 /**
  * @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.
+ * @details Loads the effective merged 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 local configuration` or `Show global 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.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @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
+ * @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, REQ-314, REQ-318, REQ-319, REQ-320
  */
 async function configurePiUsereq(
   pi: ExtensionAPI,
@@ -3520,7 +3979,36 @@ async function configurePiUsereq(
       ctx,
       "pi-usereq",
       buildPiUsereqMenuChoices(ctx.cwd, config),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config),
+        onChange: (choiceId, newValue) => {
+          if (choiceId === "auto-git-commit") {
+            config.AUTO_GIT_COMMIT = newValue === "enable" ? "enable" : "disable";
+            if (config.AUTO_GIT_COMMIT === "disable") {
+              config.GIT_WORKTREE_ENABLED = "disable";
+              persistConfigChange();
+              ctx.ui.notify("Auto git commit disabled; Git worktree forced off", "info");
+            } else {
+              persistConfigChange();
+              ctx.ui.notify("Auto git commit enabled", "info");
+            }
+            return;
+          }
+          if (choiceId === "git-worktree-enabled") {
+            if (config.AUTO_GIT_COMMIT === "disable") {
+              ctx.ui.notify("Git worktree is locked while Auto git commit is disabled", "info");
+              return;
+            }
+            config.GIT_WORKTREE_ENABLED = newValue === "enable" ? "enable" : "disable";
+            persistConfigChange();
+            ctx.ui.notify(
+              `Git worktree ${resolveEffectiveGitWorktreeEnabled(config.AUTO_GIT_COMMIT, config.GIT_WORKTREE_ENABLED) === "enable" ? "enabled" : "disabled"}`,
+              "info",
+            );
+          }
+        },
+      },
     );
     if (!choice) {
       if (config["notify-sound-toggle-shortcut"] !== initialShortcut) {
@@ -3707,12 +4195,16 @@ async function configurePiUsereq(
       ctx.ui.notify("Restored all default configuration values", "info");
       continue;
     }
-    if (choice === "show-config") {
+    if (choice === "show-local-config" || choice === "show-global-config") {
       persistConfigChange();
       if (config["notify-sound-toggle-shortcut"] !== initialShortcut) {
         ctx.ui.notify("Sound toggle hotkey bind updated; run /reload to apply the new binding", "info");
       }
-      writePersistedProjectConfigToEditor(ctx, ctx.cwd, config);
+      if (choice === "show-local-config") {
+        writePersistedLocalConfigToEditor(ctx, ctx.cwd);
+      } else {
+        writePersistedGlobalConfigToEditor(ctx);
+      }
       return;
     }
   }
@@ -3740,23 +4232,16 @@ function registerConfigCommands(
 
 /**
  * @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
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
+  registerReqResetCommand(pi, statusController);
+  registerReqReferencesCommand(pi, statusController);
   registerPromptCommands(pi, statusController);
   registerAgentTools(pi);
   registerConfigCommands(pi, statusController);