pi-usereq 0.82.0 → 0.83.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.82.0)
+# PI-useReq/pi-usereq (0.83.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,7 +335,7 @@ 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`, a byte-for-byte snapshot of the retained execution session into `<timestamp>-<command>-error-<status>-session.jsonl`, 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; `replayCommands.piFork` targets the log-local `-session.jsonl` snapshot, which freezes the transcript exactly at the failing provider request (before any context edit or compaction). You can re-generate the failure for immediate pi CLI debugging:
+- **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>.json` (raw provider-request JSON), the provider error message text into `<timestamp>-<command>-error-<status>-response.txt`, a byte-for-byte snapshot of the retained execution session into `<timestamp>-<command>-error-<status>-session.jsonl`, and replay metadata into `<timestamp>-<command>-error-<status>-replay.json`, all beside the run's `-request.md` and `-prompt.md` 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; `replayCommands.piFork` targets the log-local `-session.jsonl` snapshot, which freezes the transcript exactly at the failing provider request (before any context edit or compaction). 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)
@@ -345,7 +345,7 @@ The extension renders a status field in the pi status line showing: extension id
   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
+    --data @/tmp/PI-useReq/20261012070707447-req-analyze-error-400.json
 
   # Replay the saved prompt through pi with the same model and thinking level
   pi --no-session --model '~deepseek/deepseek-flash-latest' --thinking high \

package/package.json

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

package/src/core/debug-runtime.ts

@@ -724,32 +724,32 @@ export function formatPromptDebugFileName(
 
 /**
  * @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.
+ * @details Appends the `-request.md` suffix to the shared `<timestamp>-<req-command>` base so every saved command invocation summary stays attributable to the originating `/req-*` prompt, with the `.md` extension coherent with the persisted markdown summary content per REQ-435. 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
+ * @return {string} Prompt debug filename in the `<timestamp>-<req-command>-request.md` shape.
+ * @satisfies REQ-417, REQ-427, REQ-435
  */
 export function formatPromptDebugRequestFileName(
   promptName: PromptCommandName,
   date = new Date(),
 ): string {
-  return `${formatPromptDebugFileName(promptName, date)}-request`;
+  return `${formatPromptDebugFileName(promptName, date)}-request.md`;
 }
 
 /**
  * @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.
+ * @details Appends the `-prompt.md` suffix to the shared `<timestamp>-<req-command>` base so every saved initial LLM prompt stays attributable to the originating `/req-*` prompt, with the `.md` extension coherent with the persisted markdown prompt content per REQ-435. 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
+ * @return {string} Prompt debug filename in the `<timestamp>-<req-command>-prompt.md` shape.
+ * @satisfies REQ-417, REQ-418, REQ-435
  */
 export function formatPromptDebugPromptFileName(
   promptName: PromptCommandName,
   date = new Date(),
 ): string {
-  return `${formatPromptDebugFileName(promptName, date)}-prompt`;
+  return `${formatPromptDebugFileName(promptName, date)}-prompt.md`;
 }
 
 /**
@@ -787,14 +787,14 @@ function writePromptDebugFile(
 
 /**
  * @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.
+ * @details Persists the exact summary text displayed on screen into one `<timestamp>-<req-command>-request.md` 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
+ * @satisfies REQ-416, REQ-417, REQ-427, REQ-428, REQ-435
  */
 export function logDebugPromptRequest(
   projectBase: string,
@@ -815,14 +815,14 @@ export function logDebugPromptRequest(
 
 /**
  * @brief Writes one dispatched prompt content file when prompt debug logging is enabled.
- * @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.
+ * @details Persists the exact rendered prompt content delivered through `sendMessage` or `sendUserMessage` into one `<timestamp>-<req-command>-prompt.md` 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; 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, REQ-428
+ * @satisfies REQ-416, REQ-417, REQ-418, REQ-428, REQ-435
  */
 export function logDebugPromptContent(
   projectBase: string,
@@ -878,7 +878,7 @@ interface CapturedPromptErrorPayload {
 
 /**
  * @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.
+ * @details Stores the prompt name, failing status, resolved log directory, and shared extensionless error base filename of the most recent error-stage flush so a later finalized `message_end` error message can still append the `-response.txt` 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 {
@@ -916,12 +916,12 @@ function getProcessScopedPromptErrorCaptureStore(): ProcessScopedPromptErrorCapt
 }
 
 /**
- * @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.
+ * @brief Builds the shared extensionless provider error base 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>` base shape so every saved error-stage prompt artifact stays attributable to the originating `/req-*` prompt and its session error code. This extensionless base is the suffix-attachment anchor for the `-response.txt`, `-replay.json`, and `-session.jsonl` variants; the flushed raw provider-request JSON payload appends its content-coherent `.json` extension through `formatPromptDebugErrorPayloadFileName(...)`. 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.
+ * @return {string} Extensionless provider error base filename in the `<timestamp>-<req-command>-error-<status>` shape.
  * @satisfies REQ-423
  */
 export function formatPromptDebugErrorFileName(
@@ -932,21 +932,38 @@ export function formatPromptDebugErrorFileName(
   return `${formatPromptDebugTimestamp(date)}-${getDebugPromptName(promptName)}-error-${errorCode}`;
 }
 
+/**
+ * @brief Builds one provider error payload debug filename for one bundled prompt.
+ * @details Appends the `.json` extension to the shared extensionless `<timestamp>-<req-command>-error-<status>` base so the flushed raw provider-request JSON payload keeps a filename extension coherent with its JSON content per REQ-435 while staying attributable to the exact failing request. 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 sibling error artifacts. Defaults to the current wall-clock time.
+ * @return {string} Provider error payload filename in the `<timestamp>-<req-command>-error-<status>.json` shape.
+ * @satisfies REQ-423, REQ-431, REQ-435
+ */
+export function formatPromptDebugErrorPayloadFileName(
+  promptName: PromptCommandName,
+  errorCode: number,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugErrorFileName(promptName, errorCode, date)}.json`;
+}
+
 /**
  * @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.
+ * @details Appends the `-response.txt` suffix to the shared extensionless `<timestamp>-<req-command>-error-<status>` shape so the persisted plain-text provider error message keeps a filename extension coherent with its text content per REQ-435 and 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
+ * @return {string} Provider error response filename in the `<timestamp>-<req-command>-error-<status>-response.txt` shape.
+ * @satisfies REQ-423, REQ-429, REQ-435
  */
 export function formatPromptDebugErrorResponseFileName(
   promptName: PromptCommandName,
   errorCode: number,
   date = new Date(),
 ): string {
-  return `${formatPromptDebugErrorFileName(promptName, errorCode, date)}-response`;
+  return `${formatPromptDebugErrorFileName(promptName, errorCode, date)}-response.txt`;
 }
 
 /**
@@ -1178,11 +1195,11 @@ function buildPromptErrorReplaySidecarText(
 
 /**
  * @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, one identically timestamped byte-for-byte `-session.jsonl` copy of the retained execution session so `pi --fork` can resume the exact failing state from the prompt log directory alone, 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 four 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.
+ * @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>.json` file that stays raw provider-request JSON usable with `curl --data @`, the provider error text into one identically timestamped `-response.txt` file when supplied, one identically timestamped byte-for-byte `-session.jsonl` copy of the retained execution session so `pi --fork` can resume the exact failing state from the prompt log directory alone, 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.txt` 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 four 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`.
  * @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, REQ-432, REQ-433
+ * @satisfies REQ-422, REQ-423, REQ-424, REQ-425, REQ-429, REQ-430, REQ-431, REQ-432, REQ-433, REQ-435
  */
 export function flushCapturedPromptErrorPayload(errorCode: number, errorResponseText?: string): boolean {
   const captureStore = getProcessScopedPromptErrorCaptureStore();
@@ -1192,7 +1209,7 @@ export function flushCapturedPromptErrorPayload(errorCode: number, errorResponse
     return false;
   }
   const writeTime = new Date();
-  const payloadFileName = formatPromptDebugErrorFileName(captured.promptName, errorCode, writeTime);
+  const payloadFileName = formatPromptDebugErrorPayloadFileName(captured.promptName, errorCode, writeTime);
   try {
     fs.mkdirSync(captured.logDirectory, { recursive: true });
     fs.writeFileSync(
@@ -1220,7 +1237,7 @@ export function flushCapturedPromptErrorPayload(errorCode: number, errorResponse
       promptName: captured.promptName,
       errorCode,
       logDirectory: captured.logDirectory,
-      baseFileName: payloadFileName,
+      baseFileName: formatPromptDebugErrorFileName(captured.promptName, errorCode, writeTime),
     };
     return true;
   } catch {
@@ -1273,7 +1290,7 @@ function copyPromptErrorSessionSnapshotFile(
 
 /**
  * @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.
+ * @details Providers that fire `after_provider_response` before surfacing their error text flush the payload without a `-response.txt` 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`.
@@ -1293,7 +1310,7 @@ export function writeFlushedPromptProviderErrorResponse(
   try {
     writePromptProviderErrorResponseFile(
       record.logDirectory,
-      `${record.baseFileName}-response`,
+      `${record.baseFileName}-response.txt`,
       errorResponseText,
     );
     return true;

package/src/core/req-reset-command.ts

@@ -325,7 +325,15 @@ function readReqResetSessionHeader(sessionFile: string): { cwd?: string; parentS
 
 /**
  * @brief Resolves the original base-path session file from the active session header.
- * @details Reads the current session file exposed by the supplied command context, accepts only a persisted `parentSession` link whose own header `cwd` remains inside the main base path, and returns it so `req-reset` can switch the pi CLI back to the original session-backed base path. Runtime is O(n) in session-header size plus bounded filesystem probes. No external state is mutated.
+ * @details Reads the current session file exposed by the supplied command context and accepts one
+ * persisted `parentSession` link as the reserved original base-path session under two conditions:
+ * when the linked file already exists on disk its own header `cwd` must remain inside the main base
+ * path, and when the linked file was never flushed to disk (pi persists session files lazily on the
+ * first entry append) the link itself proves the reserved original-session identity so the caller
+ * can materialize the base session before switching. Unpersisted links are accepted only when their
+ * parent directory already exists so recovery never writes session files into arbitrary locations.
+ * Runtime is O(n) in session-header size plus bounded filesystem probes. No external state is
+ * mutated.
  * @param[in] activeContext {ReqResetCommandContext | undefined} Session-bound command context whose current session file links the base-path session.
  * @param[in] basePath {string} Absolute main repository base path that must contain the parent session cwd.
  * @return {string | undefined} Original base-path session file or `undefined` when unavailable.
@@ -346,10 +354,15 @@ function resolveReqResetParentSessionFile(
     return undefined;
   }
   const header = readReqResetSessionHeader(path.resolve(currentSessionFile));
-  if (header?.parentSession === undefined || !fs.existsSync(header.parentSession)) {
+  if (header?.parentSession === undefined) {
     return undefined;
   }
   const resolvedParentSession = path.resolve(header.parentSession);
+  if (!fs.existsSync(resolvedParentSession)) {
+    return fs.existsSync(path.dirname(resolvedParentSession))
+      ? resolvedParentSession
+      : undefined;
+  }
   const parentHeader = readReqResetSessionHeader(resolvedParentSession);
   if (parentHeader?.cwd === undefined || !fs.existsSync(parentHeader.cwd)) {
     return undefined;
@@ -359,6 +372,93 @@ function resolveReqResetParentSessionFile(
     : undefined;
 }
 
+/**
+ * @brief Guarantees one switchable persisted base-path session file for `req-reset` re-anchoring.
+ * @details Leaves existing session files untouched and, when the resolved base session file was
+ * never flushed to disk (pi persists session files lazily on the first entry append), materializes
+ * one minimal pi JSONL session header whose `cwd` equals the main base path using the same header
+ * contract as pi `SessionManager.newSession(...)`/`forkFrom(...)` and the extension-owned execution
+ * session snapshots. Materialization is restricted to existing session directories so recovery
+ * never writes into arbitrary locations, and any write failure degrades to `false` so the caller
+ * surfaces the re-anchor failure instead of silently deleting the anchoring worktree.
+ * Runtime is O(p) in path length plus one bounded filesystem probe and at most one file write.
+ * Side effects include one conditional session-file creation.
+ * @param[in] sessionFile {string} Resolved base-path session file path.
+ * @param[in] basePath {string} Absolute main repository base path recorded in the materialized header.
+ * @return {boolean} `true` when a persisted session file exists or was materialized; `false` when the session directory is missing or the write fails.
+ */
+function ensureReqResetBaseSessionFile(sessionFile: string, basePath: string): boolean {
+  const normalizedSessionFile = path.resolve(sessionFile);
+  if (fs.existsSync(normalizedSessionFile)) {
+    return true;
+  }
+  if (!fs.existsSync(path.dirname(normalizedSessionFile))) {
+    return false;
+  }
+  const sessionHeader = {
+    type: "session",
+    version: 3,
+    id: `req-reset-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`,
+    timestamp: new Date().toISOString(),
+    cwd: path.resolve(basePath),
+  };
+  try {
+    fs.writeFileSync(normalizedSessionFile, `${JSON.stringify(sessionHeader)}\n`, "utf8");
+  } catch {
+    return false;
+  }
+  return fs.existsSync(normalizedSessionFile);
+}
+
+/**
+ * @brief Reads one live session-bound context session directory while tolerating stale contexts.
+ * @details Real pi command contexts resolve `sessionManager` through getter-only accessors whose
+ * reads throw the documented stale-extension-context error after session replacement, so the
+ * session-directory probe must degrade stale reads to `undefined`. Runtime is O(1). No external
+ * state is mutated.
+ * @param[in] activeContext {ReqResetCommandContext | undefined} Candidate session-bound context.
+ * @return {string | undefined} Live session directory when readable; `undefined` when absent or stale.
+ */
+function readReqResetContextSessionDir(activeContext: ReqResetCommandContext | undefined): string | undefined {
+  try {
+    const sessionDir = typeof activeContext?.sessionManager?.getSessionDir === "function"
+      ? activeContext.sessionManager.getSessionDir()
+      : undefined;
+    return typeof sessionDir === "string" && sessionDir !== "" ? sessionDir : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @brief Allocates one fresh persisted base-path session file for `req-reset` re-anchoring.
+ * @details Mirrors pi `/new` semantics for recovery situations without any resolvable original or
+ * recent base session: reserves one new session file path inside the live session directory
+ * through `SessionManager.create(...)` so the caller can materialize its header with the main base
+ * path and switch the pi CLI onto it before generated worktrees are removed. Allocation is
+ * restricted to existing session directories and any failure degrades to `undefined`. Runtime is
+ * O(p) in path length plus one bounded filesystem probe. No external state is mutated beyond the
+ * pi session-manager reservation.
+ * @param[in] basePath {string} Absolute main repository base path for the reserved session.
+ * @param[in] sessionDir {string | undefined} Live session directory reused for the reserved file.
+ * @return {string | undefined} Reserved session file path or `undefined` when allocation is impossible.
+ */
+function allocateReqResetBaseSessionFile(
+  basePath: string,
+  sessionDir: string | undefined,
+): string | undefined {
+  if (typeof sessionDir !== "string" || sessionDir === "" || !fs.existsSync(sessionDir)) {
+    return undefined;
+  }
+  try {
+    const sessionManager = SessionManager.create(path.resolve(basePath), sessionDir);
+    const sessionFile = sessionManager.getSessionFile();
+    return typeof sessionFile === "string" && sessionFile !== "" ? path.resolve(sessionFile) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * @brief Resolves the most recent persisted session file rooted at the main base path.
  * @details Uses the pi SDK default session discovery for the supplied cwd and returns the persisted session file only when it already exists on disk, so the pi CLI can resume the recent base-path session instead of being created a fresh one. Runtime is O(s) in session-directory listing cost. No external state is mutated.
@@ -408,20 +508,51 @@ function reqResetExecutionPathNeedsRedirect(
   });
 }
 
+/**
+ * @brief Reads one live session-bound context cwd while tolerating stale contexts.
+ * @details Real pi command contexts expose `cwd` as a getter-only accessor whose read throws the
+ * documented stale-extension-context error after session replacement, so every `req-reset` probe
+ * must degrade stale reads to `undefined` instead of aborting the whole recovery. Runtime is O(1).
+ * No external state is mutated.
+ * @param[in] activeContext {ReqResetCommandContext | undefined} Candidate session-bound context.
+ * @return {string | undefined} Live context cwd when readable; `undefined` when absent or stale.
+ */
+function readReqResetContextCwd(activeContext: ReqResetCommandContext | undefined): string | undefined {
+  try {
+    return typeof activeContext?.cwd === "string" && activeContext.cwd !== ""
+      ? activeContext.cwd
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * @brief Returns the pi CLI to the main base path before generated worktrees are removed.
- * @details When the host process cwd or the supplied context cwd is still anchored inside a generated worktree targeted for deletion or points at a deleted path, best-effort switches the active pi session back to the original or recent base-path session, re-anchors `process.cwd()` and the context `cwd` mirror onto the main base path, and clears the runtime worktree path state so no post-cleanup surface keeps probing the removed worktree directory. Session switching failures are swallowed because the process and context surfaces remain authoritative for cleanup; session switching is skipped entirely when no `switchSession(...)` hook is available or no base-path session exists. Runtime is dominated by one optional session switch plus bounded filesystem probes. Side effects include active-session replacement, host-process cwd mutation, and optional context mirror mutation.
+ * @details When the host process cwd or the supplied context cwd is still anchored inside a
+ * generated worktree targeted for deletion or points at a deleted path, best-effort switches the
+ * active pi session back to the original or recent base-path session, guaranteeing the resolved
+ * base session file is persisted through `ensureReqResetBaseSessionFile(...)` before switching so
+ * lazily-flushed reserved sessions still re-anchor the pi CLI onto the main base path. Re-anchors
+ * `process.cwd()`, clears the runtime worktree path state so no post-cleanup surface keeps probing
+ * the removed worktree directory, and reports any session-switch failure through the returned
+ * re-anchor diagnostic so the caller can surface it and retain anchoring worktrees instead of
+ * silently orphaning the live session at a deleted directory. Context `cwd` mirrors are probed
+ * stale-safely because pi contexts expose getter-only accessors that `Reflect.set(...)` cannot
+ * mutate. Runtime is dominated by one optional session switch plus bounded filesystem probes.
+ * Side effects include active-session replacement, host-process cwd mutation, and one conditional
+ * base-session file materialization.
  * @param[in] basePath {string} Absolute main repository base path.
  * @param[in,out] activeContext {ReqResetCommandContext | undefined} Mutated session context mirror and potential replacement-session context.
  * @param[in] matchingWorktreeRoots {string[]} Absolute generated worktree roots targeted for deletion.
- * @return {Promise<ReqResetCommandContext | undefined>} Replacement-session context when the runtime provides one; otherwise the caller-supplied context.
- * @satisfies REQ-257, REQ-307
+ * @return {Promise<{ context: ReqResetCommandContext | undefined; reanchorErrorMessage?: string }>} Re-anchored context plus one optional re-anchor failure diagnostic.
+ * @satisfies REQ-257, REQ-307, REQ-308, REQ-313
  */
 async function redirectReqResetExecutionToMainBranch(
   basePath: string,
   activeContext: ReqResetCommandContext | undefined,
   matchingWorktreeRoots: string[],
-): Promise<ReqResetCommandContext | undefined> {
+): Promise<{ context: ReqResetCommandContext | undefined; reanchorErrorMessage?: string }> {
   const normalizedBasePath = path.resolve(basePath);
   let processCwd: string | undefined;
   try {
@@ -429,7 +560,7 @@ async function redirectReqResetExecutionToMainBranch(
   } catch {
     processCwd = undefined;
   }
-  const contextCwd = typeof activeContext?.cwd === "string" ? activeContext.cwd : undefined;
+  const contextCwd = readReqResetContextCwd(activeContext);
   const processNeedsRedirect = reqResetExecutionPathNeedsRedirect(
     processCwd,
     normalizedBasePath,
@@ -441,17 +572,26 @@ async function redirectReqResetExecutionToMainBranch(
     matchingWorktreeRoots,
   );
   if (!processNeedsRedirect && !contextNeedsRedirect) {
-    return activeContext;
+    return { context: activeContext };
   }
+  let reanchorErrorMessage: string | undefined;
   if (typeof activeContext?.switchSession === "function") {
-    const mainSessionFile = resolveReqResetParentSessionFile(activeContext, normalizedBasePath)
+    let mainSessionFile = resolveReqResetParentSessionFile(activeContext, normalizedBasePath)
       ?? resolveReqResetMainSessionFile(normalizedBasePath);
-    if (mainSessionFile !== undefined) {
+    if (mainSessionFile === undefined) {
+      mainSessionFile = allocateReqResetBaseSessionFile(
+        normalizedBasePath,
+        readReqResetContextSessionDir(activeContext),
+      );
+    }
+    if (mainSessionFile !== undefined && ensureReqResetBaseSessionFile(mainSessionFile, normalizedBasePath)) {
       try {
         activeContext = await switchPromptCommandSession(mainSessionFile, activeContext);
-      } catch {
-        // Best-effort; host process and context surfaces below remain authoritative.
+      } catch (error) {
+        reanchorErrorMessage = `ERROR: req-reset could not switch the pi session back to ${normalizedBasePath}: ${error instanceof Error ? error.message : String(error)}`;
       }
+    } else {
+      reanchorErrorMessage = `ERROR: req-reset found no persisted base-path session to restore for ${normalizedBasePath}.`;
     }
   }
   try {
@@ -461,7 +601,7 @@ async function redirectReqResetExecutionToMainBranch(
   }
   if (activeContext !== undefined) {
     try {
-      if (path.resolve(activeContext.cwd ?? "") !== normalizedBasePath) {
+      if (path.resolve(readReqResetContextCwd(activeContext) ?? "") !== normalizedBasePath) {
         Reflect.set(activeContext, "cwd", normalizedBasePath);
       }
     } catch {
@@ -470,7 +610,38 @@ async function redirectReqResetExecutionToMainBranch(
   }
   setRuntimeContextPath(normalizedBasePath);
   setRuntimeWorktreePathState({});
-  return activeContext;
+  return { context: activeContext, reanchorErrorMessage };
+}
+
+/**
+ * @brief Lists matching worktree roots that still anchor the live session cwd.
+ * @details Used only after a failed session re-anchor so `req-reset` retains the worktree directory
+ * the live pi session is still checked out in, preventing the session cwd from being orphaned at a
+ * deleted directory (which renders `branch:unknown`). Stale or unreadable context cwds and paths
+ * that no longer exist yield an empty list because the session cannot be probed reliably. Runtime
+ * is O(r) in matched-worktree count plus one bounded filesystem probe. No external state is
+ * mutated.
+ * @param[in] activeContext {ReqResetCommandContext | undefined} Session-bound context whose live cwd may still anchor one matching worktree.
+ * @param[in] matchingWorktreeRoots {string[]} Absolute generated worktree roots targeted for deletion.
+ * @return {string[]} Absolute matching worktree roots that still contain the live session cwd.
+ */
+function resolveReqResetAnchoredWorktreeRoots(
+  activeContext: ReqResetCommandContext | undefined,
+  matchingWorktreeRoots: string[],
+): string[] {
+  const contextCwd = readReqResetContextCwd(activeContext);
+  if (contextCwd === undefined) {
+    return [];
+  }
+  const normalizedContextCwd = path.resolve(contextCwd);
+  if (!fs.existsSync(normalizedContextCwd)) {
+    return [];
+  }
+  return matchingWorktreeRoots.filter((worktreeRootPath) => {
+    const normalizedRoot = path.resolve(worktreeRootPath);
+    return normalizedContextCwd === normalizedRoot
+      || normalizedContextCwd.startsWith(`${normalizedRoot}${path.sep}`);
+  });
 }
 
 /**
@@ -547,7 +718,7 @@ export function prepareReqResetCommandExecution(
 
 /**
  * @brief Executes the specialized `req-reset` recovery and cleanup workflow.
- * @details Preserves the execution-session transcript into the original session file when a worktree-backed prompt execution plan is still available, restores the original session-backed `base-path` through the shared prompt-command restoration helper, ensures the main repository HEAD is on the main branch so generated branch deletion cannot hit git's checked-out-worktree guard, enumerates every matching sibling worktree, returns the pi CLI execution surfaces to the main base path before any matching worktree directory is removed, force-removes every matching sibling worktree directory, force-removes every remaining matching local branch, restores deleted live cwd surfaces, and aggregates any failure diagnostics without rolling back successful cleanup steps. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, branch switching, worktree deletion, branch deletion, and filesystem reads.
+ * @details Preserves the execution-session transcript into the original session file when a worktree-backed prompt execution plan is still available, restores the original session-backed `base-path` through the shared prompt-command restoration helper, ensures the main repository HEAD is on the main branch so generated branch deletion cannot hit git's checked-out-worktree guard, enumerates every matching sibling worktree, returns the pi CLI execution surfaces to the main base path (materializing the reserved base session when pi never flushed it) before any matching worktree directory is removed, force-removes every matching sibling worktree directory, force-removes every remaining matching local branch, retains the worktree plus branch that still anchor the live pi session whenever the session re-anchor fails so the session cwd is never orphaned at a deleted directory, restores deleted live cwd surfaces, and aggregates any failure diagnostics without rolling back successful cleanup steps. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, branch switching, worktree deletion, branch deletion, and filesystem reads.
  * @param[in] plan {ReqResetCommandPlan} Prepared recovery and cleanup plan.
  * @param[in] ctx {ReqResetCommandContext | undefined} Optional session-bound command context.
  * @return {Promise<ReqResetCommandExecutionResult>} Recovery and cleanup outcome facts.
@@ -604,14 +775,30 @@ export async function executeReqResetCommandExecution(
     errorMessages.push(error instanceof Error ? error.message : String(error));
   }
 
-  activeContext = await redirectReqResetExecutionToMainBranch(
+  const redirectOutcome = await redirectReqResetExecutionToMainBranch(
     plan.basePath,
     activeContext,
     matchingWorktreeRoots,
   );
+  activeContext = redirectOutcome.context;
+  if (redirectOutcome.reanchorErrorMessage !== undefined) {
+    errorMessages.push(redirectOutcome.reanchorErrorMessage);
+  }
+  const retainedWorktreeDirs = new Set(
+    redirectOutcome.reanchorErrorMessage !== undefined
+      ? resolveReqResetAnchoredWorktreeRoots(activeContext, matchingWorktreeRoots)
+        .map((worktreeRootPath) => path.basename(worktreeRootPath))
+      : [],
+  );
 
   for (const worktreeRootPath of matchingWorktreeRoots) {
     const worktreeDir = path.basename(worktreeRootPath);
+    if (retainedWorktreeDirs.has(worktreeDir)) {
+      errorMessages.push(
+        `ERROR: req-reset retained worktree ${worktreeDir} because the pi session could not be re-anchored to ${plan.basePath}.`,
+      );
+      continue;
+    }
     try {
       deletePromptWorktree(plan.basePath, worktreeDir, worktreeRootPath);
       removedWorktreeDirs.push(worktreeDir);
@@ -623,6 +810,12 @@ export async function executeReqResetCommandExecution(
   try {
     const matchingBranchNames = listReqResetMatchingBranchNames(plan.gitPath, plan.worktreeNamePattern);
     for (const branchName of matchingBranchNames) {
+      if (retainedWorktreeDirs.has(branchName)) {
+        errorMessages.push(
+          `ERROR: req-reset retained branch ${branchName} because its worktree still anchors the pi session.`,
+        );
+        continue;
+      }
       const deleteResult = runCapture(["git", "branch", "-D", branchName], plan.gitPath);
       if (deleteResult.error || deleteResult.status !== 0) {
         const diagnostic = deleteResult.stderr.trim()