pi-usereq 0.10.0 → 0.11.0

package/src/core/prompt-command-runtime.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Implements prompt-command preflight and worktree orchestration.
- * @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
+ * @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization with restored-session transcript preservation, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
  */
 
 import fs from "node:fs";
@@ -421,6 +421,169 @@ function readPromptSessionFileCwd(sessionFile: string): string | undefined {
   return typeof headerCwd === "string" ? headerCwd : undefined;
 }
 
+/**
+ * @brief Reads one persisted session file as ordered parsed JSONL records.
+ * @details Loads the raw session file, preserves every non-empty serialized line verbatim, parses each line as one JSON object, and rejects unreadable or structurally invalid files so prompt-closure helpers can replay exact execution-session transcript records into the restored base session without reserialization drift. Runtime is O(n) in session-file size. No external state is mutated.
+ * @param[in] sessionFile {string} Absolute session-file path.
+ * @return {Array<{ rawLine: string; parsed: Record<string, unknown> }>} Parsed non-empty JSONL lines in file order.
+ * @throws {ReqError} Throws when the file cannot be read, when it contains no JSONL records, when any record is not a JSON object, or when the header record is missing.
+ */
+function readPromptSessionJsonLines(
+  sessionFile: string,
+): Array<{ rawLine: string; parsed: Record<string, unknown> }> {
+  const normalizedSessionFile = path.resolve(sessionFile);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(normalizedSessionFile, "utf8");
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new ReqError(
+      `ERROR: Unable to read session file ${normalizedSessionFile}: ${errorMessage}.`,
+      1,
+    );
+  }
+  const parsedLines: Array<{ rawLine: string; parsed: Record<string, unknown> }> = [];
+  for (const [index, rawLine] of raw.split(/\r?\n/u).entries()) {
+    if (rawLine.trim() === "") {
+      continue;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawLine);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ReqError(
+        `ERROR: Unable to parse session file ${normalizedSessionFile} line ${index + 1}: ${errorMessage}.`,
+        1,
+      );
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new ReqError(
+        `ERROR: Session file ${normalizedSessionFile} line ${index + 1} is not a JSON object.`,
+        1,
+      );
+    }
+    parsedLines.push({ rawLine, parsed: parsed as Record<string, unknown> });
+  }
+  if (parsedLines.length === 0) {
+    throw new ReqError(`ERROR: Session file ${normalizedSessionFile} is empty.`, 1);
+  }
+  if (parsedLines[0]?.parsed.type !== "session") {
+    throw new ReqError(
+      `ERROR: Session file ${normalizedSessionFile} is missing a valid session header.`,
+      1,
+    );
+  }
+  return parsedLines;
+}
+
+/**
+ * @brief Copies successful execution-session transcript records into the restored base session file.
+ * @details Reads the execution session JSONL file, preserves the original base-session header when it already exists, materializes a restored base-session header when the reserved original session file is still pending persistence, appends any execution-session records missing from the original session in original execution order, and re-reads the restored file to verify both `base-path` cwd and copied entry identifiers. Runtime is O(n) in combined session-file size. Side effects include session-file creation or append operations for the restored base session.
+ * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original and execution session files must be synchronized.
+ * @return {void} No return value.
+ * @throws {ReqError} Throws when either session file is unreadable or when appended execution records are not persisted to the original session file.
+ * @satisfies REQ-208
+ */
+function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void {
+  const normalizedOriginalSessionFile = path.resolve(plan.originalSessionFile);
+  const normalizedExecutionSessionFile = path.resolve(plan.executionSessionFile);
+  if (normalizedOriginalSessionFile === normalizedExecutionSessionFile) {
+    return;
+  }
+  const executionLines = readPromptSessionJsonLines(normalizedExecutionSessionFile);
+  const executionEntryIds = executionLines
+    .slice(1)
+    .map((line) => line.parsed.id)
+    .filter((entryId): entryId is string => typeof entryId === "string" && entryId !== "");
+  if (!fs.existsSync(normalizedOriginalSessionFile)) {
+    const rewrittenHeader: Record<string, unknown> = {
+      ...executionLines[0]!.parsed,
+      cwd: plan.basePath,
+    };
+    if (
+      typeof rewrittenHeader.parentSession === "string"
+      && path.resolve(rewrittenHeader.parentSession) === normalizedOriginalSessionFile
+    ) {
+      delete rewrittenHeader.parentSession;
+    }
+    try {
+      fs.mkdirSync(path.dirname(normalizedOriginalSessionFile), { recursive: true });
+      const serializedLines = [
+        JSON.stringify(rewrittenHeader),
+        ...executionLines.slice(1).map((line) => line.rawLine),
+      ];
+      fs.writeFileSync(
+        normalizedOriginalSessionFile,
+        `${serializedLines.join("\n")}\n`,
+        "utf8",
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ReqError(
+        `ERROR: Unable to materialize restored session transcript in ${normalizedOriginalSessionFile}: ${errorMessage}.`,
+        1,
+      );
+    }
+  } else {
+    const originalLines = readPromptSessionJsonLines(normalizedOriginalSessionFile);
+    const existingEntryIds = new Set<string>();
+    for (const line of originalLines.slice(1)) {
+      const entryId = line.parsed.id;
+      if (typeof entryId === "string" && entryId !== "") {
+        existingEntryIds.add(entryId);
+      }
+    }
+    const missingExecutionLines = executionLines.slice(1).filter((line) => {
+      const entryId = line.parsed.id;
+      return typeof entryId === "string"
+        && entryId !== ""
+        && !existingEntryIds.has(entryId);
+    });
+    if (missingExecutionLines.length > 0) {
+      const originalRaw = fs.readFileSync(normalizedOriginalSessionFile, "utf8");
+      const leadingSeparator = originalRaw === "" || originalRaw.endsWith("\n") ? "" : "\n";
+      try {
+        fs.appendFileSync(
+          normalizedOriginalSessionFile,
+          `${leadingSeparator}${missingExecutionLines.map((line) => line.rawLine).join("\n")}\n`,
+          "utf8",
+        );
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new ReqError(
+          `ERROR: Unable to preserve execution transcript in ${normalizedOriginalSessionFile}: ${errorMessage}.`,
+          1,
+        );
+      }
+    }
+  }
+  const synchronizedSessionCwd = readPromptSessionFileCwd(normalizedOriginalSessionFile);
+  if (
+    typeof synchronizedSessionCwd !== "string"
+    || path.resolve(synchronizedSessionCwd) !== path.resolve(plan.basePath)
+  ) {
+    throw new ReqError(
+      `ERROR: Restored session transcript expected cwd ${path.resolve(plan.basePath)} but observed ${synchronizedSessionCwd ?? "missing"}.`,
+      1,
+    );
+  }
+  const synchronizedEntryIds = new Set<string>();
+  for (const line of readPromptSessionJsonLines(normalizedOriginalSessionFile).slice(1)) {
+    const entryId = line.parsed.id;
+    if (typeof entryId === "string" && entryId !== "") {
+      synchronizedEntryIds.add(entryId);
+    }
+  }
+  const missingSynchronizedIds = executionEntryIds.filter((entryId) => !synchronizedEntryIds.has(entryId));
+  if (missingSynchronizedIds.length > 0) {
+    throw new ReqError(
+      `ERROR: Unable to verify execution transcript preservation for ${normalizedOriginalSessionFile}: missing entries ${missingSynchronizedIds.join(", ")}.`,
+      1,
+    );
+  }
+}
+
 /**
  * @brief Verifies that the active session file and cwd surfaces match one expected prompt-orchestration target.
  * @details Re-reads the persisted session-file header when present plus the host `process.cwd()` and throws on the first mismatch so prompt commands abort before prompt dispatch or prompt-end handling whenever session switching leaves execution attached to the wrong cwd. A missing persisted session file is treated as a non-fatal lazy-persistence state because pi's `SessionManager` writes session files on first assistant flush rather than eagerly during `ctx.switchSession(sessionPath)`; when the file is absent, pi aligns its internal session cwd to the live `process.cwd()`, so verifying `process.cwd()` alone is authoritative in that state. Reads of `ctx.cwd`, `ctx.sessionManager.getCwd()`, and `ctx.sessionManager.getSessionFile()` are advisory only because the pi `ctx.switchSession(sessionPath)` SDK contract does not mutate the handler-scoped `ctx` object, so those probes stay bound to the pre-switch session and a divergent value alone never triggers abort; they only surface a mismatch when they disagree with both the persisted header cwd and the live `process.cwd()`. Runtime is O(p) in aggregate path length plus one session-file header read. No external state is mutated.
@@ -1528,7 +1691,7 @@ export async function abortPromptCommandExecution(
 
 /**
  * @brief Finalizes one matched successful worktree-backed prompt execution.
- * @details Re-verifies persisted execution-session metadata plus worktree artifacts, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
  * @param[in] ctx {PromptCommandSessionContext | undefined} Optional prompt-command context.
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
@@ -1550,6 +1713,9 @@ export async function finalizePromptCommandExecution(
   let verificationErrorMessage: string | undefined;
   try {
     verifyPromptCommandClosureArtifacts(plan);
+    if (plan.worktreePath && plan.worktreeDir && plan.worktreeRootPath) {
+      preservePromptCommandExecutionTranscript(plan);
+    }
   } catch (error) {
     verificationErrorMessage = error instanceof Error ? error.message : String(error);
   }

package/src/core/runtime-project-paths.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Derives runtime-only repository facts.
- * @details Centralizes git-repository probing and repository-root resolution for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
+ * @details Centralizes git-repository probing, repository-root resolution, and active-branch lookup for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
  */
 
 import path from "node:path";
@@ -67,4 +67,24 @@ export function resolveRuntimeGitPath(executionPath: string): string | undefined
   return isSameOrAncestorPath(gitRoot, normalizedExecutionPath) ? gitRoot : undefined;
 }
 
