pi-usereq 0.75.0 → 0.77.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.75.0)
+# PI-useReq/pi-usereq (0.77.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+">

package/package.json

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

package/src/core/config.ts

@@ -32,7 +32,6 @@ import {
   normalizePiNotifyTemplateValue,
 } from "./pi-notify.js";
 import {
-  DEFAULT_DEBUG_ENABLED,
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
   DEFAULT_DEBUG_PROMPTS_ENABLED,
@@ -40,7 +39,7 @@ import {
   DEFAULT_DEBUG_STATUS_CHANGES,
   DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
-  normalizeDebugEnabled,
+  getRuntimeDebugEnabled,
   normalizeDebugEnabledPrompts,
   normalizeDebugEnabledTools,
   normalizeDebugLogFile,
@@ -149,7 +148,8 @@ interface GlobalStaticCheckLanguageConfig {
 
 /**
  * @brief Defines the persisted local pi-usereq configuration schema.
- * @details Captures project-scoped directory, debug, and static-check enablement fields written to `<base-path>/.pi-usereq.json` while excluding global notification, tool, git, and checker-command settings. The interface is compile-time only and introduces no runtime side effects.
+ * @details Captures project-scoped directory, debug, and static-check enablement fields written to `<base-path>/.pi-usereq.json` while excluding the runtime-only `DEBUG_ENABLED` flag and global notification, tool, git, and checker-command settings. The interface is compile-time only and introduces no runtime side effects.
+ * @satisfies REQ-426
  */
 interface UseReqLocalConfig {
   "docs-dir": string;
@@ -159,7 +159,6 @@ interface UseReqLocalConfig {
   "context-files-references": boolean;
   "context-files-workflow": boolean;
   "static-check": Record<string, LocalStaticCheckLanguageConfig>;
-  DEBUG_ENABLED: "enable" | "disable";
   DEBUG_LOG_FILE: string;
   DEBUG_PROMPTS_ENABLED: DebugPromptsEnabled;
   DEBUG_PROMPTS_LOG_PATH: string;
@@ -587,7 +586,7 @@ export function getGlobalConfigPath(): string {
  * @details Populates canonical docs/test/source directories, derives local static-check enable defaults from the supplied global checker definitions, and seeds documented debug defaults including tool-wrapper command registration without any cross-project fields. Runtime is O(l). No filesystem side effects occur.
  * @param[in] globalStaticCheckConfig {Record<string, GlobalStaticCheckLanguageConfig>} Global checker definitions used to derive local enable defaults.
  * @return {UseReqLocalConfig} Fresh default local configuration object.
- * @satisfies CTN-019, REQ-328, REQ-413, REQ-414
+ * @satisfies CTN-013, CTN-019, REQ-328, REQ-413, REQ-414, REQ-426
  */
 function getDefaultLocalConfig(
   globalStaticCheckConfig: Record<string, GlobalStaticCheckLanguageConfig>,
@@ -600,7 +599,6 @@ function getDefaultLocalConfig(
     "context-files-references": DEFAULT_CONTEXT_FILES_FLAG,
     "context-files-workflow": DEFAULT_CONTEXT_FILES_FLAG,
     "static-check": getDefaultLocalStaticCheckConfig(globalStaticCheckConfig),
-    DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
     DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
     DEBUG_PROMPTS_ENABLED: DEFAULT_DEBUG_PROMPTS_ENABLED,
     DEBUG_PROMPTS_LOG_PATH: DEFAULT_DEBUG_PROMPTS_LOG_PATH,
@@ -652,11 +650,11 @@ function getDefaultGlobalConfig(): UseReqGlobalConfig {
 
 /**
  * @brief Merges persisted local and global configuration scopes into the effective runtime config.
- * @details Normalizes local directories, combines local static-check enable flags with global checker arrays, resolves effective worktree disablement when automatic git commit is off, normalizes debug and notification fields including tool-wrapper command registration, and disables Pushover until both credentials are populated. Runtime is O(l + c + p). No external state is mutated.
+ * @details Normalizes local directories, combines local static-check enable flags with global checker arrays, resolves effective worktree disablement when automatic git commit is off, normalizes debug and notification fields including tool-wrapper command registration, sources the runtime-only `DEBUG_ENABLED` flag from the process-scoped debug store, and disables Pushover until both credentials are populated. Runtime is O(l + c + p). No external state is mutated.
  * @param[in] localConfig {UseReqLocalConfig} Persisted local configuration.
  * @param[in] globalConfig {UseReqGlobalConfig} Persisted global configuration.
  * @return {UseReqConfig} Effective merged configuration.
- * @satisfies REQ-328, REQ-413, REQ-414
+ * @satisfies REQ-236, REQ-328, REQ-413, REQ-414, REQ-426
  */
 function mergeConfigScopes(
   localConfig: UseReqLocalConfig,
@@ -691,7 +689,7 @@ function mergeConfigScopes(
     AUTO_GIT_COMMIT: autoGitCommit,
     GIT_WORKTREE_ENABLED: gitWorktreeEnabled,
     GIT_WORKTREE_PREFIX: normalizeGitWorktreePrefix(globalConfig.GIT_WORKTREE_PREFIX),
-    DEBUG_ENABLED: normalizeDebugEnabled(localConfig.DEBUG_ENABLED),
+    DEBUG_ENABLED: getRuntimeDebugEnabled(),
     DEBUG_LOG_FILE: normalizeDebugLogFile(localConfig.DEBUG_LOG_FILE),
     DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(localConfig.DEBUG_PROMPTS_ENABLED),
     DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(localConfig.DEBUG_PROMPTS_LOG_PATH),
@@ -862,11 +860,11 @@ function normalizeGlobalStaticCheckConfig(
 
 /**
  * @brief Loads and sanitizes the persisted local configuration.
- * @details Returns defaults when `<base-path>/.pi-usereq.json` is absent. Otherwise parses the local JSON payload, normalizes project-scoped directory, debug, tool-wrapper command registration, and static-check enable fields, and ignores misplaced global keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+ * @details Returns defaults when `<base-path>/.pi-usereq.json` is absent. Otherwise parses the local JSON payload, normalizes project-scoped directory, debug, tool-wrapper command registration, and static-check enable fields, ignores any persisted `DEBUG_ENABLED` payload, and ignores misplaced global keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
  * @param[in] projectBase {string} Absolute project root path.
  * @param[in] defaultStaticCheckConfig {Record<string, LocalStaticCheckLanguageConfig>} Local static-check enable defaults derived from the current global checker map.
  * @return {UseReqLocalConfig} Sanitized local configuration.
- * @satisfies CTN-019, REQ-328, REQ-413, REQ-414
+ * @satisfies CTN-019, REQ-328, REQ-413, REQ-414, REQ-426
  */
 function loadLocalConfig(
   projectBase: string,
@@ -883,7 +881,6 @@ function loadLocalConfig(
       "context-files-references": DEFAULT_CONTEXT_FILES_FLAG,
       "context-files-workflow": DEFAULT_CONTEXT_FILES_FLAG,
       "static-check": normalizeLocalStaticCheckConfig(undefined, defaultStaticCheckConfig),
-      DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
       DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
       DEBUG_PROMPTS_ENABLED: DEFAULT_DEBUG_PROMPTS_ENABLED,
       DEBUG_PROMPTS_LOG_PATH: DEFAULT_DEBUG_PROMPTS_LOG_PATH,
@@ -915,7 +912,6 @@ function loadLocalConfig(
     "context-files-references": normalizeContextFilesFlag(data["context-files-references"]),
     "context-files-workflow": normalizeContextFilesFlag(data["context-files-workflow"]),
     "static-check": normalizeLocalStaticCheckConfig(data["static-check"], defaultStaticCheckConfig),
-    DEBUG_ENABLED: normalizeDebugEnabled(data.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(data.DEBUG_LOG_FILE),
     DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(data.DEBUG_PROMPTS_ENABLED),
     DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(data.DEBUG_PROMPTS_LOG_PATH),
@@ -995,10 +991,10 @@ export function loadConfig(projectBase: string): UseReqConfig {
 
 /**
  * @brief Builds the persisted local configuration payload.
- * @details Copies only project-scoped keys into a fresh object so runtime-derived metadata plus global checker, tool, git, and notification fields never reach `.pi-usereq.json`, while preserving the debug tool-wrapper command flag beside other local debug settings. Runtime is O(n) in config size. No external state is mutated.
+ * @details Copies only project-scoped keys into a fresh object so runtime-derived metadata, the runtime-only `DEBUG_ENABLED` flag, and global checker, tool, git, and notification fields never reach `.pi-usereq.json`, while preserving the debug tool-wrapper command flag beside other persisted local debug settings. Runtime is O(n) in config size. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective configuration object.
  * @return {UseReqLocalConfig} Persistable local configuration payload.
- * @satisfies CTN-012, CTN-013, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277, REQ-328, REQ-413, REQ-414
+ * @satisfies CTN-012, CTN-013, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277, REQ-328, REQ-413, REQ-414, REQ-426
  */
 function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
   const normalizedSrcDir = config["src-dir"]
@@ -1022,7 +1018,6 @@ function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
         ),
       ]),
     ),
-    DEBUG_ENABLED: normalizeDebugEnabled(config.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(config.DEBUG_LOG_FILE),
     DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED),
     DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(config.DEBUG_PROMPTS_LOG_PATH),

package/src/core/debug-runtime.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Declares debug inventories, normalizers, and JSON log persistence helpers.
- * @details Centralizes debug-menu selector inventories, config-field normalization, workflow-status gating, and append-only JSON log writing for tool, prompt, and dedicated workflow debug events. Runtime is dominated by JSON serialization plus filesystem I/O during log writes. Side effects include directory creation and file overwrite when debug entries are appended.
+ * @details Centralizes debug-menu selector inventories, config-field normalization, the process-scoped runtime debug-enable state, workflow-status gating, append-only JSON log writing for tool, prompt, and dedicated workflow debug events, process-scoped capture of the exact `before_provider_request` provider payload for active prompt runs, and error-stage provider payload dumps gated by `after_provider_response` error statuses. Runtime is dominated by JSON serialization plus filesystem I/O during log writes. Side effects include directory creation and file overwrite when debug entries are appended.
  */
 
 import fs from "node:fs";
@@ -24,6 +24,49 @@ import {
  */
 export const DEFAULT_DEBUG_ENABLED = "disable" as const;
 
+/**
+ * @brief Describes the process-scoped runtime debug-enable state persisted across session rebinds.
+ * @details Stores the user-toggled runtime `Debug` flag on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload` while the hosting process persists across those operations; the flag therefore survives ctrl+N session forks and `req-reset` but resets to `disable` when a fresh pi CLI process starts. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-236, REQ-426
+ */
+interface ProcessScopedDebugEnabledStore {
+  runtimeDebugEnabled: "enable" | "disable" | undefined;
+}
+
+/**
+ * @brief Returns the process-scoped runtime debug-enable store.
+ * @details Lazily initializes one `globalThis` record so session rebinds reuse the toggled runtime debug mode instead of resetting it to the persisted default. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedDebugEnabledStore} Mutable process-scoped runtime debug store.
+ */
+function getProcessScopedDebugEnabledStore(): ProcessScopedDebugEnabledStore {
+  const globalScope = globalThis as typeof globalThis & { __piUsereqDebugEnabledStore?: ProcessScopedDebugEnabledStore };
+  if (!globalScope.__piUsereqDebugEnabledStore) {
+    globalScope.__piUsereqDebugEnabledStore = { runtimeDebugEnabled: undefined };
+  }
+  return globalScope.__piUsereqDebugEnabledStore;
+}
+
+/**
+ * @brief Resolves the runtime debug-enable mode for the current pi host process.
+ * @details Returns the process-scoped toggled value when present and the documented `disable` default otherwise, so every fresh pi CLI process starts with debug logging disabled regardless of any stale persisted payload. Runtime is O(1). No external state is mutated.
+ * @return {"enable" | "disable"} Effective runtime debug-enable mode.
+ * @satisfies REQ-236
+ */
+export function getRuntimeDebugEnabled(): "enable" | "disable" {
+  return getProcessScopedDebugEnabledStore().runtimeDebugEnabled ?? DEFAULT_DEBUG_ENABLED;
+}
+
+/**
+ * @brief Stores one user-toggled runtime debug-enable mode for the current pi host process.
+ * @details Mutates only the process-scoped runtime store so `Debug` menu toggles survive session rebinds without reaching persisted local or global configuration files. Runtime is O(1). Side effect: mutates process-scoped runtime state.
+ * @param[in] runtimeDebugEnabled {"enable" | "disable"} Next runtime debug-enable mode.
+ * @return {void} No return value.
+ * @satisfies REQ-236, REQ-426
+ */
+export function setRuntimeDebugEnabled(runtimeDebugEnabled: "enable" | "disable"): void {
+  getProcessScopedDebugEnabledStore().runtimeDebugEnabled = runtimeDebugEnabled;
+}
+
 /**
  * @brief Defines the default debug log file value.
  * @details New configurations write debug JSON entries to `/tmp/PI-useReq.json` unless the user overrides the path. Access complexity is O(1).
@@ -442,10 +485,10 @@ export function shouldLogDebugPromptWorkflowEvent(
 
 /**
  * @brief Tests whether one dispatched prompt content file should be written.
- * @details Requires global debug enablement, explicit prompt-content debug enablement, and a matching workflow-state filter before any filesystem work occurs; prompt-content logging is therefore fully subordinate to the global `Debug` flag. Runtime is O(1). No external state is mutated.
+ * @details Requires global debug enablement plus explicit prompt-content debug enablement before any filesystem work occurs; prompt-content logging is fully subordinate to the global `Debug` flag and exempt from the `DEBUG_LOG_ON_STATUS` workflow-state filter so enabled runs always save their debug files. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
- * @param[in] workflowState {DebugWorkflowState} Current workflow state.
- * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state; retained for signature compatibility and excluded from gating per REQ-416.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name; retained for signature compatibility.
  * @return {boolean} `true` when the prompt content file should be written.
  * @satisfies REQ-413, REQ-416
  */
@@ -455,8 +498,7 @@ export function shouldLogDebugPromptContent(
   promptName: PromptCommandName,
 ): boolean {
   return normalizeDebugEnabled(config.DEBUG_ENABLED) === "enable"
-    && normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED) === "enable"
-    && matchesDebugWorkflowState(normalizeDebugLogOnStatus(config.DEBUG_LOG_ON_STATUS), workflowState);
+    && normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED) === "enable";
 }
 
 /**
@@ -680,16 +722,107 @@ export function formatPromptDebugFileName(
   return `${formatPromptDebugTimestamp(date)}-${getDebugPromptName(promptName)}`;
 }
 
+/**
+ * @brief Builds one command-invocation summary debug filename for one bundled prompt.
+ * @details Appends the `-request` suffix to the shared `<timestamp>-<req-command>` base so every saved command invocation summary stays attributable to the originating `/req-*` prompt. Runtime is O(1). No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] date {Date} Write-time timestamp. Defaults to the current wall-clock time.
+ * @return {string} Prompt debug filename in the `<timestamp>-<req-command>-request` shape.
+ * @satisfies REQ-417, REQ-427
+ */
+export function formatPromptDebugRequestFileName(
+  promptName: PromptCommandName,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugFileName(promptName, date)}-request`;
+}
+
+/**
+ * @brief Builds one dispatched-prompt content debug filename for one bundled prompt.
+ * @details Appends the `-prompt` suffix to the shared `<timestamp>-<req-command>` base so every saved initial LLM prompt stays attributable to the originating `/req-*` prompt. Runtime is O(1). No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] date {Date} Write-time timestamp. Defaults to the current wall-clock time.
+ * @return {string} Prompt debug filename in the `<timestamp>-<req-command>-prompt` shape.
+ * @satisfies REQ-417, REQ-418
+ */
+export function formatPromptDebugPromptFileName(
+  promptName: PromptCommandName,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugFileName(promptName, date)}-prompt`;
+}
+
+/**
+ * @brief Writes one gated prompt debug file under the configured prompt log directory.
+ * @details Applies the global-debug plus prompt-debug gating, creates the configured prompt log directory, and writes the supplied text into the requested filename so dispatched-prompt artifacts can be replayed from the pi CLI without pi-usereq installed. Runtime is dominated by one directory creation plus one file write when enabled and O(1) otherwise. Side effects include directory creation and file creation only for enabled matching entries.
+ * @param[in] projectBase {string} Absolute original project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state; excluded from gating per REQ-416.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] fileName {string} Target filename under the resolved prompt log directory.
+ * @param[in] content {string} Exact text to persist.
+ * @return {boolean} `true` when the file is written; otherwise `false`.
+ * @satisfies REQ-416
+ */
+function writePromptDebugFile(
+  projectBase: string,
+  config: UseReqConfig,
+  workflowState: DebugWorkflowState,
+  promptName: PromptCommandName,
+  fileName: string,
+  content: string,
+): boolean {
+  if (!shouldLogDebugPromptContent(config, workflowState, promptName)) {
+    return false;
+  }
+  const logDirectory = resolveDebugPromptsLogPath(projectBase, config);
+  try {
+    fs.mkdirSync(logDirectory, { recursive: true });
+    fs.writeFileSync(path.join(logDirectory, fileName), content, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @brief Writes one command invocation summary debug file when prompt debug logging is enabled.
+ * @details Persists the exact summary text displayed on screen into one `<timestamp>-<req-command>-request` file so the `/req-*` invocation headers survive beside the dispatched prompt. Runtime is dominated by one directory creation plus one file write when enabled and O(1) otherwise. Side effects include directory creation and file creation only for enabled matching entries.
+ * @param[in] projectBase {string} Absolute original project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state; excluded from gating per REQ-416.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] requestText {string} Exact command invocation summary text displayed on screen.
+ * @return {boolean} `true` when the request file is written; otherwise `false`.
+ * @satisfies REQ-416, REQ-417, REQ-427, REQ-428
+ */
+export function logDebugPromptRequest(
+  projectBase: string,
+  config: UseReqConfig,
+  workflowState: DebugWorkflowState,
+  promptName: PromptCommandName,
+  requestText: string,
+): boolean {
+  return writePromptDebugFile(
+    projectBase,
+    config,
+    workflowState,
+    promptName,
+    formatPromptDebugRequestFileName(promptName),
+    requestText,
+  );
+}
+
 /**
  * @brief Writes one dispatched prompt content file when prompt debug logging is enabled.
- * @details Applies global-debug, prompt-debug, and workflow-state gating before creating the configured prompt log directory and writing the exact delivered prompt content into one `<timestamp>-<req-command>` file so the send can be replayed from the pi CLI without pi-usereq installed. Runtime is dominated by one directory creation plus one file write when enabled and O(1) otherwise. Side effects include directory creation and file creation only for enabled matching entries.
+ * @details Persists the exact rendered prompt content delivered through `sendMessage` or `sendUserMessage` into one `<timestamp>-<req-command>-prompt` file so the send can be replayed from the pi CLI without pi-usereq installed. Runtime is dominated by one directory creation plus one file write when enabled and O(1) otherwise. Side effects include directory creation and file creation only for enabled matching entries.
  * @param[in] projectBase {string} Absolute original project base path.
  * @param[in] config {UseReqConfig} Effective project configuration.
- * @param[in] workflowState {DebugWorkflowState} Current workflow state.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state; excluded from gating per REQ-416.
  * @param[in] promptName {PromptCommandName} Bundled prompt name.
  * @param[in] content {string} Exact rendered prompt content delivered through `sendMessage` or `sendUserMessage`.
  * @return {boolean} `true` when the prompt content file is written; otherwise `false`.
- * @satisfies REQ-416, REQ-417, REQ-418
+ * @satisfies REQ-416, REQ-417, REQ-418, REQ-428
  */
 export function logDebugPromptContent(
   projectBase: string,
@@ -698,15 +831,152 @@ export function logDebugPromptContent(
   promptName: PromptCommandName,
   content: string,
 ): boolean {
-  if (!shouldLogDebugPromptContent(config, workflowState, promptName)) {
+  return writePromptDebugFile(
+    projectBase,
+    config,
+    workflowState,
+    promptName,
+    formatPromptDebugPromptFileName(promptName),
+    content,
+  );
+}
+
+/**
+ * @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
+ */
+interface CapturedPromptErrorPayload {
+  promptName: PromptCommandName;
+  payloadText: string;
+  projectBase: string;
+  logDirectory: 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.
+ */
+interface ProcessScopedPromptErrorCaptureStore {
+  capturedPromptErrorPayload: CapturedPromptErrorPayload | undefined;
+}
+
+/**
+ * @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.
+ * @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 };
+  }
+  return globalScope.__piUsereqPromptErrorCaptureStore;
+}
+
+/**
+ * @brief Builds one provider error payload debug filename for one bundled prompt.
+ * @details Combines the write-time `YYYYMMDDHHMMSSmmm` timestamp, the invokable `req-*` command name, and the failing provider response status into the `<timestamp>-<req-command>-error-<status>` shape so every saved error-stage prompt payload stays attributable to the originating `/req-*` prompt and its session error code. 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. Defaults to the current wall-clock time.
+ * @return {string} Provider error payload filename in the `<timestamp>-<req-command>-error-<status>` shape.
+ * @satisfies REQ-423
+ */
+export function formatPromptDebugErrorFileName(
+  promptName: PromptCommandName,
+  errorCode: number,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugTimestamp(date)}-${getDebugPromptName(promptName)}-error-${errorCode}`;
+}
+
+/**
+ * @brief Serializes one provider request payload into deterministic text.
+ * @details Pretty-prints the payload as JSON while degrading circular references into one `[Circular]` token and bigint values into decimal strings so serialization failures never discard the capture. Runtime is O(n) in serialized payload size. No external state is mutated.
+ * @param[in] payload {unknown} Exact `before_provider_request` provider request payload.
+ * @return {string} Serialized payload text; the empty string when the payload serializes to nothing.
+ */
+function serializePromptProviderPayload(payload: unknown): string {
+  const seenObjects = new WeakSet<object>();
+  return JSON.stringify(
+    payload,
+    (_key: string, value: unknown) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      if (typeof value === "object" && value !== null) {
+        if (seenObjects.has(value)) {
+          return "[Circular]";
+        }
+        seenObjects.add(value);
+      }
+      return value;
+    },
+    2,
+  ) ?? "";
+}
+
+/**
+ * @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.
+ * @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.
+ * @return {void} No return value.
+ * @satisfies REQ-416, REQ-421
+ */
+export function capturePromptProviderRequestForDebug(
+  config: UseReqConfig,
+  promptName: PromptCommandName,
+  projectBase: string,
+  payload: unknown,
+): void {
+  if (!shouldLogDebugPromptContent(config, "unknown", promptName)) {
+    return;
+  }
+  getProcessScopedPromptErrorCaptureStore().capturedPromptErrorPayload = {
+    promptName,
+    payloadText: serializePromptProviderPayload(payload),
+    projectBase,
+    logDirectory: resolveDebugPromptsLogPath(projectBase, config),
+  };
+}
+
+/**
+ * @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.
+ * @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
+ */
+export function flushCapturedPromptErrorPayload(errorCode: number): boolean {
+  const captureStore = getProcessScopedPromptErrorCaptureStore();
+  const captured = captureStore.capturedPromptErrorPayload;
+  captureStore.capturedPromptErrorPayload = undefined;
+  if (!captured || !Number.isFinite(errorCode) || errorCode < 400) {
     return false;
   }
-  const logDirectory = resolveDebugPromptsLogPath(projectBase, config);
   try {
-    fs.mkdirSync(logDirectory, { recursive: true });
-    fs.writeFileSync(path.join(logDirectory, formatPromptDebugFileName(promptName)), content, "utf8");
+    fs.mkdirSync(captured.logDirectory, { recursive: true });
+    fs.writeFileSync(
+      path.join(captured.logDirectory, formatPromptDebugErrorFileName(captured.promptName, errorCode)),
+      captured.payloadText,
+      "utf8",
+    );
     return true;
   } catch {
     return false;
   }
 }
+
+/**
+ * @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.
+ * @return {void} No return value.
+ * @satisfies REQ-421, REQ-425
+ */
+export function discardCapturedPromptErrorPayload(): void {
+  getProcessScopedPromptErrorCaptureStore().capturedPromptErrorPayload = undefined;
+}

package/src/core/extension-status.ts

@@ -74,6 +74,7 @@ export const PI_USEREQ_STATUS_HOOK_NAMES = [
   "session_tree",
   "context",
   "before_provider_request",
+  "after_provider_response",
   "before_agent_start",
   "agent_start",
   "agent_end",

package/src/index.ts

@@ -133,8 +133,12 @@ import {
   DEFAULT_DEBUG_STATUS_CHANGES,
   DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
+  capturePromptProviderRequestForDebug,
+  discardCapturedPromptErrorPayload,
+  flushCapturedPromptErrorPayload,
   logDebugPromptContent,
   logDebugPromptEvent,
+  logDebugPromptRequest,
   logDebugPromptWorkflowEvent,
   logDebugToolExecution,
   normalizeDebugEnabledPrompts,
@@ -146,6 +150,7 @@ import {
   normalizeDebugStatusChanges,
   normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
+  setRuntimeDebugEnabled,
   shouldLogDebugPromptWorkflowState,
   type DebugLogOnStatus,
   type DebugWorkflowState,
@@ -1443,14 +1448,14 @@ 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. 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 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 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.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1509,6 +1514,31 @@ async function handleExtensionStatusEvent(
       }
     : undefined;
   updateExtensionStatus(statusController, hookName, event, ctx);
+  // Provider payload capture and error flush read the LIVE post-update controller state and fall
+  // back to a fresh config load: after switchSession rebinds the extension, the entry-read
+  // `activePromptRequest` snapshot can be stale, `agent_start` promotion may lag one hook, and the
+  // replacement-session instance may not have cached config yet. The process-scoped capture store
+  // carries everything the error-stage write needs, so the flush itself is state-independent.
+  const livePromptRequest = statusController.state.activePromptRequest
+    ?? statusController.state.pendingPromptRequest;
+  if (hookName === "before_provider_request" && livePromptRequest !== undefined) {
+    const providerRequestEvent = event as { payload?: unknown };
+    capturePromptProviderRequestForDebug(
+      statusController.config ?? loadProjectConfig(resolveLiveBootstrapCwd(ctx.cwd)),
+      livePromptRequest.promptName,
+      livePromptRequest.basePath,
+      providerRequestEvent.payload,
+    );
+  }
+  if (hookName === "after_provider_response") {
+    const providerResponseEvent = event as { status?: unknown };
+    if (typeof providerResponseEvent.status === "number" && providerResponseEvent.status >= 400) {
+      flushCapturedPromptErrorPayload(providerResponseEvent.status);
+    }
+  }
+  if (hookName === "agent_end" || hookName === "agent_settled") {
+    discardCapturedPromptErrorPayload();
+  }
   if (hookName === "tool_result" && statusController.config) {
     const toolEvent = event as {
       toolName?: string;
@@ -1783,13 +1813,14 @@ function getDebugToolToggleNames(): PiUsereqStartupToolName[] {
 
 /**
  * @brief Restores the debug configuration subtree to its documented defaults.
- * @details Resets global debug enablement, log path, prompt-content debug enablement plus prompt log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
+ * @details Resets runtime debug enablement in both the effective config object and the process-scoped runtime debug store, then resets log path, prompt-content debug enablement plus prompt log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config` and process-scoped runtime debug state.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {void} No return value.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322, REQ-413, REQ-414, REQ-420
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322, REQ-413, REQ-414, REQ-420, REQ-426
  */
 function resetDebugConfigToDefaults(config: UseReqConfig): void {
   config.DEBUG_ENABLED = "disable";
+  setRuntimeDebugEnabled("disable");
   config.DEBUG_LOG_FILE = DEFAULT_DEBUG_LOG_FILE;
   config.DEBUG_PROMPTS_ENABLED = DEFAULT_DEBUG_PROMPTS_ENABLED;
   config.DEBUG_PROMPTS_LOG_PATH = DEFAULT_DEBUG_PROMPTS_LOG_PATH;
@@ -1991,12 +2022,12 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
 
 /**
  * @brief Runs the interactive Debug submenu.
- * @details Lets the user toggle global debug enablement, prompt-content debug enablement plus prompt log path, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
+ * @details Lets the user toggle runtime global debug enablement (stored only in the process-scoped runtime debug store and never persisted), prompt-content debug enablement plus prompt log path, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, process-scoped runtime debug state mutation, and optional debug command registration.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323, REQ-413, REQ-414, REQ-415, REQ-420
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323, REQ-413, REQ-414, REQ-415, REQ-420, REQ-426
  */
 async function configureDebugMenu(
   pi: ExtensionAPI,
@@ -2021,6 +2052,7 @@ async function configureDebugMenu(
       onChange: (choiceId, newValue) => {
         if (choiceId === "debug-enabled") {
           config.DEBUG_ENABLED = newValue === "enable" ? "enable" : "disable";
+          setRuntimeDebugEnabled(config.DEBUG_ENABLED);
           onConfigChange();
           ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
           return;
@@ -2087,6 +2119,7 @@ async function configureDebugMenu(
 
     if (choice === "debug-enabled") {
       config.DEBUG_ENABLED = config.DEBUG_ENABLED === "enable" ? "disable" : "enable";
+      setRuntimeDebugEnabled(config.DEBUG_ENABLED);
       onConfigChange();
       ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
       continue;
@@ -3430,11 +3463,11 @@ function registerReqReferencesCommand(
 
 /**
  * @brief Registers bundled prompt-backed commands with the extension.
- * @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, saves the exact delivered prompt content into the debug prompt log path when prompt debug logging is enabled, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, optional prompt-content debug file creation, user-message delivery during execution, and optional debug-log writes.
+ * @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, saves the exact command invocation summary plus the delivered prompt content into the debug prompt log path as separate `-request` and `-prompt` files when prompt debug logging is enabled, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, optional prompt-debug file creation, user-message delivery during execution, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281, REQ-377, REQ-416, REQ-417, REQ-418
+ * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281, REQ-377, REQ-416, REQ-417, REQ-418, REQ-427, REQ-428
  */
 function registerPromptCommands(
   pi: ExtensionAPI,
@@ -3540,6 +3573,13 @@ function registerPromptCommands(
             promptName,
             "running",
           );
+          logDebugPromptRequest(
+            projectBase,
+            config,
+            statusController.state.workflowState,
+            promptName,
+            commandSummary,
+          );
           logDebugPromptContent(
             projectBase,
             config,