pi-usereq 0.7.0 → 0.11.0

package/src/core/extension-status.ts

@@ -1,14 +1,12 @@
 /**
  * @file
  * @brief Tracks pi-usereq extension status state and renders status-bar telemetry.
- * @details Centralizes hook interception, context-usage snapshots, run timing,
- * and deterministic status-bar formatting for the pi-usereq extension. Runtime
- * is O(1) per event plus O(s) in configured source-path count during status
- * rendering. Side effects are limited to in-memory state mutation and interval
+ * @details Centralizes hook interception, context-usage snapshots, active-branch lookup, run timing, and deterministic status-bar formatting for the pi-usereq extension. Runtime
+ * is O(1) per event plus interval-driven re-renders while a prompt remains
+ * active. Side effects are limited to in-memory state mutation and interval
  * scheduling through exported controller helpers.
  */
 
-import path from "node:path";
 import type {
   AgentEndEvent,
   ContextUsage,
@@ -16,7 +14,12 @@ import type {
   ThemeColor,
 } from "@mariozechner/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
-import { normalizePathSlashes } from "./path-context.js";
+import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
+import {
+  restorePersistedPromptCommandRuntimeStateForSession,
+  writePersistedPromptCommandRuntimeState,
+} from "./prompt-command-state.js";
+import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
 
 /**
  * @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
@@ -96,18 +99,22 @@ export type PiUsereqStatusHookName = (typeof PI_USEREQ_STATUS_HOOK_NAMES)[number
 
 /**
  * @brief Describes one prompt request tracked across extension command delivery and runtime execution.
- * @details Stores the bundled prompt command name plus the raw argument string substituted into `%%ARGS%%` so later successful-run side effects can reconstruct prompt-specific completion notifications. The interface is compile-time only and introduces no runtime cost.
+ * @details Reuses the prepared prompt-command execution plan so status rendering and prompt-end side effects can recover the original project base, active execution base, and optional worktree metadata for the current prompt run. The alias is compile-time only and introduces no runtime cost.
  */
-export interface PiUsereqPromptRequest {
-  promptName: string;
-  promptArgs: string;
-}
+export type PiUsereqPromptRequest = PromptCommandExecutionPlan;
+
+/**
+ * @brief Represents one prompt-orchestration workflow state displayed in the status bar.
+ * @details Narrows workflow tracking to the documented `idle`, `checking`, `running`, `merging`, and `error` states reused by prompt-command gating, prompt-end orchestration, and status rendering. Compile-time only and introduces no runtime cost.
+ */
+export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging" | "error";
 
 /**
  * @brief Stores the mutable runtime facts displayed by the status bar.
- * @details Persists 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, 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;
   contextUsage: ContextUsage | undefined;
   runStartTimeMs: number | undefined;
   lastRunDurationMs: number | undefined;
@@ -130,6 +137,169 @@ export interface PiUsereqStatusController {
   tickHandle: ReturnType<typeof setInterval> | undefined;
 }
 
+/**
+ * @brief Stores the process-scoped elapsed-timer snapshot reused across session replacement.
+ * @details Preserves only the latest completed duration and accumulated completed runtime so `/new`, `/resume`, and `/fork` can restore elapsed counters after the extension runtime is rebound. Compile-time only and introduces no runtime cost.
+ */
+interface PiUsereqStatusPersistenceStore {
+  lastRunDurationMs: number | undefined;
+  totalRunDurationMs: number | undefined;
+}
+
+/**
+ * @brief Defines the global property name used for elapsed-timer persistence.
+ * @details The property lives on `globalThis` so prompt counters can survive extension-runtime replacement within the same pi process while remaining internal to pi-usereq. Access complexity is O(1).
+ */
+const PI_USEREQ_STATUS_PERSISTENCE_KEY = "__piUsereqStatusPersistenceStore";
+
+/**
+ * @brief Returns the process-scoped elapsed-timer persistence store.
+ * @details Lazily initializes one internal `globalThis` record because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, but the hosting process persists across those operations. Runtime is O(1). Side effect: initializes internal process-scoped state on first access.
+ * @return {PiUsereqStatusPersistenceStore} Mutable persistence record.
+ * @note Design rationale: required to preserve elapsed counters across session replacement without writing session-global menu state into project configuration.
+ */
+function getPiUsereqStatusPersistenceStore(): PiUsereqStatusPersistenceStore {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqStatusPersistenceStore?: PiUsereqStatusPersistenceStore;
+  };
+  globalState[PI_USEREQ_STATUS_PERSISTENCE_KEY] ??= {
+    lastRunDurationMs: undefined,
+    totalRunDurationMs: undefined,
+  };
+  return globalState[PI_USEREQ_STATUS_PERSISTENCE_KEY]!;
+}
+
+/**
+ * @brief Restores persisted elapsed counters into one mutable status snapshot.
+ * @details Copies the process-scoped last-run and accumulated completed durations into the supplied controller state so rebinding events can continue showing prior counters. Runtime is O(1). Side effect: mutates `state`.
+ * @param[in,out] state {PiUsereqStatusState} Mutable status state.
+ * @return {void} No return value.
+ */
+function restorePersistedElapsedState(state: PiUsereqStatusState): void {
+  const store = getPiUsereqStatusPersistenceStore();
+  state.lastRunDurationMs = store.lastRunDurationMs;
+  state.totalRunDurationMs = store.totalRunDurationMs;
+}
+
+/**
+ * @brief Persists elapsed counters from one mutable status snapshot.
+ * @details Copies the current last-run and accumulated completed durations into the process-scoped store so later extension instances can restore them after session replacement. Runtime is O(1). Side effect: mutates internal process-scoped state.
+ * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+ * @return {void} No return value.
+ */
+function persistElapsedState(state: PiUsereqStatusState): void {
+  const store = getPiUsereqStatusPersistenceStore();
+  store.lastRunDurationMs = state.lastRunDurationMs;
+  store.totalRunDurationMs = state.totalRunDurationMs;
+}
+
+/**
+ * @brief Mirrors one controller prompt state into the process-scoped persistence store.
+ * @details Persists the current workflow state plus the pending and active prompt execution plans so prompt orchestration can survive session replacement. Runtime is O(1). Side effect: mutates process-scoped prompt-command persistence state.
+ * @param[in] state {PiUsereqStatusState} Current controller state snapshot.
+ * @return {void} No return value.
+ */
+function persistPromptCommandState(state: PiUsereqStatusState): void {
+  writePersistedPromptCommandRuntimeState({
+    workflowState: state.workflowState,
+    pendingPromptRequest: state.pendingPromptRequest,
+    activePromptRequest: state.activePromptRequest,
+  });
+}
+
+/**
+ * @brief Detects whether `session_shutdown` must preserve prompt-command state.
+ * @details Keeps both the in-memory controller prompt state and the process-scoped prompt execution plan intact while pi switches from the original session into the forked execution session, because the old extension instance can keep running the initiating command handler after `session_shutdown` fires and before the replacement session fully takes over. Runtime is O(1). No external state is mutated.
+ * @param[in] state {PiUsereqStatusState} Controller state before shutdown mutation.
+ * @return {boolean} `true` when prompt-command state must survive the shutdown event.
+ * @satisfies REQ-278
+ */
+export function shouldPreservePromptCommandStateOnShutdown(state: PiUsereqStatusState): boolean {
+  return state.workflowState !== "idle"
+    && (state.pendingPromptRequest !== undefined || state.activePromptRequest !== undefined);
+}
+
+/**
+ * @brief Restores prompt-command persistence into one fresh controller when the active session matches.
+ * @details Rehydrates workflow state plus pending or active prompt execution plans only when the current session file targets the persisted execution session created for prompt orchestration. Runtime is O(1). Side effect: mutates `state` when persisted prompt state is available.
+ * @param[in,out] state {PiUsereqStatusState} Mutable controller state.
+ * @param[in] sessionFile {string | undefined} Current active session file.
+ * @return {void} No return value.
+ */
+function restorePersistedPromptCommandState(
+  state: PiUsereqStatusState,
+  sessionFile: string | undefined,
+): void {
+  const persistedState = restorePersistedPromptCommandRuntimeStateForSession(sessionFile);
+  if (persistedState === undefined) {
+    return;
+  }
+  state.workflowState = persistedState.workflowState;
+  state.pendingPromptRequest = persistedState.pendingPromptRequest;
+  state.activePromptRequest = persistedState.activePromptRequest;
+}
+
+/**
+ * @brief Resolves the active session file exposed by one extension context.
+ * @details Reads the session-manager session-file getter when available so prompt-command persistence can be resynchronized on every lifecycle hook after session replacement. Runtime is O(1). No external state is mutated.
+ * @param[in] ctx {ExtensionContext} Active extension context.
+ * @return {string | undefined} Current session file when available.
+ */
+function getContextSessionFile(ctx: ExtensionContext): string | undefined {
+  return typeof ctx.sessionManager?.getSessionFile === "function"
+    ? ctx.sessionManager.getSessionFile()
+    : undefined;
+}
+
+/**
+ * @brief Detects stale extension-context access after session replacement.
+ * @details Matches the guarded pi runtime error emitted when one invalidated extension context, command context, or replacement-session context is accessed after session replacement or reload. Runtime is O(n) in message length only when an error is supplied. No external state is mutated.
+ * @param[in] error {unknown} Candidate thrown value.
+ * @return {boolean} `true` when the value matches the stale-extension-context runtime error.
+ * @satisfies REQ-280
+ */
+export function isStaleExtensionContextError(error: unknown): boolean {
+  return error instanceof Error
+    && /stale after session replacement or reload/i.test(error.message);
+}
+
+/**
+ * @brief Resets the in-memory and persisted elapsed counters.
+ * @details Clears both completed-duration fields in the supplied state and mirrors that cleared snapshot into the process-scoped store. Runtime is O(1). Side effects include mutable state reset and process-scoped persistence update.
+ * @param[in,out] state {PiUsereqStatusState} Mutable status state.
+ * @return {void} No return value.
+ * @satisfies REQ-217
+ */
+function resetElapsedState(state: PiUsereqStatusState): void {
+  state.lastRunDurationMs = undefined;
+  state.totalRunDurationMs = undefined;
+  persistElapsedState(state);
+}
+
+/**
+ * @brief Detects whether a `session_start` event must reset elapsed counters.
+ * @details Treats `startup` and `reload` as hard-reset boundaries while preserving counters for `new`, `resume`, and `fork`. Runtime is O(1). No external state is mutated.
+ * @param[in] event {unknown} Session-start payload.
+ * @return {boolean} `true` when elapsed counters must reset.
+ * @satisfies REQ-217
+ */
+function shouldResetElapsedStateOnSessionStart(event: unknown): boolean {
+  const reason = (event as { reason?: unknown }).reason;
+  return reason === "startup" || reason === "reload";
+}
+
+/**
+ * @brief Detects whether a `session_start` event must reset the workflow state to `idle`.
+ * @details Treats `startup`, `new`, and `reload` as workflow-reset boundaries so prompt-orchestration state never leaks across boot, explicit session replacement, or extension reload. Runtime is O(1). No external state is mutated.
+ * @param[in] event {unknown} Session-start payload.
+ * @return {boolean} `true` when workflow state must reset to `idle`.
+ * @satisfies REQ-009, REQ-221
+ */
+function shouldResetWorkflowStateOnSessionStart(event: unknown): boolean {
+  const reason = (event as { reason?: unknown }).reason;
+  return reason === "startup" || reason === "new" || reason === "reload";
+}
+
 /**
  * @brief Builds the normalized theme adapter used by pi-usereq status formatters.
  * @details Precomputes label, value, foreground, and separator renderers so
@@ -149,6 +319,17 @@ function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter {
   };
 }
 
+/**
+ * @brief Resolves the active git branch value rendered in the status bar.
+ * @details Reads the current branch from the active context working directory on every status render so worktree switches and restored base-session renders expose the latest branch immediately. Runtime is dominated by git execution when the working directory belongs to a repository. Side effects include subprocess creation.
+ * @param[in] ctx {ExtensionContext} Active extension context.
+ * @return {string} Active branch name or `unknown` when unavailable.
+ * @satisfies REQ-121, REQ-283
+ */
+function resolveStatusBranchValue(ctx: ExtensionContext): string {
+  return resolveRuntimeGitBranchName(ctx.cwd);
+}
+
 /**
  * @brief Normalizes one raw context-usage snapshot.
  * @details Preserves the runtime token and context-window counts, derives a
@@ -196,12 +377,10 @@ function refreshContextUsage(
 
 /**
  * @brief Resolves the icon text for one normalized context-usage snapshot.
- * @details Maps context usage to one fixed-width icon band so footer rendering
- * remains compact and deterministic. Unavailable usage degrades to the `0%`
- * icon. Runtime is O(1). No external state is mutated.
+ * @details Maps context usage to one fixed-width icon band so footer rendering remains compact and deterministic across the documented `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands. Unavailable usage degrades to the `0%` icon. Runtime is O(1). No external state is mutated.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Fixed-width gauge icon text.
- * @satisfies REQ-121, REQ-122
+ * @satisfies REQ-122, REQ-284
  */
 function resolveContextUsageIconText(
   contextUsage: ContextUsage | undefined,
@@ -210,13 +389,13 @@ function resolveContextUsageIconText(
   if (percent === undefined || percent === null || percent <= 0) {
     return "▕_▏";
   }
-  if (percent <= 25) {
+  if (percent < 25) {
     return "▕▂▏";
   }
-  if (percent <= 50) {
+  if (percent < 50) {
     return "▕▄▏";
   }
-  if (percent <= 90) {
+  if (percent < 75) {
     return "▕▆▏";
   }
   return "▕█▏";
@@ -224,23 +403,24 @@ function resolveContextUsageIconText(
 
 /**
  * @brief Formats one icon-based context-usage gauge.
- * @details Renders the documented `warning`-colored icon bands for `0-100%` and
- * applies terminal blink control to the `error`-colored overflow icon so
- * unsupported terminals degrade to non-blinking red automatically. Runtime is
- * O(1). No external state is mutated.
+ * @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.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Rendered fixed-width gauge icon.
- * @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128
+ * @satisfies REQ-122, REQ-126, REQ-127, REQ-128, REQ-233, REQ-284
  */
 function formatContextUsageBar(
   theme: StatusThemeAdapter,
   contextUsage: ContextUsage | undefined,
 ): string {
-  if ((contextUsage?.percent ?? 0) > 100) {
+  const percent = contextUsage?.percent ?? 0;
+  if (percent >= 100) {
     return theme.colorize("error", "\u001b[5m▕█▏\u001b[25m");
   }
-  return theme.value(resolveContextUsageIconText(contextUsage));
+  if (percent >= 90) {
+    return theme.colorize("error", "▕█▏");
+  }
+  return resolveContextUsageIconText(contextUsage);
 }
 
 /**
@@ -332,6 +512,24 @@ function formatRenderedStatusField(
   return `${theme.label(fieldName)}${renderedValue}`;
 }
 
+/**
+ * @brief Formats the rendered workflow-state value for the `status` field.
+ * @details Uses the standard warning-colored value renderer for non-error states and emits a blinking `error`-colored value for `status:error` so the footer highlights orchestration failures immediately. Runtime is O(n) in text length. No external state is mutated.
+ * @param[in] theme {StatusThemeAdapter} Normalized status theme.
+ * @param[in] workflowState {PiUsereqWorkflowState} Current workflow state.
+ * @return {string} Rendered workflow-state value.
+ * @satisfies REQ-112, REQ-223
+ */
+function formatWorkflowStateValue(
+  theme: StatusThemeAdapter,
+  workflowState: PiUsereqWorkflowState,
+): string {
+  if (workflowState === "error") {
+    return theme.colorize("error", "\u001b[5merror\u001b[25m");
+  }
+  return theme.value(workflowState);
+}
+
 /**
  * @brief Detects whether an agent run ended through abort semantics.
  * @details Treats any assistant message whose `stopReason` equals `aborted` as
@@ -352,29 +550,31 @@ function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean {
 
 /**
  * @brief Builds the full single-line pi-usereq status-bar payload.
- * @details Renders base, context, elapsed, and sound fields in the canonical
- * order with dim bullet separators and the documented icon-based context gauge.
- * Runtime is O(1). No external state is mutated.
- * @param[in] cwd {string} Runtime working directory used for base-path derivation.
+ * @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.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+ * @param[in] branchName {string} Active git branch name shown in the footer.
  * @param[in] nowMs {number} Current wall-clock time in milliseconds.
  * @return {string} Single-line status-bar text.
- * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-148, REQ-156, REQ-159, REQ-180
+ * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223, REQ-233, REQ-283, REQ-284
  */
 function buildPiUsereqStatusText(
-  cwd: string,
   config: UseReqConfig,
   theme: StatusThemeAdapter,
   state: PiUsereqStatusState,
+  branchName: string,
   nowMs: number,
 ): string {
-  const baseText = normalizePathSlashes(path.resolve(cwd));
   const elapsedText = formatElapsedStatusValue(state, nowMs);
   const soundText = config["notify-sound"];
   return [
-    formatStatusField(theme, "base", baseText),
+    formatRenderedStatusField(
+      theme,
+      "status",
+      formatWorkflowStateValue(theme, state.workflowState),
+    ),
+    formatStatusField(theme, "branch", branchName),
     formatRenderedStatusField(
       theme,
       "context",
@@ -439,6 +639,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
     config: undefined,
     latestContext: undefined,
     state: {
+      workflowState: "idle",
       contextUsage: undefined,
       runStartTimeMs: undefined,
       lastRunDurationMs: undefined,
@@ -469,14 +670,11 @@ export function setPiUsereqStatusConfig(
 
 /**
  * @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
- * documented icon-based context gauge. Runtime is O(s) in configured source-
- * path count. Side effect: mutates `ctx.ui` status.
+ * @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.
  * @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-148, REQ-159, REQ-180
+ * @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
  */
 export function renderPiUsereqStatus(
   controller: PiUsereqStatusController,
@@ -486,33 +684,61 @@ export function renderPiUsereqStatus(
   if (!controller.config) {
     return;
   }
-  const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
-  ctx.ui.setStatus(
-    "pi-usereq",
-    buildPiUsereqStatusText(
-      ctx.cwd,
-      controller.config,
-      theme,
-      controller.state,
-      Date.now(),
-    ),
-  );
+  try {
+    const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
+    const branchName = resolveStatusBranchValue(ctx);
+    ctx.ui.setStatus(
+      "pi-usereq",
+      buildPiUsereqStatusText(
+        controller.config,
+        theme,
+        controller.state,
+        branchName,
+        Date.now(),
+      ),
+    );
+  } catch (error) {
+    if (isStaleExtensionContextError(error)) {
+      if (controller.latestContext === ctx) {
+        controller.latestContext = undefined;
+      }
+      return;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @brief Transitions the prompt-orchestration workflow state and refreshes the status bar.
+ * @details Mutates the tracked workflow state, preserves the latest extension context when available, and re-renders the single-line footer immediately so internal command transitions and pi lifecycle transitions stay visible to the user. Runtime is O(1). Side effect: mutates workflow state and may update `ctx.ui` status.
+ * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
+ * @param[in] workflowState {PiUsereqWorkflowState} Next workflow state.
+ * @param[in] ctx {ExtensionContext | undefined} Optional active extension context.
+ * @return {void} No return value.
+ * @satisfies REQ-221, REQ-222, REQ-223
+ */
+export function setPiUsereqWorkflowState(
+  controller: PiUsereqStatusController,
+  workflowState: PiUsereqWorkflowState,
+  ctx?: ExtensionContext,
+): void {
+  controller.state.workflowState = workflowState;
+  persistPromptCommandState(controller.state);
+  const renderContext = ctx ?? controller.latestContext;
+  if (renderContext) {
+    renderPiUsereqStatus(controller, renderContext);
+  }
 }
 
 /**
  * @brief Updates mutable status state for one intercepted lifecycle hook.
- * @details Refreshes stored context usage on every hook, 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 `Σ`, clears live timing on shutdown, 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, and
- * footer-status updates.
+ * @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.
  * @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-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169
+ * @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
  */
 export function updateExtensionStatus(
   controller: PiUsereqStatusController,
@@ -523,6 +749,28 @@ export function updateExtensionStatus(
   controller.latestContext = ctx;
   refreshContextUsage(controller.state, ctx);
   const nowMs = Date.now();
+  const currentSessionFile = getContextSessionFile(ctx);
+
+  if (hookName === "session_start") {
+    if (shouldResetElapsedStateOnSessionStart(event)) {
+      resetElapsedState(controller.state);
+    } else {
+      restorePersistedElapsedState(controller.state);
+    }
+    const shouldResetWorkflowState = shouldResetWorkflowStateOnSessionStart(event);
+    if (shouldResetWorkflowState) {
+      controller.state.workflowState = "idle";
+    }
+    controller.state.runStartTimeMs = undefined;
+    if (shouldResetWorkflowState || controller.state.workflowState === "idle") {
+      controller.state.pendingPromptRequest = undefined;
+      controller.state.activePromptRequest = undefined;
+    }
+  }
+
+  restorePersistedPromptCommandState(controller.state, currentSessionFile);
+  const preservePromptCommandStateOnShutdown = hookName === "session_shutdown"
+    && shouldPreservePromptCommandStateOnShutdown(controller.state);
 
   if (hookName === "agent_start") {
     controller.state.runStartTimeMs = nowMs;
@@ -543,10 +791,17 @@ export function updateExtensionStatus(
 
   if (hookName === "session_shutdown") {
     controller.state.runStartTimeMs = undefined;
-    controller.state.pendingPromptRequest = undefined;
-    controller.state.activePromptRequest = undefined;
+    if (!preservePromptCommandStateOnShutdown) {
+      controller.state.pendingPromptRequest = undefined;
+      controller.state.activePromptRequest = undefined;
+      controller.state.workflowState = "idle";
+    }
   }
 
+  persistElapsedState(controller.state);
+  if (!preservePromptCommandStateOnShutdown) {
+    persistPromptCommandState(controller.state);
+  }
   syncPiUsereqStatusTicker(controller);
   renderPiUsereqStatus(controller, ctx);
 }

package/src/core/find-constructs.ts

@@ -1,6 +1,6 @@
 /**
  * @file
- * @brief Finds named language constructs in explicit source-file lists and renders compact excerpts.
+ * @brief Searches named language constructs in explicit source-file lists and renders compact excerpts.
  * @details Combines source analysis, tag filtering, regex name matching, optional Doxygen extraction, and comment-stripped code rendering. Runtime is O(F + S + M) where F is file count, S is analyzed source size, and M is candidate element count. Side effects are limited to filesystem reads and optional stderr logging.
  */
 
@@ -240,7 +240,7 @@ export function formatConstruct(element: SourceElement, sourceLines: string[], i
 }
 
 /**
- * @brief Finds named constructs across explicit files and renders markdown excerpts.
+ * @brief Searches named constructs across explicit files and renders markdown excerpts.
  * @details Validates files, infers languages, skips unsupported tag/language combinations, analyzes source elements, filters matches by tag and regex, and emits one markdown section per file containing matches. Runtime is O(F + S + M). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] filePaths {string[]} Explicit file paths to search.
  * @param[in] tagFilter {string} Pipe-delimited requested construct tags.
@@ -250,7 +250,7 @@ export function formatConstruct(element: SourceElement, sourceLines: string[], i
  * @return {string} Concatenated markdown output grouped by file.
  * @throws {Error} Throws when no valid tags are provided or when no constructs match the request.
  */
-export function findConstructsInFiles(
+export function searchConstructsInFiles(
   filePaths: string[],
   tagFilter: string,
   pattern: string,