+/**
+ * @brief Resolves the active branch name for one runtime execution path.
+ * @details Resolves the enclosing git work tree from the supplied execution path, reads `git branch --show-current`, and falls back to `unknown` when the path is outside git or HEAD has no branch name. Runtime is dominated by git execution. Side effects include subprocess creation.
+ * @param[in] executionPath {string} Runtime execution path.
+ * @return {string} Active branch name or `unknown` when unavailable.
+ * @satisfies REQ-121, REQ-283
+ */
+export function resolveRuntimeGitBranchName(executionPath: string): string {
+  const gitRoot = resolveRuntimeGitPath(executionPath);
+  if (!gitRoot) {
+    return "unknown";
+  }
+  const result = runGitCapture(["git", "branch", "--show-current"], gitRoot);
+  if (result.error || result.status !== 0) {
+    return "unknown";
+  }
+  const branchName = result.stdout.trim();
+  return branchName === "" ? "unknown" : branchName;
+}
+
 

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.10.0";
+export const VERSION = "0.11.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -279,20 +279,19 @@ function formatProjectConfigPathForMenu(cwd: string): string {
 
 /**
  * @brief Builds the standardized terminal rows appended to every configuration menu.
- * @details Returns the canonical `Reset defaults` row so all configuration menus and descendant selector menus share the same terminal ordering contract without rendering `Save and close`. Runtime is O(1). No external state is mutated.
- * @param[in] options {{ resetDefaultsDescription: string; resetDefaultsValue?: string | undefined }} Menu-specific terminal-row metadata.
+ * @details Returns the canonical value-less `Reset defaults` row so all configuration menus and descendant selector menus share the same terminal ordering contract without rendering `Save and close`. Runtime is O(1). No external state is mutated.
+ * @param[in] options {{ resetDefaultsDescription: string }} Menu-specific terminal-row metadata.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered terminal menu rows.
  * @satisfies REQ-193
  */
 function buildTerminalSettingsMenuChoices(options: {
   resetDefaultsDescription: string;
-  resetDefaultsValue?: string;
 }): PiUsereqSettingsMenuChoice[] {
   return [
     {
       id: "reset-defaults",
       label: "Reset defaults",
-      value: options.resetDefaultsValue ?? "",
+      value: "",
       description: options.resetDefaultsDescription,
     },
   ];
@@ -1356,7 +1355,6 @@ async function selectDebugLogOnStatus(
       description: `Write matching debug entries only while workflow state is ${workflowState}.`,
     })),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: DEFAULT_DEBUG_LOG_ON_STATUS,
       resetDefaultsDescription: "Restore the documented default workflow-state filter.",
     }),
   ], { initialSelectedId: currentValue });
