pi-usereq 0.79.0 → 0.81.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.79.0)
+# PI-useReq/pi-usereq (0.81.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -335,6 +335,26 @@ The extension renders a status field in the pi status line showing: extension id
   pi -p "Rewrite this function" --append-system-prompt /tmp/PI-useReq/20261009072235123-req-implement
   ```
 
+- **Provider error logging** — when a dispatched `req-*` run receives a provider response with status >= 400, pi-usereq writes the exact failing request payload into `<timestamp>-<command>-error-<status>` (raw provider-request JSON), the provider error message text into `<timestamp>-<command>-error-<status>-response`, and replay metadata into `<timestamp>-<command>-error-<status>-replay.json`, all beside the run's `-request` and `-prompt` files. The `-replay.json` sidecar carries the provider, base URL, model id, thinking level, context window, max output tokens, the retained execution-session file, and ready-to-use replay commands. You can re-generate the failure for immediate pi CLI debugging:
+
+  ```bash
+  # Re-send the exact failing provider request (the payload file is raw request JSON)
+  curl -sS "$(jq -r '.replayCommands.provider' /tmp/PI-useReq/20261012070707447-req-analyze-error-400-replay.json)"
+
+  # Or replay it directly against the captured body
+  curl -sS https://openrouter.ai/api/v1/chat/completions \
+    -H "Authorization: Bearer $OPENROUTER_API_KEY" \
+    -H "Content-Type: application/json" \
+    --data @/tmp/PI-useReq/20261012070707447-req-analyze-error-400
+
+  # Replay the saved prompt through pi with the same model and thinking level
+  pi --no-session --model '~deepseek/deepseek-flash-latest' --thinking high \
+    -p "$(cat /tmp/PI-useReq/20261012070647580-req-analyze-prompt)"
+
+  # Fork the retained execution session (kept on failed runs) and continue it
+  pi --fork /home/ogekuri/.pi/agent/sessions/--home-ogekuri-Git-PI-useReq--/2026-10-12T05-06-46-788Z_01a12e81-9584-72f4-92e3-19008d04cccf.jsonl
+  ```
+
 
 ## Note on Git usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/debug-runtime.ts

@@ -831,45 +831,86 @@ export function logDebugPromptContent(
   promptName: PromptCommandName,
   content: string,
 ): boolean {
-  return writePromptDebugFile(
+  const fileName = formatPromptDebugPromptFileName(promptName);
+  const written = writePromptDebugFile(
     projectBase,
     config,
     workflowState,
     promptName,
-    formatPromptDebugPromptFileName(promptName),
+    fileName,
     content,
   );
+  if (written) {
+    getProcessScopedPromptErrorCaptureStore().dispatchedPromptDebugFiles.set(promptName, fileName);
+  }
+  return written;
+}
+
+/**
+ * @brief Describes replay facts captured beside one provider request payload for reproduction.
+ * @details Stores the provider, API, base URL, model identifier, thinking level, context-window, max-output-token, and execution-session-file facts resolved from the live pi runtime model plus prompt execution plan so the error-stage replay sidecar can emit ready-to-use replay command lines without live runtime state. Every field stays optional so degraded runtimes and offline replays never abort the capture. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-430
+ */
+export interface PromptErrorReplayFacts {
+  modelId: string | undefined;
+  provider: string | undefined;
+  api: string | undefined;
+  baseUrl: string | undefined;
+  thinkingLevel: string | undefined;
+  contextWindow: number | undefined;
+  maxTokens: number | undefined;
+  executionSessionFile: string | undefined;
 }
 
 /**
  * @brief Describes one process-scoped captured provider request payload bound to an active prompt run.
- * @details Pairs the bundled prompt name, the serialization of the exact `before_provider_request` payload, the original project base, and the resolved prompt log directory so a later `after_provider_response` error status can dump the failing request verbatim without live controller state, cached configuration, or live provider objects. The interface is compile-time only and introduces no runtime cost.
- * @satisfies REQ-421
+ * @details Pairs the bundled prompt name, the serialization of the exact `before_provider_request` payload, the original project base, the resolved prompt log directory, the dispatched prompt debug filename of the same run, and the captured replay facts so a later `after_provider_response` or `message_end` error status can dump the failing request verbatim, its provider error text, and one replay sidecar without live controller state, cached configuration, or live provider objects. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-421, REQ-429, REQ-430
  */
 interface CapturedPromptErrorPayload {
   promptName: PromptCommandName;
   payloadText: string;
   projectBase: string;
   logDirectory: string;
+  promptDebugFile: string | undefined;
+  replayFacts: PromptErrorReplayFacts;
+}
+
+/**
+ * @brief Describes the location of one already flushed provider error payload file set.
+ * @details Stores the prompt name, failing status, resolved log directory, and payload base filename of the most recent error-stage flush so a later finalized `message_end` error message can still append the `-response` file beside the already written payload when the provider fired `after_provider_response` before surfacing its error text. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-429
+ */
+interface FlushedPromptErrorRecord {
+  promptName: PromptCommandName;
+  errorCode: number;
+  logDirectory: string;
+  baseFileName: string;
 }
 
 /**
  * @brief Describes the process-scoped provider error payload capture state persisted across extension rebinds.
- * @details Stores the latest captured prompt error payload on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload` between prompt dispatch and provider execution, while the hosting process persists across those operations, so the capture survives the forked execution-session switch. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores the latest captured prompt error payload, the latest flushed error record, and the latest dispatched prompt debug filenames on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload` between prompt dispatch and provider execution, while the hosting process persists across those operations, so the capture, the late response write, and the dispatched-prompt correlation survive the forked execution-session switch. The interface is compile-time only and introduces no runtime cost.
  */
 interface ProcessScopedPromptErrorCaptureStore {
   capturedPromptErrorPayload: CapturedPromptErrorPayload | undefined;
+  lastFlushedPromptError: FlushedPromptErrorRecord | undefined;
+  dispatchedPromptDebugFiles: Map<PromptCommandName, string>;
 }
 
 /**
  * @brief Returns the process-scoped provider error payload capture store.
- * @details Lazily initializes one `globalThis` record so session rebinds never discard an already captured failing provider request. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @details Lazily initializes one `globalThis` record so session rebinds never discard an already captured failing provider request, its flushed error record, or its dispatched prompt debug filename correlation. Runtime is O(1). Side effect: initializes process-scoped state on first access.
  * @return {ProcessScopedPromptErrorCaptureStore} Mutable process-scoped capture store.
  */
 function getProcessScopedPromptErrorCaptureStore(): ProcessScopedPromptErrorCaptureStore {
   const globalScope = globalThis as typeof globalThis & { __piUsereqPromptErrorCaptureStore?: ProcessScopedPromptErrorCaptureStore };
   if (!globalScope.__piUsereqPromptErrorCaptureStore) {
-    globalScope.__piUsereqPromptErrorCaptureStore = { capturedPromptErrorPayload: undefined };
+    globalScope.__piUsereqPromptErrorCaptureStore = {
+      capturedPromptErrorPayload: undefined,
+      lastFlushedPromptError: undefined,
+      dispatchedPromptDebugFiles: new Map(),
+    };
   }
   return globalScope.__piUsereqPromptErrorCaptureStore;
 }
@@ -891,6 +932,40 @@ export function formatPromptDebugErrorFileName(
   return `${formatPromptDebugTimestamp(date)}-${getDebugPromptName(promptName)}-error-${errorCode}`;
 }
 
+/**
+ * @brief Builds one provider error response debug filename for one bundled prompt.
+ * @details Appends the `-response` suffix to the shared `<timestamp>-<req-command>-error-<status>` shape so the persisted provider error text stays attributable to the exact failing request payload file written with the identical write-time timestamp. Runtime is O(1). No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] errorCode {number} Failing provider response status, such as `400`.
+ * @param[in] date {Date} Write-time timestamp shared with the payload file. Defaults to the current wall-clock time.
+ * @return {string} Provider error response filename in the `<timestamp>-<req-command>-error-<status>-response` shape.
+ * @satisfies REQ-423, REQ-429
+ */
+export function formatPromptDebugErrorResponseFileName(
+  promptName: PromptCommandName,
+  errorCode: number,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugErrorFileName(promptName, errorCode, date)}-response`;
+}
+
+/**
+ * @brief Builds one provider error replay sidecar debug filename for one bundled prompt.
+ * @details Appends the `-replay.json` suffix to the shared `<timestamp>-<req-command>-error-<status>` shape so the persisted replay metadata sidecar stays attributable to the exact failing request payload file written with the identical write-time timestamp. Runtime is O(1). No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] errorCode {number} Failing provider response status, such as `400`.
+ * @param[in] date {Date} Write-time timestamp shared with the payload file. Defaults to the current wall-clock time.
+ * @return {string} Provider error replay sidecar filename in the `<timestamp>-<req-command>-error-<status>-replay.json` shape.
+ * @satisfies REQ-423, REQ-430
+ */
+export function formatPromptDebugErrorReplayFileName(
+  promptName: PromptCommandName,
+  errorCode: number,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugErrorFileName(promptName, errorCode, date)}-replay.json`;
+}
+
 /**
  * @brief Resolves the failing HTTP status carried by one finalized agent message.
  * @details Extracts the leading provider error status from one `message_end` assistant message whose `stopReason` equals `error`, accepting the pi `formatProviderError` display shapes (`"<status>: <body>"` and `"<prefix> (<status>): <body>"`) plus the raw SDK `error.message` shape (`"<status> <body>"`) surfaced unchanged by the agent run-failure path, so provider APIs whose SDK clients throw before emitting `after_provider_response` for non-2xx statuses (the OpenAI-compatible family, including `zai`) still flush the captured provider request payload through the message lifecycle channel. Runtime is O(n) in the inspected error-message prefix length. No external state is mutated.
@@ -946,54 +1021,230 @@ function serializePromptProviderPayload(payload: unknown): string {
   ) ?? "";
 }
 
+/**
+ * @brief Resolves the model identifier embedded in one provider request payload.
+ * @details Reads the string `model` field of the serialized request payload so the replay sidecar can still name the failing model when the live runtime model object was unavailable at capture time. Runtime is O(1). No external state is mutated.
+ * @param[in] payload {unknown} Exact `before_provider_request` provider request payload.
+ * @return {string | undefined} Payload model identifier when present as a string; otherwise `undefined`.
+ */
+function resolveProviderPayloadModelId(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+  const modelId = (payload as { model?: unknown }).model;
+  return typeof modelId === "string" && modelId.length > 0 ? modelId : undefined;
+}
+
 /**
  * @brief Captures one exact provider request payload for the active prompt run when prompt debug logging is enabled.
- * @details Applies the global-debug plus prompt-debug gating, serializes the exact `before_provider_request` payload through the cycle-safe serializer, and stores the prompt name, payload text, original project base, and resolved prompt log directory in the process-scoped capture store so the payload survives session replacement and later error-stage writes require no live workflow state or cached configuration. Runtime is O(n) in serialized payload size when enabled and O(1) otherwise. Side effect: mutates the process-scoped capture store for enabled matching requests.
+ * @details Applies the global-debug plus prompt-debug gating, serializes the exact `before_provider_request` payload through the cycle-safe serializer, resolves the dispatched prompt debug filename of the same run from the process-scoped correlation map, and stores the prompt name, payload text, original project base, resolved prompt log directory, replay facts, and prompt debug filename in the process-scoped capture store so the payload, its error text, and its replay sidecar survive session replacement and later error-stage writes require no live workflow state or cached configuration. Falls back to the payload `model` field when the supplied replay facts omit the model identifier. Runtime is O(n) in serialized payload size when enabled and O(1) otherwise. Side effect: mutates the process-scoped capture store for enabled matching requests.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] promptName {PromptCommandName} Active bundled prompt name.
  * @param[in] projectBase {string} Absolute original project base path used to resolve the prompt log directory.
  * @param[in] payload {unknown} Exact `before_provider_request` provider request payload.
+ * @param[in] replayFacts {PromptErrorReplayFacts} Live runtime replay facts consumed by the error-stage sidecar. Defaults to empty facts.
  * @return {void} No return value.
- * @satisfies REQ-416, REQ-421
+ * @satisfies REQ-416, REQ-421, REQ-430
  */
 export function capturePromptProviderRequestForDebug(
   config: UseReqConfig,
   promptName: PromptCommandName,
   projectBase: string,
   payload: unknown,
+  replayFacts: PromptErrorReplayFacts = {
+    modelId: undefined,
+    provider: undefined,
+    api: undefined,
+    baseUrl: undefined,
+    thinkingLevel: undefined,
+    contextWindow: undefined,
+    maxTokens: undefined,
+    executionSessionFile: undefined,
+  },
 ): void {
   if (!shouldLogDebugPromptContent(config, "unknown", promptName)) {
     return;
   }
+  const logDirectory = resolveDebugPromptsLogPath(projectBase, config);
+  const dispatchedPromptFile = getProcessScopedPromptErrorCaptureStore().dispatchedPromptDebugFiles.get(promptName);
   getProcessScopedPromptErrorCaptureStore().capturedPromptErrorPayload = {
     promptName,
     payloadText: serializePromptProviderPayload(payload),
     projectBase,
-    logDirectory: resolveDebugPromptsLogPath(projectBase, config),
+    logDirectory,
+    promptDebugFile: dispatchedPromptFile === undefined ? undefined : path.join(logDirectory, dispatchedPromptFile),
+    replayFacts: {
+      ...replayFacts,
+      modelId: replayFacts.modelId ?? resolveProviderPayloadModelId(payload),
+    },
   };
 }
 
 /**
- * @brief Writes the captured provider request payload as one error-stage prompt debug file for the failing prompt.
- * @details Consumes the process-scoped capture, discards it after every write attempt so stale payloads never reach later runs, rejects failing statuses below 400, and writes the exact captured payload into one `<timestamp>-<req-command>-error-<status>` file inside the captured log directory beside the initial dispatched prompt artifacts. All write inputs come from the capture itself, so the flush requires no live workflow state, cached configuration, or active controller prompt request. Runtime is dominated by one directory creation plus one file write when a capture exists and O(1) otherwise. Side effects include directory creation and file creation only when a capture exists and the status is an error status.
+ * @brief Normalizes one provider name into an uppercase environment-variable token.
+ * @details Uppercases the provider name and replaces every non-alphanumeric character with `_` so the generated replay command can reference a deterministic `<PROVIDER>_API_KEY` environment variable. Runtime is O(n) in provider-name length. No external state is mutated.
+ * @param[in] provider {string} Provider identifier, such as `openrouter`.
+ * @return {string} Uppercase alphanumeric environment-variable token.
+ */
+function normalizeProviderEnvToken(provider: string): string {
+  const normalized = provider.toUpperCase().replace(/[^A-Z0-9]/gu, "_");
+  return normalized.length > 0 ? normalized : "PROVIDER";
+}
+
+/**
+ * @brief Resolves the provider HTTP endpoint targeted by one captured provider request payload.
+ * @details Appends the canonical chat-completions path for `openai-completions` APIs and the canonical messages path for `anthropic-messages` APIs, and preserves the raw base URL for every other API so the generated provider replay command never fabricates an endpoint it cannot derive. Runtime is O(p) in URL length. No external state is mutated.
+ * @param[in] facts {PromptErrorReplayFacts} Captured replay facts supplying the API and base URL.
+ * @return {string | undefined} Replay endpoint URL when a base URL exists; otherwise `undefined`.
+ */
+function resolveProviderReplayEndpoint(facts: PromptErrorReplayFacts): string | undefined {
+  if (facts.baseUrl === undefined) {
+    return undefined;
+  }
+  if (facts.api === "openai-completions") {
+    return `${facts.baseUrl}/chat/completions`;
+  }
+  if (facts.api === "anthropic-messages") {
+    return `${facts.baseUrl}/v1/messages`;
+  }
+  return facts.baseUrl;
+}
+
+/**
+ * @brief Builds the replay sidecar JSON text for one flushed provider error payload.
+ * @details Serializes the captured provider, base URL, API, model identifier, thinking level, context-window and max-output-token facts, the execution-session file, the dispatched prompt debug file, the flushed request payload file, and ready-to-use replay command lines: one `curl --data @` provider replay of the exact failing request, one pi one-shot replay of the dispatched prompt file, and one `pi --fork` replay of the retained execution session. Command lines are emitted only when their supporting facts exist so every emitted command is directly executable. Runtime is O(n) in serialized sidecar size. No external state is mutated.
+ * @param[in] captured {CapturedPromptErrorPayload} Consumed capture supplying replay facts and artifact paths.
+ * @param[in] requestFileName {string} Payload filename written with the same write-time timestamp.
+ * @return {string} Newline-terminated replay sidecar JSON text.
+ * @satisfies REQ-430
+ */
+function buildPromptErrorReplaySidecarText(
+  captured: CapturedPromptErrorPayload,
+  requestFileName: string,
+): string {
+  const facts = captured.replayFacts;
+  const requestFilePath = path.join(captured.logDirectory, requestFileName);
+  const endpoint = resolveProviderReplayEndpoint(facts);
+  const replayCommands: Record<string, string> = {};
+  if (endpoint !== undefined) {
+    const envToken = facts.provider === undefined ? "PROVIDER_API_KEY" : `${normalizeProviderEnvToken(facts.provider)}_API_KEY`;
+    replayCommands.provider = `curl -sS '${endpoint}' -H 'Authorization: Bearer $${envToken}' -H 'Content-Type: application/json' --data @'${requestFilePath}'`;
+  }
+  if (captured.promptDebugFile !== undefined && facts.modelId !== undefined) {
+    replayCommands.piOneShot = `pi --no-session --model '${facts.modelId}' --thinking ${facts.thinkingLevel ?? "off"} -p "$(cat '${captured.promptDebugFile}')"`;
+  }
+  if (facts.executionSessionFile !== undefined) {
+    const modelFlags = facts.modelId === undefined ? "" : ` --model '${facts.modelId}'`;
+    const thinkingFlags = facts.thinkingLevel === undefined ? "" : ` --thinking ${facts.thinkingLevel}`;
+    replayCommands.piFork = `pi --fork '${facts.executionSessionFile}'${modelFlags}${thinkingFlags}`;
+  }
+  const sidecar = {
+    provider: facts.provider ?? null,
+    baseUrl: facts.baseUrl ?? null,
+    api: facts.api ?? null,
+    modelId: facts.modelId ?? null,
+    thinkingLevel: facts.thinkingLevel ?? null,
+    contextWindow: facts.contextWindow ?? null,
+    maxTokens: facts.maxTokens ?? null,
+    sessionFile: facts.executionSessionFile ?? null,
+    promptFile: captured.promptDebugFile ?? null,
+    requestFile: requestFilePath,
+    replayCommands,
+  };
+  return `${JSON.stringify(sidecar, null, 2)}\n`;
+}
+
+/**
+ * @brief Writes the captured provider request payload plus its response text and replay sidecar as error-stage prompt debug files.
+ * @details Consumes the process-scoped capture, discards it after every write attempt so stale payloads never reach later runs, rejects failing statuses below 400, and writes the exact captured payload into one `<timestamp>-<req-command>-error-<status>` file that stays raw provider-request JSON usable with `curl --data @`, the provider error text into one identically timestamped `-response` file when supplied, and the replay sidecar into one identically timestamped `-replay.json` file inside the captured log directory beside the initial dispatched prompt artifacts. Records the flushed location so a later finalized `message_end` error message can still append the `-response` file when `after_provider_response` fired first without error text. All write inputs come from the capture itself, so the flush requires no live workflow state, cached configuration, or active controller prompt request. Runtime is dominated by one directory creation plus at most three file writes when a capture exists and O(1) otherwise. Side effects include directory creation and file creation only when a capture exists and the status is an error status.
  * @param[in] errorCode {number} Failing provider response status, such as `400`.
- * @return {boolean} `true` when the provider error payload file is written; otherwise `false`.
- * @satisfies REQ-422, REQ-423, REQ-424, REQ-425
+ * @param[in] errorResponseText {string | undefined} Finalized provider error message text when already available; the `-response` file is written later when omitted.
+ * @return {boolean} `true` when the provider error payload file set is written; otherwise `false`.
+ * @satisfies REQ-422, REQ-423, REQ-424, REQ-425, REQ-429, REQ-430, REQ-431
  */
-export function flushCapturedPromptErrorPayload(errorCode: number): boolean {
+export function flushCapturedPromptErrorPayload(errorCode: number, errorResponseText?: string): boolean {
   const captureStore = getProcessScopedPromptErrorCaptureStore();
   const captured = captureStore.capturedPromptErrorPayload;
   captureStore.capturedPromptErrorPayload = undefined;
   if (!captured || !Number.isFinite(errorCode) || errorCode < 400) {
     return false;
   }
+  const writeTime = new Date();
+  const payloadFileName = formatPromptDebugErrorFileName(captured.promptName, errorCode, writeTime);
   try {
     fs.mkdirSync(captured.logDirectory, { recursive: true });
     fs.writeFileSync(
-      path.join(captured.logDirectory, formatPromptDebugErrorFileName(captured.promptName, errorCode)),
+      path.join(captured.logDirectory, payloadFileName),
       captured.payloadText,
       "utf8",
     );
+    if (typeof errorResponseText === "string" && errorResponseText.length > 0) {
+      writePromptProviderErrorResponseFile(
+        captured.logDirectory,
+        formatPromptDebugErrorResponseFileName(captured.promptName, errorCode, writeTime),
+        errorResponseText,
+      );
+    }
+    fs.writeFileSync(
+      path.join(captured.logDirectory, formatPromptDebugErrorReplayFileName(captured.promptName, errorCode, writeTime)),
+      buildPromptErrorReplaySidecarText(captured, payloadFileName),
+      "utf8",
+    );
+    captureStore.lastFlushedPromptError = {
+      promptName: captured.promptName,
+      errorCode,
+      logDirectory: captured.logDirectory,
+      baseFileName: payloadFileName,
+    };
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @brief Writes one provider error response text file under a resolved log directory.
+ * @details Creates the parent directory and writes the finalized provider error text with one trailing newline into the requested response filename so both the flush-time and the late `message_end` response writes share one deterministic serialization. Runtime is dominated by one directory creation plus one file write. Side effects include directory creation and file creation.
+ * @param[in] logDirectory {string} Absolute prompt log directory owning the response file.
+ * @param[in] fileName {string} Target response filename under the log directory.
+ * @param[in] errorResponseText {string} Finalized provider error message text.
+ * @return {void} No return value.
+ * @satisfies REQ-429
+ */
+function writePromptProviderErrorResponseFile(
+  logDirectory: string,
+  fileName: string,
+  errorResponseText: string,
+): void {
+  fs.mkdirSync(logDirectory, { recursive: true });
+  fs.writeFileSync(path.join(logDirectory, fileName), `${errorResponseText}\n`, "utf8");
+}
+
+/**
+ * @brief Appends the provider error response text beside one already flushed error payload file.
+ * @details Providers that fire `after_provider_response` before surfacing their error text flush the payload without a `-response` file, so this helper writes the finalized `message_end` error message beside the recorded flush location when the failing status matches. Runtime is dominated by one directory creation plus one file write when a matching record exists and O(1) otherwise. Side effects include directory creation and file creation only for a matching record.
+ * @param[in] errorCode {number} Failing provider response status carried by the finalized error message.
+ * @param[in] errorResponseText {string} Finalized provider error message text.
+ * @return {boolean} `true` when the response file is written; otherwise `false`.
+ * @satisfies REQ-429
+ */
+export function writeFlushedPromptProviderErrorResponse(
+  errorCode: number,
+  errorResponseText: string,
+): boolean {
+  if (typeof errorResponseText !== "string" || errorResponseText.length === 0) {
+    return false;
+  }
+  const record = getProcessScopedPromptErrorCaptureStore().lastFlushedPromptError;
+  if (record === undefined || record.errorCode !== errorCode) {
+    return false;
+  }
+  try {
+    writePromptProviderErrorResponseFile(
+      record.logDirectory,
+      `${record.baseFileName}-response`,
+      errorResponseText,
+    );
     return true;
   } catch {
     return false;
@@ -1001,11 +1252,13 @@ export function flushCapturedPromptErrorPayload(errorCode: number): boolean {
 }
 
 /**
- * @brief Discards any captured provider request payload for the ended prompt run.
- * @details Clears the process-scoped capture unconditionally so leftover payloads from a finished `req-*` prompt run never flush into later provider errors raised outside extension-owned prompt orchestration. Runtime is O(1). Side effect: mutates the process-scoped capture store.
+ * @brief Discards any captured provider request payload and flushed error record for the ended prompt run.
+ * @details Clears the process-scoped capture and the latest flushed error record unconditionally so leftover payloads and flush locations from a finished `req-*` prompt run never flush into later provider errors raised outside extension-owned prompt orchestration. Runtime is O(1). Side effect: mutates the process-scoped capture store.
  * @return {void} No return value.
- * @satisfies REQ-421, REQ-425
+ * @satisfies REQ-421, REQ-425, REQ-429
  */
 export function discardCapturedPromptErrorPayload(): void {
-  getProcessScopedPromptErrorCaptureStore().capturedPromptErrorPayload = undefined;
+  const captureStore = getProcessScopedPromptErrorCaptureStore();
+  captureStore.capturedPromptErrorPayload = undefined;
+  captureStore.lastFlushedPromptError = undefined;
 }

package/src/index.ts

@@ -153,8 +153,10 @@ import {
   resolveProviderErrorFlushStatusFromMessage,
   setRuntimeDebugEnabled,
   shouldLogDebugPromptWorkflowState,
+  writeFlushedPromptProviderErrorResponse,
   type DebugLogOnStatus,
   type DebugWorkflowState,
+  type PromptErrorReplayFacts,
 } from "./core/debug-runtime.js";
 import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
@@ -294,6 +296,42 @@ function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void {
   }
 }
 
+/**
+ * @brief Loads the effective configuration anchored at one exact prompt-run project base.
+ * @details Reads the split local and global configuration scoped to the supplied absolute `projectBase` without consulting the shared runtime path state, because during worktree-backed prompt runs the runtime `base-path` resolves to the execution checkout whose untracked `.pi-usereq.json` is absent while the prompt debug gating configuration lives at the original project base that also produced the `-request` and `-prompt` debug files. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
+ * @param[in] projectBase {string} Absolute original project base path recorded in the prompt execution plan.
+ * @return {UseReqConfig} Effective configuration anchored at the exact supplied project base.
+ * @satisfies REQ-416, REQ-421
+ */
+function loadPromptRunBaseConfig(projectBase: string): UseReqConfig {
+  return normalizeConfigPaths(projectBase, loadConfig(projectBase));
+}
+
+/**
+ * @brief Builds the replay facts captured beside one provider request payload.
+ * @details Reads the provider, API, base URL, model identifier, thinking level, context-window, and max-output-token facts from the live extension-context model plus the execution-session file from the live prompt execution plan so the error-stage replay sidecar can emit ready-to-use `curl` and `pi` replay command lines without live runtime state at flush time. Degrades every fact to `undefined` when the runtime model is unavailable so the capture never aborts. Runtime is O(1). No external state is mutated.
+ * @param[in] ctx {ExtensionContext} Active extension context supplying the live model and thinking level.
+ * @param[in] executionSessionFile {string | undefined} Persisted execution-session file of the active prompt run retained per REQ-209.
+ * @return {PromptErrorReplayFacts} Replay facts consumed by the error-stage sidecar writer.
+ * @satisfies REQ-430
+ */
+function buildPromptProviderReplayFacts(
+  ctx: ExtensionContext,
+  executionSessionFile: string | undefined,
+): PromptErrorReplayFacts {
+  const model = ctx.model;
+  return {
+    modelId: model?.id,
+    provider: model?.provider,
+    api: model?.api,
+    baseUrl: model?.baseUrl,
+    thinkingLevel: ctx.thinkingLevel,
+    contextWindow: model?.contextWindow,
+    maxTokens: model?.maxTokens,
+    executionSessionFile,
+  };
+}
+
 /**
  * @brief Loads project configuration for the extension runtime.
  * @details Resolves the project base, loads persisted config, and normalizes configured directory paths without reading or persisting runtime-derived `base-path` or `git-path` metadata. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
@@ -1449,7 +1487,7 @@ async function finalizeMatchedPromptSuccess(
 
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, idle-time shared-tokenizer and context-file measurement pre-warm, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. After the status update, captures the exact `before_provider_request` provider payload for the live active or pending prompt run with a fresh config fallback when the controller has no cached config, flushes the process-scoped captured payload as one `<timestamp>-<req-command>-error-<status>` file whenever `after_provider_response` reports a status >= 400 or whenever one finalized `message_end` assistant error message carries a leading HTTP status >= 400 (the provider-independent fallback for provider APIs whose SDK clients throw before emitting `after_provider_response` for non-2xx statuses) without requiring live workflow state, and discards the capture at prompt-run end so stale payloads never reach later runs. 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, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, 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 closure 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, idle-time shared-tokenizer and context-file measurement pre-warm, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. After the status update, captures the exact `before_provider_request` provider payload for the live active or pending prompt run by reloading the prompt debug gating configuration from the prompt run's original `base-path` (worktree-backed checkouts do not contain the untracked `.pi-usereq.json`, so the cwd-derived cached config would silently disable capture), flushes the process-scoped captured payload as one `<timestamp>-<req-command>-error-<status>` file whenever `after_provider_response` reports a status >= 400 or whenever one finalized `message_end` assistant error message carries a leading HTTP status >= 400 (the provider-independent fallback for provider APIs whose SDK clients throw before emitting `after_provider_response` for non-2xx statuses) without requiring live workflow state, and discards the capture at prompt-run end so stale payloads never reach later runs. 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, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, 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 closure 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.
@@ -1524,16 +1562,25 @@ async function handleExtensionStatusEvent(
     ?? statusController.state.pendingPromptRequest;
   if (hookName === "before_provider_request" && livePromptRequest !== undefined) {
     const providerRequestEvent = event as { payload?: unknown };
+    // The capture gate MUST resolve its gating configuration from the prompt run's ORIGINAL
+    // project base: worktree-backed runs execute in a checkout whose untracked
+    // `.pi-usereq.json` is absent, so the cwd-derived cached config silently reverts to
+    // `DEBUG_PROMPTS_ENABLED=disable` defaults and would skip the REQ-421 capture even though
+    // the base configuration already wrote the `-request` and `-prompt` debug files.
     capturePromptProviderRequestForDebug(
-      statusController.config ?? loadProjectConfig(resolveLiveBootstrapCwd(ctx.cwd)),
+      loadPromptRunBaseConfig(livePromptRequest.basePath),
       livePromptRequest.promptName,
       livePromptRequest.basePath,
       providerRequestEvent.payload,
+      buildPromptProviderReplayFacts(ctx, livePromptRequest.executionSessionFile),
     );
   }
   if (hookName === "after_provider_response") {
     const providerResponseEvent = event as { status?: unknown };
     if (typeof providerResponseEvent.status === "number" && providerResponseEvent.status >= 400) {
+      // The response event carries status plus headers only, so the provider error text is
+      // appended later by the finalized `message_end` error message through the recorded
+      // flush location.
       flushCapturedPromptErrorPayload(providerResponseEvent.status);
     }
   }
@@ -1544,11 +1591,17 @@ async function handleExtensionStatusEvent(
   // `message_end` for every failed provider request with the HTTP status embedded in
   // `errorMessage` by `formatProviderError`.
   if (hookName === "message_end") {
-    const providerErrorStatus = resolveProviderErrorFlushStatusFromMessage(
-      (event as { message?: unknown }).message,
-    );
+    const finalizedMessage = (event as { message?: unknown }).message as { errorMessage?: unknown } | undefined;
+    const providerErrorStatus = resolveProviderErrorFlushStatusFromMessage(finalizedMessage);
     if (providerErrorStatus !== undefined) {
-      flushCapturedPromptErrorPayload(providerErrorStatus);
+      const providerErrorText = typeof finalizedMessage?.errorMessage === "string"
+        ? finalizedMessage.errorMessage
+        : undefined;
+      if (!flushCapturedPromptErrorPayload(providerErrorStatus, providerErrorText)) {
+        // The capture was already flushed by `after_provider_response`, so the finalized error
+        // text is appended beside the recorded payload location.
+        writeFlushedPromptProviderErrorResponse(providerErrorStatus, providerErrorText ?? "");
+      }
     }
   }
   if (hookName === "agent_end" || hookName === "agent_settled") {