pi-usereq 0.11.0 → 0.12.0

package/src/cli.ts

@@ -20,12 +20,12 @@ import {
   runCompress,
   runFilesCompress,
   runFilesSearch,
-  runFilesReferences,
+  runFilesSummarize,
   runFilesStaticCheck,
   runFilesTokens,
   runSearch,
   runProjectStaticCheck,
-  runReferences,
+  runSummarize,
   runTokens,
 } from "./core/tool-runner.js";
 import {
@@ -46,10 +46,10 @@ interface ParsedArgs {
   enableLineNumbers?: boolean;
   enableStaticCheck?: string[];
   filesTokens?: string[];
-  filesReferences?: string[];
+  filesSummarize?: string[];
   filesCompress?: string[];
   filesSearch?: string[];
-  references?: boolean;
+  summarize?: boolean;
   compress?: boolean;
   search?: [string, string];
   tokens?: boolean;
@@ -106,9 +106,9 @@ function parseArgs(argv: string[]): ParsedArgs {
         index = next;
         break;
       }
-      case "--files-references": {
+      case "--files-summarize": {
         const [values, next] = takeUntilOption(index + 1);
-        parsed.filesReferences = values;
+        parsed.filesSummarize = values;
         index = next;
         break;
       }
@@ -124,8 +124,8 @@ function parseArgs(argv: string[]): ParsedArgs {
         index = next;
         break;
       }
-      case "--references":
-        parsed.references = true;
+      case "--summarize":
+        parsed.summarize = true;
         index += 1;
         break;
       case "--compress":
@@ -256,12 +256,12 @@ export function main(argv = process.argv.slice(2)): number {
     }
     const args = parseArgs(argv);
     const hereOnlyProjectCommand = !!(
-      args.references || args.compress || args.tokens || args.search || args.staticCheck
+      args.summarize || args.compress || args.tokens || args.search || args.staticCheck
     );
     if (hereOnlyProjectCommand) {
       if (args.base) {
         throw new ReqError(
-          "Error: --references, --compress, --tokens, --find, and --static-check do not allow --base; use --here.",
+          "Error: --summarize, --compress, --tokens, --find, and --static-check do not allow --base; use --here.",
           1,
         );
       }
@@ -281,12 +281,12 @@ export function main(argv = process.argv.slice(2)): number {
     }
 
     if (args.filesTokens) return writeResult(runFilesTokens(args.filesTokens));
-    if (args.filesReferences) return writeResult(runFilesReferences(args.filesReferences, process.cwd(), args.verbose));
+    if (args.filesSummarize) return writeResult(runFilesSummarize(args.filesSummarize, process.cwd(), args.verbose));
     if (args.filesCompress) return writeResult(runFilesCompress(args.filesCompress, process.cwd(), args.enableLineNumbers, args.verbose));
     if (args.filesSearch) return writeResult(runFilesSearch(args.filesSearch, args.enableLineNumbers, args.verbose));
     if (args.testStaticCheck) return runStaticCheck(args.testStaticCheck);
     if (args.filesStaticCheck) return writeResult(runFilesStaticCheck(args.filesStaticCheck, projectBase, config));
-    if (args.references) return writeResult(runReferences(projectBase, config, args.verbose));
+    if (args.summarize) return writeResult(runSummarize(projectBase, config, args.verbose));
     if (args.compress) return writeResult(runCompress(projectBase, config, args.enableLineNumbers, args.verbose));
     if (args.search) return writeResult(runSearch(projectBase, args.search[0], args.search[1], config, args.enableLineNumbers, args.verbose));
     if (args.tokens) return writeResult(runTokens(projectBase, config));

package/src/core/extension-status.ts

@@ -14,6 +14,7 @@ import type {
   ThemeColor,
 } from "@mariozechner/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
+import type { PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 import {
   restorePersistedPromptCommandRuntimeStateForSession,
@@ -111,7 +112,7 @@ export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging"
 
 /**
  * @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.
  */
 export interface PiUsereqStatusState {
   workflowState: PiUsereqWorkflowState;
@@ -119,6 +120,7 @@ export interface PiUsereqStatusState {
   runStartTimeMs: number | undefined;
   lastRunDurationMs: number | undefined;
   totalRunDurationMs: number | undefined;
+  runtimeSoundLevel: PiNotifySoundLevel | undefined;
   pendingPromptRequest: PiUsereqPromptRequest | undefined;
   activePromptRequest: PiUsereqPromptRequest | undefined;
 }
@@ -403,7 +405,7 @@ function resolveContextUsageIconText(
 
 /**
  * @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.
@@ -420,7 +422,7 @@ function formatContextUsageBar(
   if (percent >= 90) {
     return theme.colorize("error", "▕█▏");
   }
-  return resolveContextUsageIconText(contextUsage);
+  return theme.value(resolveContextUsageIconText(contextUsage));
 }
 
 /**
@@ -548,9 +550,24 @@ function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean {
   );
 }
 
+/**
+ * @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
+ */
+function resolvePiUsereqRuntimeSoundLevel(
+  state: PiUsereqStatusState,
+  config: UseReqConfig | undefined,
+): PiNotifySoundLevel {
+  return state.runtimeSoundLevel ?? config?.["notify-sound"] ?? "none";
+}
+
 /**
  * @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.
@@ -567,7 +584,7 @@ function buildPiUsereqStatusText(
   nowMs: number,
 ): string {
   const elapsedText = formatElapsedStatusValue(state, nowMs);
-  const soundText = config["notify-sound"];
+  const soundText = resolvePiUsereqRuntimeSoundLevel(state, config);
   return [
     formatRenderedStatusField(
       theme,
@@ -630,7 +647,7 @@ function syncPiUsereqStatusTicker(
 
 /**
  * @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
  */
@@ -644,6 +661,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
       runStartTimeMs: undefined,
       lastRunDurationMs: undefined,
       totalRunDurationMs: undefined,
+      runtimeSoundLevel: undefined,
       pendingPromptRequest: undefined,
       activePromptRequest: undefined,
     },
@@ -654,8 +672,9 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
 /**
  * @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,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] config {UseReqConfig} Effective project configuration.
@@ -668,13 +687,47 @@ export function setPiUsereqStatusConfig(
   controller.config = config;
 }
 
+/**
+ * @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
+ */
+export function getPiUsereqRuntimeSoundLevel(
+  controller: PiUsereqStatusController,
+): PiNotifySoundLevel {
+  return resolvePiUsereqRuntimeSoundLevel(controller.state, controller.config);
+}
+
+/**
+ * @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,out] controller {PiUsereqStatusController} Mutable status controller.
+ * @param[in] runtimeSoundLevel {PiNotifySoundLevel} Next active runtime sound level.
+ * @param[in] ctx {ExtensionContext | undefined} Optional active extension context.
+ * @return {void} No return value.
+ * @satisfies REQ-180, REQ-286, REQ-287
+ */
+export function setPiUsereqRuntimeSoundLevel(
+  controller: PiUsereqStatusController,
+  runtimeSoundLevel: PiNotifySoundLevel,
+  ctx?: ExtensionContext,
+): void {
+  controller.state.runtimeSoundLevel = runtimeSoundLevel;
+  const renderContext = ctx ?? controller.latestContext;
+  if (renderContext) {
+    renderPiUsereqStatus(controller, renderContext);
+  }
+}
+
 /**
  * @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,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @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
  */
 export function renderPiUsereqStatus(
   controller: PiUsereqStatusController,
@@ -685,6 +738,7 @@ export function renderPiUsereqStatus(
     return;
   }
   try {
+    refreshContextUsage(controller.state, ctx);
     const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
     const branchName = resolveStatusBranchValue(ctx);
     ctx.ui.setStatus(
@@ -732,13 +786,13 @@ export function setPiUsereqWorkflowState(
 
 /**
  * @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,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded from the wrapper.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @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
  */
 export function updateExtensionStatus(
   controller: PiUsereqStatusController,
@@ -757,6 +811,9 @@ export function updateExtensionStatus(
     } else {
       restorePersistedElapsedState(controller.state);
     }
+    controller.state.runtimeSoundLevel = controller.config?.["notify-sound"]
+      ?? controller.state.runtimeSoundLevel
+      ?? "none";
     const shouldResetWorkflowState = shouldResetWorkflowStateOnSessionStart(event);
     if (shouldResetWorkflowState) {
       controller.state.workflowState = "idle";

package/src/core/pi-notify.ts

@@ -110,7 +110,7 @@ export interface PiNotifyEventRequest {
 
 /**
  * @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.
  */
 export type PiNotifyConfigFields = Pick<
   UseReqConfig,
@@ -363,10 +363,10 @@ export function formatPiNotifyPushoverStatus(config: Pick<UseReqConfig, "notify-
 
 /**
  * @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
  */
 export function cyclePiNotifySoundLevel(currentLevel: PiNotifySoundLevel): PiNotifySoundLevel {
   const currentIndex = PI_NOTIFY_SOUND_LEVELS.indexOf(currentLevel);

package/src/core/pi-usereq-tools.ts

@@ -10,9 +10,10 @@
  */
 export const PI_USEREQ_CUSTOM_TOOL_NAMES = [
   "files-tokens",
-  "files-references",
+  "files-summarize",
   "files-compress",
   "files-search",
+  "summarize",
   "references",
   "compress",
   "search",
@@ -51,9 +52,10 @@ export const PI_USEREQ_STARTUP_TOOL_NAMES = [
  */
 export const PI_USEREQ_DEFAULT_ENABLED_TOOL_NAMES = [
   "files-tokens",
-  "files-references",
+  "files-summarize",
   "files-compress",
   "files-search",
+  "summarize",
   "references",
   "compress",
   "search",

package/src/core/prompt-command-catalog.ts

@@ -1,12 +1,12 @@
 /**
  * @file
- * @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.
  */
 
 /**
- * @brief Lists bundled prompt-command names handled by the extension.
- * @details Provides the single source of truth for `req-*` prompt registration, required-document routing, debug-prompt inventory derivation, and prompt-command worktree orchestration. Access complexity is O(1).
+ * @brief Lists bundled prompt-backed command names handled by the extension.
+ * @details Provides the single source of truth for prompt-template-backed `req-*` registration, required-document routing, debug-prompt inventory derivation, and prompt-command worktree orchestration. Access complexity is O(1).
  */
 export const PROMPT_COMMAND_NAMES = [
   "analyze",
@@ -21,7 +21,6 @@ export const PROMPT_COMMAND_NAMES = [
   "readme",
   "recreate",
   "refactor",
-  "references",
   "renumber",
   "workflow",
   "write",