@@ -1444,7 +1442,6 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       debugEnabled,
     )),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: DEFAULT_DEBUG_LOG_ON_STATUS,
       resetDefaultsDescription: "Restore the documented default Debug configuration.",
     }),
   ];
@@ -1794,7 +1791,7 @@ function buildPiNotifyEventLauncherChoice(
 
 /**
  * @brief Builds the shared settings-menu choices for one notification event submenu.
- * @details Serializes completed/interrupted/failed rows with right-aligned `on|off` values, then appends `Reset defaults` and `Save and close` for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
+ * @details Serializes completed/interrupted/failed rows with right-aligned `on|off` values, then appends a value-less `Reset defaults` row for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered event-submenu choice vector.
@@ -1983,7 +1980,7 @@ function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuCh
 
 /**
  * @brief Opens the shared settings-menu selector for Pushover priority.
- * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the notification menus and appends subtree-local `Reset defaults` plus `Save and close` rows. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the notification menus and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] currentPriority {PiNotifyPushoverPriority} Persisted priority value.
  * @return {Promise<PiNotifyPushoverPriority | "reset-defaults" | undefined>} Selected priority, reset action, or `undefined` when cancelled.
@@ -2007,7 +2004,6 @@ async function selectPiNotifyPushoverPriority(
       description: "Send outbound Pushover messages with high priority `1`.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: formatPiNotifyPushoverPriority(getDefaultConfig("")["notify-pushover-priority"]),
       resetDefaultsDescription: "Restore the documented default Pushover priority.",
     }),
   ], { initialSelectedId: String(currentPriority) });
@@ -2088,7 +2084,7 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
 
 /**
  * @brief Opens the shared settings-menu selector for the active sound level.
- * @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and appends subtree-local `Reset defaults` plus `Save and close` rows. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] currentLevel {PiNotifySoundLevel} Currently selected sound level.
  * @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected sound level, reset action, or `undefined` when cancelled.
@@ -2124,7 +2120,6 @@ async function selectPiNotifySoundLevel(
       description: "Use the high-volume sound command when sound delivery is enabled for the current event.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: getDefaultConfig("")["notify-sound"],
       resetDefaultsDescription: "Restore the documented default sound level.",
     }),
   ], { initialSelectedId: currentLevel });
@@ -2923,7 +2918,6 @@ function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig):
       description: "Disable every configurable startup tool for future session starts.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: `${normalizeEnabledPiUsereqTools(undefined).length} defaults`,
       resetDefaultsDescription: "Restore the documented default startup-tool selection.",
     }),
   ];
@@ -2931,7 +2925,7 @@ function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig):
 
 /**
  * @brief Builds the shared settings-menu choices for per-tool startup toggles.
- * @details Exposes every configurable startup tool as one row whose right-side value reports the current enabled state, preserves the documented custom/files/embedded/default-disabled ordering, and appends subtree-local `Reset defaults` plus `Save and close` rows. Runtime is O(t) in configurable-tool count. No external state is mutated.
+ * @details Exposes every configurable startup tool as one row whose right-side value reports the current enabled state, preserves the documented custom/files/embedded/default-disabled ordering, and appends a value-less subtree-local `Reset defaults` row. Runtime is O(t) in configurable-tool count. No external state is mutated.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered per-tool toggle choices.
@@ -2947,7 +2941,6 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
       description: tool.description ?? `Toggle startup activation for ${tool.name}.`,
     })),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: `${normalizeEnabledPiUsereqTools(undefined).length} defaults`,
       resetDefaultsDescription: "Restore the documented default startup-tool selection.",
     }),
   ];
@@ -3149,7 +3142,6 @@ function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenu
       };
     }),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: formatStaticCheckLanguagesSummary(config),
       resetDefaultsDescription: "Restore the documented per-language static-check defaults.",
     }),
   ];
@@ -3175,7 +3167,6 @@ function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsere
       };
     }),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: formatStaticCheckLanguagesSummary(config),
       resetDefaultsDescription: "Restore the documented per-language static-check defaults.",
     }),
   ];
@@ -3201,7 +3192,6 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
         };
       }),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: formatStaticCheckLanguagesSummary(config),
       resetDefaultsDescription: "Restore the documented per-language static-check defaults.",
     }),
   ];
@@ -3471,7 +3461,6 @@ function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoic
       description: "Select one configured source directory to remove from the current configuration.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: `${DEFAULT_SRC_DIRS.join(", ")}`,
       resetDefaultsDescription: "Restore the documented default source-directory configuration.",
     }),
   ];
@@ -3479,7 +3468,7 @@ function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoic
 
 /**
  * @brief Builds the shared settings-menu choices for removing one source-directory entry.
- * @details Exposes every configured `src-dir` entry as one removable row and appends subtree-local `Reset defaults` plus `Save and close` rows. Runtime is O(s) in source-directory count. No external state is mutated.
+ * @details Exposes every configured `src-dir` entry as one removable row and appends a value-less subtree-local `Reset defaults` row. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered removable source-directory choices.
  * @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
@@ -3493,7 +3482,6 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
       description: `Remove the source-directory entry ${entry} from the current configuration.`,
     })),
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsValue: `${DEFAULT_SRC_DIRS.join(", ")}`,
       resetDefaultsDescription: "Restore the documented default source-directory configuration.",
     }),
   ];
@@ -3764,7 +3752,7 @@ function registerConfigCommands(
  * optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-148, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247
+ * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();

package/tests/debug-extension-harness.test.ts

@@ -225,13 +225,19 @@ test("replaySessionStart captures active tools, statuses, and cwd semantics", as
     const report = await replaySessionStart(projectBase);
     const status = report.ui.statuses["pi-usereq"] ?? "";
 
+    const expectedBranch = spawnSync("git", ["branch", "--show-current"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    }).stdout.trim() || "unknown";
+    const escapedBranch = expectedBranch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
     assert.deepEqual([...report.activeTools].sort(), ["files-tokens", "static-check"]);
     assert.equal(report.effectiveCtxCwd, projectBase);
     assert.equal(report.effectiveProcessCwd, projectBase);
-    const normalizedBasePath = projectBase.split(path.sep).join("/");
     assert.match(status, /<accent>status:<\/accent><warning>idle<\/warning>/);
-    assert.match(status, new RegExp(`<accent>current-path:</accent><warning>${normalizedBasePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}</warning>`));
-    assert.match(status, /<accent>context:<\/accent><warning>▕_▏<\/warning>/);
+    assert.match(status, new RegExp(`<accent>branch:<\\/accent><warning>${escapedBranch}<\\/warning>`));
+    assert.doesNotMatch(status, /<accent>current-path:<\/accent>/);
+    assert.match(status, /<accent>context:<\/accent>▕_▏/);
     assert.match(status, /<accent>elapsed:<\/accent><warning>⏱︎ --:-- ⚑ --:-- ⌛︎--:--<\/warning>/);
     assert.match(status, /<accent>sound:<\/accent><warning>none<\/warning>/);
     assert.doesNotMatch(status, /<accent>beep:<\/accent>/);