pi-usereq 0.6.0 → 0.10.0

package/src/core/extension-status.ts

@@ -8,7 +8,6 @@
  * scheduling through exported controller helpers.
  */
 
-import path from "node:path";
 import type {
   AgentEndEvent,
   ContextUsage,
@@ -16,8 +15,15 @@ import type {
   ThemeColor,
 } from "@mariozechner/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
-import { normalizePathSlashes } from "./path-context.js";
-import { formatPiNotifyBeepStatus, formatPiNotifyPushoverStatus } from "./pi-notify.js";
+import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
+import {
+  formatRuntimePathForDisplay,
+  getRuntimeContextPath,
+} from "./path-context.js";
+import {
+  restorePersistedPromptCommandRuntimeStateForSession,
+  writePersistedPromptCommandRuntimeState,
+} from "./prompt-command-state.js";
 
 /**
  * @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
@@ -32,42 +38,24 @@ type StatusForegroundColor = Extract<
 
 /**
  * @brief Describes the raw theme capabilities required for status rendering.
- * @details Accepts the `ctx.ui.theme` foreground renderer plus optional helpers
- * that can convert a foreground color into a background-styled fragment for the
- * context-usage bar. Compile-time only and introduces no runtime cost.
+ * @details Accepts the `ctx.ui.theme` foreground renderer used by the
+ * single-line footer. Compile-time only and introduces no runtime cost.
  */
 interface RawStatusTheme {
   fg: (color: StatusForegroundColor, text: string) => string;
-  bgFromFg?: (color: StatusForegroundColor, text: string) => string;
-  getFgAnsi?: (color: StatusForegroundColor) => string;
 }
 
 /**
  * @brief Describes the normalized theme adapter used by status formatters.
- * @details Exposes deterministic label, value, foreground, background, and
- * context-cell renderers so status text generation stays independent from the
- * raw theme API. Compile-time only and introduces no runtime cost.
+ * @details Exposes deterministic label, value, foreground, and separator
+ * renderers so status text generation stays independent from the raw theme API.
+ * Compile-time only and introduces no runtime cost.
  */
 interface StatusThemeAdapter {
   label: (fieldName: string) => string;
   value: (text: string) => string;
   colorize: (color: StatusForegroundColor, text: string) => string;
-  backgroundize: (color: StatusForegroundColor, text: string) => string;
   separator: string;
-  filledContextCell: string;
-  emptyContextCell: string;
-}
-
-/**
- * @brief Describes one fixed-width context-bar overlay.
- * @details Stores the literal text plus foreground and background color roles
- * used when the context bar must render threshold-specific labels instead of
- * block glyphs. Compile-time only and introduces no runtime cost.
- */
-interface ContextUsageOverlaySpec {
-  backgroundColor: StatusForegroundColor;
-  foregroundColor: StatusForegroundColor;
-  text: "◀ CLEAR ▶ " | " ◀ FULL ▶ ";
 }
 
 /**
@@ -115,18 +103,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;
@@ -150,89 +142,193 @@ export interface PiUsereqStatusController {
 }
 
 /**
- * @brief Converts a foreground ANSI sequence into the equivalent background ANSI.
- * @details Supports the standard `38;` foreground prefix emitted by pi themes.
- * Returns `undefined` when the input cannot be transformed deterministically.
- * Runtime is O(n) in ANSI sequence length. No external state is mutated.
- * @param[in] foregroundAnsi {string} Foreground ANSI sequence.
- * @return {string | undefined} Background ANSI sequence when derivable.
+ * @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.
  */
-function convertForegroundAnsiToBackgroundAnsi(
-  foregroundAnsi: string,
-): string | undefined {
-  if (!foregroundAnsi.includes("\u001b[")) {
-    return undefined;
-  }
-  const backgroundAnsi = foregroundAnsi.replace("[38;", "[48;");
-  return backgroundAnsi === foregroundAnsi ? undefined : backgroundAnsi;
+interface PiUsereqStatusPersistenceStore {
+  lastRunDurationMs: number | undefined;
+  totalRunDurationMs: number | undefined;
 }
 
 /**
- * @brief Applies a foreground-derived background style to one text fragment.
- * @details Prefers a theme-provided `bgFromFg` encoder for deterministic test
- * rendering and falls back to ANSI conversion when the runtime theme exposes
- * `getFgAnsi`. Runtime is O(n) in fragment length. No external state is
- * mutated.
- * @param[in] theme {RawStatusTheme} Raw theme adapter.
- * @param[in] color {StatusForegroundColor} Foreground color reused as background.
- * @param[in] text {string} Already-colored foreground fragment.
- * @return {string} Background-decorated text fragment.
- */
-function applyForegroundAsBackground(
-  theme: RawStatusTheme,
-  color: StatusForegroundColor,
-  text: string,
-): string {
-  if (typeof theme.bgFromFg === "function") {
-    return theme.bgFromFg(color, text);
-  }
-  if (typeof theme.getFgAnsi === "function") {
-    const backgroundAnsi = convertForegroundAnsiToBackgroundAnsi(
-      theme.getFgAnsi(color),
-    );
-    if (backgroundAnsi) {
-      return `${backgroundAnsi}${text}\u001b[39m\u001b[49m`;
-    }
+ * @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;
   }
-  return text;
+  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, background, separator, and
- * context-cell renderers so status formatting remains stable across real TUI
- * themes and deterministic test doubles. Runtime is O(1). No external state
- * is mutated.
+ * @details Precomputes label, value, foreground, and separator renderers so
+ * status formatting remains stable across real TUI themes and deterministic
+ * test doubles. Runtime is O(1). No external state is mutated.
  * @param[in] theme {RawStatusTheme} Raw theme implementation from `ctx.ui.theme`.
  * @return {StatusThemeAdapter} Normalized status-theme adapter.
  */
 function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter {
   const colorize = (color: StatusForegroundColor, text: string): string =>
     theme.fg(color, text);
-  const backgroundize = (color: StatusForegroundColor, text: string): string =>
-    applyForegroundAsBackground(theme, color, text);
   return {
     label: (fieldName: string): string => colorize("accent", `${fieldName}:`),
     value: (text: string): string => colorize("warning", text),
     colorize,
-    backgroundize,
     separator: colorize("dim", " • "),
-    filledContextCell: backgroundize(
-      "accent",
-      colorize("warning", "▓"),
-    ),
-    emptyContextCell: backgroundize(
-      "accent",
-      colorize("dim", "▓"),
-    ),
   };
 }
 
 /**
  * @brief Normalizes one raw context-usage snapshot.
  * @details Preserves the runtime token and context-window counts, derives a
- * percentage when the runtime omits it, and clamps percentages into `[0, 100]`.
- * Runtime is O(1). No external state is mutated.
+ * percentage when the runtime omits it, clamps negative percentages to `0`,
+ * and preserves overflow above `100` for footer rendering. Runtime is O(1). No
+ * external state is mutated.
  * @param[in] contextUsage {ContextUsage | undefined} Raw runtime snapshot.
  * @return {ContextUsage | undefined} Normalized snapshot.
  */
@@ -251,7 +347,7 @@ function normalizeContextUsage(
     ...contextUsage,
     percent: derivedPercent === null
       ? null
-      : Math.max(0, Math.min(100, derivedPercent)),
+      : Math.max(0, derivedPercent),
   };
 }
 
@@ -273,100 +369,53 @@ function refreshContextUsage(
 }
 
 /**
- * @brief Counts the filled cells rendered by the 10-cell context bar.
- * @details Uses ceiling semantics for positive percentages so any non-zero
- * usage occupies at least one cell and zero usage occupies none. Runtime is
- * O(1). No external state is mutated.
+ * @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.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
- * @return {number} Filled-cell count in the inclusive range `[0, 10]`.
- * @satisfies REQ-122
+ * @return {string} Fixed-width gauge icon text.
+ * @satisfies REQ-121, REQ-122
  */
-function countFilledContextCells(
+function resolveContextUsageIconText(
   contextUsage: ContextUsage | undefined,
-): number {
-  const percent = contextUsage?.percent;
-  if (percent === null || percent === undefined || percent <= 0) {
-    return 0;
-  }
-  return Math.min(10, Math.ceil((percent * 10) / 100));
-}
-
-/**
- * @brief Resolves the threshold-specific context-bar overlay when required.
- * @details Returns the empty-state `◀ CLEAR ▶ ` overlay when normalized context
- * usage is unavailable or non-positive and returns the centered ` ◀ FULL ▶ `
- * overlay with the active theme `error` token when usage exceeds 90 percent.
- * Runtime is O(1). No external state is mutated.
- * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
- * @return {ContextUsageOverlaySpec | undefined} Overlay spec when a replacement label is required.
- * @satisfies REQ-127, REQ-128
- */
-function resolveContextUsageOverlay(
-  contextUsage: ContextUsage | undefined,
-): ContextUsageOverlaySpec | undefined {
+): string {
   const percent = contextUsage?.percent;
   if (percent === undefined || percent === null || percent <= 0) {
-    return {
-      backgroundColor: "accent",
-      foregroundColor: "warning",
-      text: "◀ CLEAR ▶ ",
-    };
+    return "▕_▏";
   }
-  if (percent > 90) {
-    return {
-      backgroundColor: "warning",
-      foregroundColor: "error",
-      text: " ◀ FULL ▶ ",
-    };
+  if (percent <= 25) {
+    return "▕▂▏";
   }
-  return undefined;
-}
-
-/**
- * @brief Formats one threshold-specific context-bar overlay.
- * @details Renders the fixed-width overlay text with the requested foreground
- * color and reuses the selected bar color as the background so the bar width
- * and state-specific backdrop remain preserved. Runtime is O(n) in overlay
- * width. No external state is mutated.
- * @param[in] theme {StatusThemeAdapter} Normalized status theme.
- * @param[in] overlay {ContextUsageOverlaySpec} Overlay specification.
- * @return {string} Rendered overlay text.
- * @satisfies REQ-127, REQ-128
- */
-function formatContextUsageOverlay(
-  theme: StatusThemeAdapter,
-  overlay: ContextUsageOverlaySpec,
-): string {
-  return theme.backgroundize(
-    overlay.backgroundColor,
-    theme.colorize(overlay.foregroundColor, overlay.text),
-  );
+  if (percent <= 50) {
+    return "▕▄▏";
+  }
+  if (percent <= 90) {
+    return "▕▆▏";
+  }
+  return "▕█▏";
 }
 
 /**
- * @brief Formats one 10-cell context-usage bar.
- * @details Renders threshold-specific overlays for empty and high-water states;
- * otherwise renders filled cells with the theme `warning` token on an
- * accent-derived background and unfilled cells in `dim` on the same background
- * to preserve constant bar width. Runtime is O(1). No external state is
- * mutated.
+ * @brief Formats one icon-based context-usage gauge.
+ * @details Renders the documented `warning`-colored icon bands for `0-90%`, applies terminal blink control to the `warning`-colored `>90-100%` icon, and applies terminal blink control to the `error`-colored overflow icon so unsupported terminals degrade to non-blinking colored text automatically. 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 10-cell bar or overlay.
- * @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128
+ * @return {string} Rendered fixed-width gauge icon.
+ * @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128, REQ-233
  */
 function formatContextUsageBar(
   theme: StatusThemeAdapter,
   contextUsage: ContextUsage | undefined,
 ): string {
-  const overlay = resolveContextUsageOverlay(contextUsage);
-  if (overlay) {
-    return formatContextUsageOverlay(theme, overlay);
+  const percent = contextUsage?.percent ?? 0;
+  if (percent > 100) {
+    return theme.colorize("error", "\u001b[5m▕█▏\u001b[25m");
+  }
+  if (percent > 90) {
+    return theme.colorize("warning", "\u001b[5m▕█▏\u001b[25m");
   }
-  const filledCells = countFilledContextCells(contextUsage);
-  return Array.from({ length: 10 }, (_value, index) =>
-    index < filledCells ? theme.filledContextCell : theme.emptyContextCell,
-  ).join("");
+  return theme.value(resolveContextUsageIconText(contextUsage));
 }
 
 /**
@@ -404,7 +453,7 @@ function formatCompletedStatusDuration(
  * @brief Formats the consolidated `elapsed` status-bar value.
  * @details Emits the active prompt segment `⏱︎ <active>`, the latest normally
  * completed segment `⚑ <last>`, and the accumulated successful-runtime segment
- * `⌛︎ <total>` with fixed spacing. Runtime is O(1). No external state is
+ * `⌛︎<total>` with fixed spacing. Runtime is O(1). No external state is
  * mutated.
  * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
  * @param[in] nowMs {number} Current wall-clock time in milliseconds.
@@ -420,7 +469,7 @@ function formatElapsedStatusValue(
     : formatStatusDuration(nowMs - state.runStartTimeMs);
   const lastText = formatCompletedStatusDuration(state.lastRunDurationMs);
   const totalText = formatCompletedStatusDuration(state.totalRunDurationMs);
-  return ` ⏱︎ ${activeText} ⚑ ${lastText} ⌛︎ ${totalText}`;
+  return `⏱︎ ${activeText} ⚑ ${lastText} ⌛︎${totalText}`;
 }
 
 /**
@@ -458,6 +507,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
@@ -478,14 +545,14 @@ function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean {
 
 /**
  * @brief Builds the full single-line pi-usereq status-bar payload.
- * @details Renders base, context, elapsed, beep, sound, and pushover fields in the canonical order with dim bullet separators and threshold-specific context-bar overlays. Runtime is O(1). No external state is mutated.
- * @param[in] cwd {string} Runtime working directory used for base-path derivation.
+ * @details Renders status, current-path, 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] cwd {string} Runtime working directory used for context-path derivation.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
  * @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-135, REQ-136, REQ-148, REQ-156, REQ-159, REQ-170, REQ-171
+ * @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, REQ-222, REQ-223
  */
 function buildPiUsereqStatusText(
   cwd: string,
@@ -494,22 +561,23 @@ function buildPiUsereqStatusText(
   state: PiUsereqStatusState,
   nowMs: number,
 ): string {
-  const baseText = normalizePathSlashes(path.resolve(cwd));
+  const currentPathText = formatRuntimePathForDisplay(getRuntimeContextPath(cwd));
   const elapsedText = formatElapsedStatusValue(state, nowMs);
-  const beepText = formatPiNotifyBeepStatus(config);
   const soundText = config["notify-sound"];
-  const pushoverText = formatPiNotifyPushoverStatus(config);
   return [
-    formatStatusField(theme, "base", baseText),
+    formatRenderedStatusField(
+      theme,
+      "status",
+      formatWorkflowStateValue(theme, state.workflowState),
+    ),
+    formatStatusField(theme, "current-path", currentPathText),
     formatRenderedStatusField(
       theme,
       "context",
       formatContextUsageBar(theme, state.contextUsage),
     ),
     formatStatusField(theme, "elapsed", elapsedText),
-    formatStatusField(theme, "beep", beepText),
     formatStatusField(theme, "sound", soundText),
-    formatStatusField(theme, "pushover", pushoverText),
   ].join(theme.separator);
 }
 
@@ -567,6 +635,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
     config: undefined,
     latestContext: undefined,
     state: {
+      workflowState: "idle",
       contextUsage: undefined,
       runStartTimeMs: undefined,
       lastRunDurationMs: undefined,
@@ -597,14 +666,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 any
- * threshold-specific context-bar overlays. 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, deriving `current-path` from the active runtime context path aligned to `ctx.cwd` and including the 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(s) in configured source-path count. 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-135, REQ-136, REQ-148, REQ-159, REQ-170, REQ-171
+ * @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-148, REQ-159, REQ-180, REQ-280
  */
 export function renderPiUsereqStatus(
   controller: PiUsereqStatusController,
@@ -614,33 +680,60 @@ 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);
+    ctx.ui.setStatus(
+      "pi-usereq",
+      buildPiUsereqStatusText(
+        ctx.cwd,
+        controller.config,
+        theme,
+        controller.state,
+        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,
@@ -651,6 +744,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;
@@ -671,10 +786,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);
 }