pi-usereq 0.11.0 → 0.12.0

package/tests/extension-registration.test.ts

@@ -5,6 +5,13 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import piUsereqExtension from "../src/index.ts";
+import {
+  REQ_REFERENCES_COMMAND_DESCRIPTION,
+  REQ_REFERENCES_COMMIT_MESSAGE,
+} from "../src/core/req-references-command.js";
+import {
+  REQ_RESET_COMMAND_DESCRIPTION,
+} from "../src/core/req-reset-command.js";
 import {
   createStaticCheckLanguageConfig,
   DEFAULT_DOCS_DIR,
@@ -45,9 +52,11 @@ import {
 } from "../src/core/pi-usereq-tools.js";
 import {
   createPiUsereqStatusController,
+  renderPiUsereqStatus,
   setPiUsereqStatusConfig,
   setPiUsereqWorkflowState,
 } from "../src/core/extension-status.js";
+import { showPiUsereqSettingsMenu } from "../src/core/settings-menu.js";
 import { getSupportedStaticCheckLanguageSupport } from "../src/core/static-check.js";
 import { createTempDir, initFixtureRepo } from "./helpers.js";
 
@@ -429,7 +438,7 @@ function buildExpectedFakeBranchValue(basePath: string | undefined): string {
 
 /**
  * @brief Builds the expected fake context-gauge payload for assertions.
- * @details Resolves the documented icon thresholds for `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75-<90`, emits the non-blinking error full icon for `>=90-<100`, and emits the blinking error full icon for `>=100`. Runtime is O(1). No external state is mutated.
+ * @details Resolves the documented icon thresholds for `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75-<90`, renders those non-error bands with the same `warning` token used by the `status` value, emits the non-blinking error full icon for `>=90-<100`, and emits the blinking error full icon for `>=100`. Runtime is O(1). No external state is mutated.
  * @param[in] options {{ filledCells: number; percent?: number | null }} Expected context-gauge facts.
  * @return {string} Encoded context-gauge string.
  */
@@ -439,7 +448,7 @@ function buildExpectedFakeContextBar(options: {
 }): string {
   const percent = options.percent;
   if (percent === undefined || percent === null || percent <= 0) {
-    return "▕_▏";
+    return formatFakeThemeForeground("warning", "▕_▏");
   }
   if (percent >= 100) {
     return formatFakeThemeForeground("error", "\u001b[5m▕█▏\u001b[25m");
@@ -448,15 +457,15 @@ function buildExpectedFakeContextBar(options: {
     return formatFakeThemeForeground("error", "▕█▏");
   }
   if (percent < 25) {
-    return "▕▂▏";
+    return formatFakeThemeForeground("warning", "▕▂▏");
   }
   if (percent < 50) {
-    return "▕▄▏";
+    return formatFakeThemeForeground("warning", "▕▄▏");
   }
   if (percent < 75) {
-    return "▕▆▏";
+    return formatFakeThemeForeground("warning", "▕▆▏");
   }
-  return "▕█▏";
+  return formatFakeThemeForeground("warning", "▕█▏");
 }
 
 /**
@@ -785,6 +794,7 @@ test("extension registers prompt and config commands while exposing tool capabil
     "req-recreate",
     "req-refactor",
     "req-references",
+    "req-reset",
     "req-renumber",
     "req-workflow",
     "req-write",
@@ -795,9 +805,10 @@ test("extension registers prompt and config commands while exposing tool capabil
 
   for (const name of [
     "files-tokens",
-    "files-references",
+    "files-summarize",
     "files-compress",
     "files-search",
+    "summarize",
     "references",
     "compress",
     "search",
@@ -813,9 +824,10 @@ test("extension registers prompt and config commands while exposing tool capabil
   const toolNames = pi.tools.map((tool: RegisteredTool) => tool.name).sort();
   for (const name of [
     "files-tokens",
-    "files-references",
+    "files-summarize",
     "files-compress",
     "files-search",
+    "summarize",
     "references",
     "compress",
     "search",
@@ -827,6 +839,46 @@ test("extension registers prompt and config commands while exposing tool capabil
   }
 });
 
+/**
+ * @brief Verifies `req-references` registration is independent from bundled prompt inventory.
+ * @details Confirms `references` is absent from `PROMPT_COMMAND_NAMES` while extension activation still registers `req-references` with the fixed dedicated description. Runtime is O(1). Side effects are limited to extension registration.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when `references` remains in the bundled prompt inventory or the command description diverges.
+ * @satisfies TST-102
+ */
+test("req-references registers outside the bundled prompt inventory and keeps its dedicated description", () => {
+  const bundledPromptNames = PROMPT_COMMAND_NAMES as readonly string[];
+  assert.equal(bundledPromptNames.includes("references"), false);
+
+  const pi = createFakePi();
+  piUsereqExtension(pi);
+
+  assert.equal(
+    pi.commands.get("req-references")?.description,
+    REQ_REFERENCES_COMMAND_DESCRIPTION,
+  );
+});
+
+/**
+ * @brief Verifies `req-reset` registration is independent from bundled prompt inventory.
+ * @details Confirms `reset` is absent from `PROMPT_COMMAND_NAMES` while extension activation still registers `req-reset` with the fixed dedicated description. Runtime is O(1). Side effects are limited to extension registration.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when `reset` remains in the bundled prompt inventory or the command description diverges.
+ * @satisfies TST-105
+ */
+test("req-reset registers outside the bundled prompt inventory and keeps its dedicated description", () => {
+  const bundledPromptNames = PROMPT_COMMAND_NAMES as readonly string[];
+  assert.equal(bundledPromptNames.includes("reset"), false);
+
+  const pi = createFakePi();
+  piUsereqExtension(pi);
+
+  assert.equal(
+    pi.commands.get("req-reset")?.description,
+    REQ_RESET_COMMAND_DESCRIPTION,
+  );
+});
+
 test("token tools register agent-oriented descriptions and schema details", () => {
   const pi = createFakePi();
   piUsereqExtension(pi);
@@ -845,24 +897,37 @@ test("token tools register agent-oriented descriptions and schema details", () =
   assert.match(String((tokens.parameters as { description?: string } | undefined)?.description ?? ""), /monolithic pack-summary text/);
 });
 
-test("reference tools register agent-oriented descriptions and schema details", () => {
+test("summary tools register agent-oriented descriptions and schema details", () => {
+  const pi = createFakePi();
+  piUsereqExtension(pi);
+
+  const filesSummarize = pi.tools.find((tool: RegisteredTool) => tool.name === "files-summarize");
+  const summarize = pi.tools.find((tool: RegisteredTool) => tool.name === "summarize");
+  assert.ok(filesSummarize, "missing files-summarize tool");
+  assert.ok(summarize, "missing summarize tool");
+
+  assert.match(filesSummarize.description ?? "", /monolithic summary markdown report/);
+  assert.ok(filesSummarize.promptGuidelines?.some((line) => line.includes("monolithic markdown")));
+  assert.ok(filesSummarize.promptGuidelines?.some((line) => line.includes("Formatting contract:")));
+  assert.match(String((filesSummarize.parameters as { description?: string } | undefined)?.description ?? ""), /monolithic markdown/);
+
+  assert.match(summarize.description ?? "", /configured project source directories/);
+  assert.ok(summarize.promptGuidelines?.some((line) => line.includes("file-structure markdown block")));
+  assert.ok(summarize.promptGuidelines?.some((line) => line.includes("Configuration contract:")));
+  assert.match(String((summarize.parameters as { description?: string } | undefined)?.description ?? ""), /monolithic markdown/);
+});
+
+test("references tool registers agent-oriented descriptions and schema details", () => {
   const pi = createFakePi();
   piUsereqExtension(pi);
 
-  const filesReferences = pi.tools.find((tool: RegisteredTool) => tool.name === "files-references");
   const references = pi.tools.find((tool: RegisteredTool) => tool.name === "references");
-  assert.ok(filesReferences, "missing files-references tool");
   assert.ok(references, "missing references tool");
 
-  assert.match(filesReferences.description ?? "", /monolithic references markdown report/);
-  assert.ok(filesReferences.promptGuidelines?.some((line) => line.includes("monolithic markdown")));
-  assert.ok(filesReferences.promptGuidelines?.some((line) => line.includes("Formatting contract:")));
-  assert.match(String((filesReferences.parameters as { description?: string } | undefined)?.description ?? ""), /monolithic markdown/);
-
-  assert.match(references.description ?? "", /configured project source directories/);
-  assert.ok(references.promptGuidelines?.some((line) => line.includes("file-structure markdown block")));
-  assert.ok(references.promptGuidelines?.some((line) => line.includes("Configuration contract:")));
-  assert.match(String((references.parameters as { description?: string } | undefined)?.description ?? ""), /monolithic markdown/);
+  assert.match(references.description ?? "", /configured project source directories and configured docs-dir/);
+  assert.ok(references.promptGuidelines?.some((line) => line.includes("overwrite `<docs-dir>/REFERENCES.md`")));
+  assert.ok(references.promptGuidelines?.some((line) => line.includes("generated markdown is never returned")));
+  assert.match(String((references.parameters as { description?: string } | undefined)?.description ?? ""), /content\[0\]\.text returns only `success` or `error: <diagnostic>`/);
 });
 
 test("search tools register agent-oriented descriptions and schema details", () => {
@@ -913,9 +978,10 @@ test("agent tools define custom renderResult with compact and expanded structure
     piUsereqExtension(pi);
     const toolNames = [
       "files-tokens",
-      "files-references",
+      "files-summarize",
       "files-compress",
       "files-search",
+      "summarize",
       "references",
       "compress",
       "search",
@@ -963,7 +1029,7 @@ test("files-tokens returns monolithic token summary text with execution diagnost
     docs: {
       "REQUIREMENTS.md": "---\ntitle: Requirements\n---\n# Requirements\nAlpha\nBeta\n",
       "WORKFLOW.md": "# Workflow\nStep one\n",
-      "REFERENCES.md": "# References\nEntry one\n",
+      "REFERENCES.md": "# Summarize\nEntry one\n",
     },
   });
   try {
@@ -1011,7 +1077,7 @@ test("files-tokens defers js-tiktoken loading until execution and returns monoli
   }
 });
 
-test("files-references returns monolithic references markdown", async () => {
+test("files-summarize returns monolithic summary markdown", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
   const samplePath = path.join(projectBase, "src", "sample.ts");
   fs.writeFileSync(samplePath, `/**
@@ -1032,7 +1098,7 @@ export function buildSample(input: string): string {
   try {
     const pi = createFakePi();
     piUsereqExtension(pi);
-    const result = await executeRegisteredTool(pi, "files-references", projectBase, {
+    const result = await executeRegisteredTool(pi, "files-summarize", projectBase, {
       files: ["src/sample.ts", "src/missing.ts"],
     }) as {
       content?: Array<{ type: string; text?: string }>;
@@ -1051,7 +1117,7 @@ export function buildSample(input: string): string {
   }
 });
 
-test("references returns monolithic project references markdown", async () => {
+test("summarize returns monolithic project summary markdown", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
   fs.writeFileSync(path.join(projectBase, "src", "alpha.ts"), "export const ALPHA = 1;\n", "utf8");
   fs.mkdirSync(path.join(projectBase, "src", "nested"), { recursive: true });
@@ -1059,7 +1125,7 @@ test("references returns monolithic project references markdown", async () => {
   try {
     const pi = createFakePi();
     piUsereqExtension(pi);
-    const result = await executeRegisteredTool(pi, "references", projectBase, {}) as {
+    const result = await executeRegisteredTool(pi, "summarize", projectBase, {}) as {
       content?: Array<{ type: string; text?: string }>;
       details?: { execution: { code: number; stderr_lines?: string[] } };
     };
@@ -1077,6 +1143,85 @@ test("references returns monolithic project references markdown", async () => {
   }
 });
 
+test("references overwrites the configured REFERENCES.md and returns status-only success", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  fs.writeFileSync(path.join(projectBase, "src", "alpha.ts"), "export const ALPHA = 1;\n", "utf8");
+  fs.mkdirSync(path.join(projectBase, "src", "nested"), { recursive: true });
+  fs.writeFileSync(path.join(projectBase, "src", "nested", "beta.ts"), "export function beta(): number {\n  return 2;\n}\n", "utf8");
+  const docsDir = path.join(projectBase, "docs", "custom");
+  fs.mkdirSync(docsDir, { recursive: true });
+  fs.writeFileSync(path.join(docsDir, "REFERENCES.md"), "stale\n", "utf8");
+  const configPath = getProjectConfigPath(projectBase);
+  const config = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>;
+  config["docs-dir"] = "docs/custom";
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const referencesResult = await executeRegisteredTool(pi, "references", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+      details?: { execution: { code: number; stderr_lines?: string[]; stdout_lines?: string[] } };
+    };
+    const summarizeResult = await executeRegisteredTool(pi, "summarize", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+
+    const referencesPath = path.join(docsDir, "REFERENCES.md");
+    const writtenText = fs.readFileSync(referencesPath, "utf8");
+    assert.equal(referencesResult.content?.[0]?.text ?? "", "success");
+    assert.equal(writtenText.trimEnd(), summarizeResult.content?.[0]?.text ?? "");
+    assert.doesNotMatch(writtenText, /^stale$/m);
+    assert.equal(referencesResult.details?.execution.code, 0);
+    assert.deepEqual(referencesResult.details?.execution.stderr_lines, undefined);
+    assert.deepEqual(referencesResult.details?.execution.stdout_lines, undefined);
+  } finally {
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+test("references returns status-only errors for source-discovery and write failures", async () => {
+  const sourceFailure = initFixtureRepo({ fixtures: [] });
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const result = await executeRegisteredTool(pi, "references", sourceFailure.projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+      details?: { execution: { code: number; stderr_lines?: string[]; stdout_lines?: string[] } };
+    };
+
+    assert.equal(result.content?.[0]?.text ?? "", "error: no source files found in configured directories.");
+    assert.equal(result.details?.execution.code, 1);
+    assert.deepEqual(result.details?.execution.stdout_lines, undefined);
+    assert.ok(result.details?.execution.stderr_lines?.some((line) => line.includes("no source files found in configured directories.")));
+  } finally {
+    fs.rmSync(sourceFailure.projectBase, { recursive: true, force: true });
+  }
+
+  const writeFailure = initFixtureRepo({ fixtures: [] });
+  fs.writeFileSync(path.join(writeFailure.projectBase, "src", "alpha.ts"), "export const ALPHA = 1;\n", "utf8");
+  const writeFailureConfigPath = getProjectConfigPath(writeFailure.projectBase);
+  const writeFailureConfig = JSON.parse(fs.readFileSync(writeFailureConfigPath, "utf8")) as Record<string, unknown>;
+  writeFailureConfig["docs-dir"] = "docs/missing/custom";
+  fs.writeFileSync(writeFailureConfigPath, `${JSON.stringify(writeFailureConfig, null, 2)}\n`, "utf8");
+
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const result = await executeRegisteredTool(pi, "references", writeFailure.projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+      details?: { execution: { code: number; stderr_lines?: string[]; stdout_lines?: string[] } };
+    };
+
+    assert.match(result.content?.[0]?.text ?? "", /^error: ENOENT:/);
+    assert.equal(result.details?.execution.code, 1);
+    assert.deepEqual(result.details?.execution.stdout_lines, undefined);
+    assert.ok(result.details?.execution.stderr_lines?.some((line) => /^error: ENOENT:/.test(line)));
+  } finally {
+    fs.rmSync(writeFailure.projectBase, { recursive: true, force: true });
+  }
+});
+
 test("files-compress returns monolithic compression markdown", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
   const samplePath = path.join(projectBase, "src", "sample.ts");
@@ -1264,21 +1409,21 @@ func (s *Server) Start(ctx context.Context) error {
     const pi = createFakePi();
     piUsereqExtension(pi);
 
-    const filesReferencesResult = await executeRegisteredTool(pi, "files-references", projectBase, {
+    const filesSummarizeResult = await executeRegisteredTool(pi, "files-summarize", projectBase, {
       files: ["src/sample.go"],
     }) as {
       content?: Array<{ type: string; text?: string }>;
       details?: { execution: { code: number } };
     };
-    assert.match(filesReferencesResult.content?.[0]?.text ?? "", /\tvar buffer bytes\.Buffer/);
-    assert.equal(filesReferencesResult.details?.execution.code, 0);
+    assert.match(filesSummarizeResult.content?.[0]?.text ?? "", /\tvar buffer bytes\.Buffer/);
+    assert.equal(filesSummarizeResult.details?.execution.code, 0);
 
-    const referencesResult = await executeRegisteredTool(pi, "references", projectBase, {}) as {
+    const summarizeResult = await executeRegisteredTool(pi, "summarize", projectBase, {}) as {
       content?: Array<{ type: string; text?: string }>;
       details?: { execution: { code: number } };
     };
-    assert.match(referencesResult.content?.[0]?.text ?? "", /\tvar buffer bytes\.Buffer/);
-    assert.equal(referencesResult.details?.execution.code, 0);
+    assert.match(summarizeResult.content?.[0]?.text ?? "", /\tvar buffer bytes\.Buffer/);
+    assert.equal(summarizeResult.details?.execution.code, 0);
 
     const filesCompressResult = await executeRegisteredTool(pi, "files-compress", projectBase, {
       files: ["src/sample.go"],
@@ -1501,12 +1646,12 @@ test("configuration menus expose show-config ordering and omit overview or notif
   assert.ok(renderedMenu.includes("disable"));
   assert.doesNotMatch(renderedMenu, /beep:/);
   assert.match(renderedNotificationsMenu, /<dim>Enable pushover/);
-  assert.match(renderedNotificationsMenu, /<dim>off<\/dim>/);
+  assert.match(renderedNotificationsMenu, /<dim>configure user\/token keys first<\/dim>/);
   assert.deepEqual(ctx.__state.selectCalls[1]?.items ?? [], [
     "Enable notification",
     "Notification events",
     "Notify command",
-    "Enable sound",
+    "Enable sound (boot value)",
     "Sound events",
     "Sound toggle hotkey bind",
     "Sound command (low vol.)",
@@ -1556,7 +1701,7 @@ test("descendant configuration menus end with Reset defaults only", async () =>
   const ctx = createFakeCtx(cwd, {
     selects: [
       "notifications",
-      "Enable sound",
+      "Enable sound (boot value)",
       "Save and close",
       "Pushover priority",
       "Save and close",
@@ -1599,14 +1744,14 @@ test("descendant configuration menus end with Reset defaults only", async () =>
     return (ctx.__state.customRenderLines[index] ?? []).join("\n");
   };
 
-  assert.deepEqual(getTerminalRows("Enable sound", "high"), ["Reset defaults"]);
+  assert.deepEqual(getTerminalRows("Enable sound (boot value)", "high"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("Pushover priority", "High"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("Enable tools", "static-check"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("Debug", "Log on status"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("static-check language", "Python"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("Remove static code checker"), ["Reset defaults"]);
   assert.deepEqual(getTerminalRows("Remove source-code directory", "src"), ["Reset defaults"]);
-  assert.doesNotMatch(getRenderedMenu("Enable sound", "high"), /Reset defaults.*none/);
+  assert.doesNotMatch(getRenderedMenu("Enable sound (boot value)", "high"), /Reset defaults.*none/);
   assert.doesNotMatch(getRenderedMenu("Pushover priority", "High"), /Reset defaults.*Normal/);
   assert.doesNotMatch(getRenderedMenu("Enable tools", "static-check"), /Reset defaults.*defaults/);
   assert.doesNotMatch(getRenderedMenu("Debug", "Log on status"), /Reset defaults.*running/);
@@ -1917,6 +2062,101 @@ test("notifications menu preserves focus on toggled and edited rows", async () =
   assert.equal(notificationEventCalls[1]?.selectedChoiceId, "notify-on-failed");
 });
 
+/**
+ * @brief Verifies inline toggle rows stay open and preserve selection for confirm keys.
+ * @details Builds one shared settings-menu instance with a primary inline toggle and a dependent secondary row whose disabled styling changes after each toggle. The test proves `space` and `enter` must mutate the selected row in place, rebuild dependent rows without closing the menu, and preserve focus on the toggled row until explicit cancel.
+ * @return {Promise<void>} Promise resolved after the raw-input interaction sequence completes.
+ * @throws {AssertionError} Throws when the menu closes early, loses focus, or fails to rebuild dependent row styling after a toggle.
+ * @satisfies REQ-192, TST-052
+ */
+test("shared settings menu keeps inline toggles focused and open for space and enter", async () => {
+  let primaryEnabled = true;
+  let component:
+    | {
+      handleInput?: (data: string) => void;
+      render: (width: number) => string[];
+    }
+    | undefined;
+  let resolved = false;
+  const changes: string[] = [];
+  const theme = {
+    fg: (color: string, text: string) => formatFakeThemeForeground(color, text),
+    bgFromFg: (color: string, text: string) => formatFakeThemeBackgroundFromForeground(color, text),
+    bold: (text: string) => `<bold>${text}</bold>`,
+  };
+  const ctx = {
+    ui: {
+      async custom<T>(factory: (tui: { requestRender: () => void }, customTheme: typeof theme, keybindings: Record<string, never>, done: (value?: T) => void) => unknown) {
+        let resolveResult!: (value: T | undefined) => void;
+        const resultPromise = new Promise<T | undefined>((resolve) => {
+          resolveResult = (value?: T) => {
+            resolved = true;
+            resolve(value);
+          };
+        });
+        component = factory(
+          { requestRender: () => undefined },
+          theme,
+          {},
+          (value?: T) => resolveResult(value),
+        ) as typeof component;
+        return resultPromise;
+      },
+    },
+  } as any;
+  const buildChoices = () => [
+    {
+      id: "primary",
+      label: "Primary",
+      value: primaryEnabled ? "enable" : "disable",
+      values: ["enable", "disable"],
+      description: "Toggle the primary row in place.",
+    },
+    {
+      id: "secondary",
+      label: "Secondary",
+      labelTone: primaryEnabled ? undefined : "dim",
+      value: primaryEnabled ? "editable" : "locked",
+      valueTone: primaryEnabled ? undefined : "dim",
+      disabled: !primaryEnabled,
+      description: "Dependent row that must rebuild without closing the menu.",
+    },
+  ] as any;
+
+  const resultPromise = showPiUsereqSettingsMenu(
+    ctx,
+    "Toggle menu",
+    buildChoices(),
+    {
+      getChoices: buildChoices,
+      onChange: (choiceId: string, newValue: string) => {
+        if (choiceId === "primary") {
+          primaryEnabled = newValue === "enable";
+          changes.push(newValue);
+        }
+      },
+    } as any,
+  );
+
+  assert.ok(component);
+  assert.doesNotMatch(component.render(120).join("\n"), /<dim>Secondary/);
+
+  component.handleInput?.(" ");
+  await Promise.resolve();
+  assert.deepEqual(changes, ["disable"]);
+  assert.equal(resolved, false);
+  assert.match(component.render(120).join("\n"), /<dim>Secondary/);
+
+  component.handleInput?.("\r");
+  await Promise.resolve();
+  assert.deepEqual(changes, ["disable", "enable"]);
+  assert.equal(resolved, false);
+  assert.doesNotMatch(component.render(120).join("\n"), /<dim>Secondary/);
+
+  component.handleInput?.("\x1b");
+  assert.equal(await resultPromise, undefined);
+});
+
 test("notifications reset defaults preserves non-notification settings", async () => {
   const cwd = createTempDir("pi-usereq-menu-reset-notifications-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
@@ -1929,7 +2169,7 @@ test("notifications reset defaults preserves non-notification settings", async (
       "docs-dir",
       "notifications",
       "Enable notification",
-      "Enable sound",
+      "Enable sound (boot value)",
       "high",
       "Reset defaults",
       "Approve reset",
@@ -2033,6 +2273,376 @@ test("prompt commands use the current session by default", async () => {
   }
 });
 
+/**
+ * @brief Verifies successful `req-references` completion uses the specialized direct commit workflow.
+ * @details Confirms the command regenerates configured `REFERENCES.md`, creates no worktree, sends no LLM user message, stages only the target file, commits the fixed message, and restores workflow state `idle`. Runtime is dominated by temporary git execution and reference generation. Side effects are limited to temporary repository mutation and command-handler notifications.
+ * @return {Promise<void>} Promise resolved after success-path assertions complete.
+ * @throws {AssertionError} Throws when `req-references` creates a worktree, starts a session handoff, skips the fixed commit, or leaves the repository dirty.
+ * @satisfies TST-103
+ */
+test("req-references updates REFERENCES.md with a direct commit workflow and no LLM session", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    fs.writeFileSync(path.join(projectBase, "src", "alpha.ts"), "export const ALPHA = 1;\n", "utf8");
+    fs.mkdirSync(path.join(projectBase, "src", "nested"), { recursive: true });
+    fs.writeFileSync(path.join(projectBase, "src", "nested", "beta.ts"), "export function beta(): number {\n  return 2;\n}\n", "utf8");
+    const docsDir = path.join(projectBase, "docs", "custom");
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, "REFERENCES.md"), "stale\n", "utf8");
+    writeProjectConfigOverrides(projectBase, { "docs-dir": "docs/custom" });
+    assert.equal(spawnSync("git", ["add", "src/alpha.ts", "src/nested/beta.ts", "docs/custom/REFERENCES.md"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    }).status, 0);
+    const fixtureCommit = spawnSync("git", ["commit", "-m", "fixture sources"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    });
+    assert.equal(fixtureCommit.status, 0, fixtureCommit.stderr);
+
+    const worktreeParentPath = path.dirname(projectBase);
+    const initialEntries = new Set(fs.readdirSync(worktreeParentPath));
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+    const recordedStatuses: string[] = [];
+    let switchSessionCalls = 0;
+    const originalSetStatus = ctx.ui.setStatus.bind(ctx.ui);
+    const originalSwitchSession = ctx.switchSession.bind(ctx);
+    ctx.ui.setStatus = (key: string, value?: string) => {
+      if (key === "pi-usereq" && value !== undefined) {
+        recordedStatuses.push(value);
+      }
+      originalSetStatus(key, value);
+    };
+    ctx.switchSession = async (sessionPath: string) => {
+      switchSessionCalls += 1;
+      return originalSwitchSession(sessionPath);
+    };
+
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    await pi.commands.get("req-references")!.handler("", ctx);
+
+    const summarizeResult = await executeRegisteredTool(pi, "summarize", projectBase, {}) as {
+      content?: Array<{ type?: string; text?: string }>;
+    };
+    const referencesPath = path.join(docsDir, "REFERENCES.md");
+    const writtenText = fs.readFileSync(referencesPath, "utf8");
+    const lastCommitMessage = spawnSync("git", ["log", "-1", "--pretty=%s"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    }).stdout.trim();
+    const committedPaths = spawnSync("git", ["diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    }).stdout.trim().split(/\r?\n/).filter((line) => line !== "");
+    const createdWorktreeEntries = fs.readdirSync(worktreeParentPath)
+      .filter((entry) => !initialEntries.has(entry))
+      .filter((entry) => /^PI-useReq-/.test(entry));
+    const finalStatus = ctx.__state.statuses.get("pi-usereq") ?? "";
+
+    assert.equal(pi.sentUserMessages.length, 0);
+    assert.equal(switchSessionCalls, 0);
+    assert.deepEqual(createdWorktreeEntries, []);
+    assert.equal(writtenText.trimEnd(), summarizeResult.content?.[0]?.text ?? "");
+    assert.doesNotMatch(writtenText, /^stale$/m);
+    assert.equal(lastCommitMessage, REQ_REFERENCES_COMMIT_MESSAGE);
+    assert.deepEqual(committedPaths, ["docs/custom/REFERENCES.md"]);
+    assert.equal(
+      spawnSync("git", ["status", "--porcelain"], { cwd: projectBase, encoding: "utf8" }).stdout.trim(),
+      "",
+    );
+    assert.ok(ctx.__state.notifications.some((entry) => /SUCCESS: Updated .*REFERENCES\.md/.test(entry.message)));
+    assert.ok(recordedStatuses.some((status) => /<accent>status:<\/accent><warning>running<\/warning>/.test(status)));
+    assert.ok(recordedStatuses.every((status) => !/<accent>status:<\/accent><warning>merging<\/warning>/.test(status)));
+    assert.equal(
+      finalStatus,
+      buildExpectedFakeStatusText({
+        workflowState: "idle",
+        basePath: buildExpectedFakeBasePath(projectBase),
+        docsDir: "docs/custom",
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies failing `req-references` runs report errors without session handoff.
+ * @details Covers both git-preflight failure and reference-generation failure, proving the command creates no worktree, sends no LLM message, transitions workflow state to `error`, and preserves the previous git commit when execution aborts. Runtime is dominated by temporary repository setup plus failing command invocations. Side effects are limited to temporary filesystem and git mutation inside fixture repositories.
+ * @return {Promise<void>} Promise resolved after failure-path assertions complete.
+ * @throws {AssertionError} Throws when `req-references` hides failures, mutates history, or attempts prompt-session orchestration.
+ * @satisfies TST-104
+ */
+test("req-references surfaces git-validation and reference-generation failures without session handoff", async () => {
+  const gitFailure = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    fs.writeFileSync(path.join(gitFailure.projectBase, "DIRTY.txt"), "dirty\n", "utf8");
+    const worktreeParentPath = path.dirname(gitFailure.projectBase);
+    const initialEntries = new Set(fs.readdirSync(worktreeParentPath));
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(gitFailure.projectBase);
+
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    await assert.rejects(
+      pi.commands.get("req-references")!.handler("", ctx),
+      /ERROR: Git status unclear!/,
+    );
+
+    const createdWorktreeEntries = fs.readdirSync(worktreeParentPath)
+      .filter((entry) => !initialEntries.has(entry))
+      .filter((entry) => /^PI-useReq-/.test(entry));
+    assert.equal(pi.sentUserMessages.length, 0);
+    assert.deepEqual(createdWorktreeEntries, []);
+    assert.ok(ctx.__state.notifications.some((entry) => /ERROR: Git status unclear!/.test(entry.message)));
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(gitFailure.projectBase),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+    assert.equal(
+      spawnSync("git", ["log", "-1", "--pretty=%s"], {
+        cwd: gitFailure.projectBase,
+        encoding: "utf8",
+      }).stdout.trim(),
+      "init",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(gitFailure.projectBase, { recursive: true, force: true });
+  }
+
+  const sourceFailure = initFixtureRepo({ fixtures: [] });
+  try {
+    const worktreeParentPath = path.dirname(sourceFailure.projectBase);
+    const initialEntries = new Set(fs.readdirSync(worktreeParentPath));
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(sourceFailure.projectBase);
+    const recordedStatuses: string[] = [];
+    const originalSetStatus = ctx.ui.setStatus.bind(ctx.ui);
+    ctx.ui.setStatus = (key: string, value?: string) => {
+      if (key === "pi-usereq" && value !== undefined) {
+        recordedStatuses.push(value);
+      }
+      originalSetStatus(key, value);
+    };
+
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    await assert.rejects(
+      pi.commands.get("req-references")!.handler("", ctx),
+      /no source files found in configured directories/,
+    );
+
+    const createdWorktreeEntries = fs.readdirSync(worktreeParentPath)
+      .filter((entry) => !initialEntries.has(entry))
+      .filter((entry) => /^PI-useReq-/.test(entry));
+    assert.equal(pi.sentUserMessages.length, 0);
+    assert.deepEqual(createdWorktreeEntries, []);
+    assert.ok(ctx.__state.notifications.some((entry) => /no source files found in configured directories/.test(entry.message)));
+    assert.ok(recordedStatuses.some((status) => /<accent>status:<\/accent><warning>running<\/warning>/.test(status)));
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(sourceFailure.projectBase),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+    assert.equal(
+      spawnSync("git", ["log", "-1", "--pretty=%s"], {
+        cwd: sourceFailure.projectBase,
+        encoding: "utf8",
+      }).stdout.trim(),
+      "init",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(sourceFailure.projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies successful `req-reset` recovers from a non-`idle` worktree-backed prompt state.
+ * @details Starts one worktree-backed `req-change` run until the fake command context remains attached to the execution worktree with workflow state `running`, appends one unique execution-session record, invokes `req-reset` from that non-`idle` state, and verifies transcript preservation, base-path restoration, generated worktree plus branch deletion, unchanged LLM prompt count, success notification, and final workflow state `idle`. Runtime is dominated by temporary git worktree setup plus session-file inspection. Side effects are limited to temporary repository mutation and fake UI notifications.
+ * @return {Promise<void>} Promise resolved after recovery-path assertions complete.
+ * @throws {AssertionError} Throws when `req-reset` rejects the non-`idle` state, loses the execution transcript, leaves generated cleanup artifacts behind, or dispatches an additional LLM prompt.
+ * @satisfies TST-106
+ */
+test("req-reset accepts non-idle workflow state, preserves transcript, and removes generated worktrees", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    const originalSessionFile = ctx.sessionManager.getSessionFile() ?? "";
+    assert.notEqual(originalSessionFile, "");
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+
+    const sentMessageCountBeforeReset = pi.sentUserMessages.length;
+    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    assert.ok(worktreeMatch, promptText);
+    const worktreeName = worktreeMatch?.[1] ?? "";
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+    const executionSessionFile = ctx.sessionManager.getSessionFile() ?? "";
+    const appendedEntryId = "req-reset-transcript-entry";
+
+    assert.notEqual(executionSessionFile, "");
+    assert.notEqual(executionSessionFile, originalSessionFile);
+    assert.equal(ctx.cwd, executionBasePath);
+    assert.equal(process.cwd(), executionBasePath);
+    assert.equal(fs.existsSync(executionBasePath), true);
+    assert.match(
+      ctx.__state.statuses.get("pi-usereq") ?? "",
+      /<accent>status:<\/accent><warning>running<\/warning>/,
+    );
+
+    fs.appendFileSync(
+      executionSessionFile,
+      `${JSON.stringify({
+        type: "custom",
+        id: appendedEntryId,
+        parentId: null,
+        timestamp: new Date(0).toISOString(),
+        customType: "req-reset-test",
+        data: { recovered: true },
+      })}\n`,
+      "utf8",
+    );
+
+    await pi.commands.get("req-reset")!.handler("", ctx);
+
+    assert.equal(pi.sentUserMessages.length, sentMessageCountBeforeReset);
+    assert.equal(ctx.cwd, projectBase);
+    assert.equal(process.cwd(), projectBase);
+    assert.equal(ctx.sessionManager.getSessionFile(), originalSessionFile);
+    assert.equal(fs.existsSync(executionBasePath), false);
+    assert.equal(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      1,
+    );
+    assert.match(fs.readFileSync(originalSessionFile, "utf8"), new RegExp(appendedEntryId));
+    assert.ok(
+      ctx.__state.notifications.some((entry) => /SUCCESS: req-reset/.test(entry.message)),
+    );
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "idle",
+        basePath: buildExpectedFakeBasePath(projectBase),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies failing `req-reset` surfaces restoration errors without starting new worktree or LLM execution.
+ * @details Starts one worktree-backed `req-change` run until the fake command context remains attached to the execution worktree, forces the subsequent base-path restoration switch to return `cancelled`, invokes `req-reset` from that non-`idle` state, and verifies the command reports the restoration failure, leaves the generated worktree plus branch in place for manual recovery, sends no additional LLM prompt, and transitions workflow state to `error`. Runtime is dominated by temporary git worktree setup. Side effects are limited to temporary repository mutation and fake UI notifications.
+ * @return {Promise<void>} Promise resolved after failure-path assertions complete.
+ * @throws {AssertionError} Throws when `req-reset` hides restoration failures, creates new cleanup artifacts, or clears the generated worktree plus branch despite the failed restore.
+ * @satisfies TST-107
+ */
+test("req-reset surfaces restoration failures and transitions workflow state to error", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    const originalSessionFile = ctx.sessionManager.getSessionFile() ?? "";
+    assert.notEqual(originalSessionFile, "");
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+
+    const sentMessageCountBeforeReset = pi.sentUserMessages.length;
+    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    assert.ok(worktreeMatch, promptText);
+    const worktreeName = worktreeMatch?.[1] ?? "";
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+
+    assert.match(
+      ctx.__state.statuses.get("pi-usereq") ?? "",
+      /<accent>status:<\/accent><warning>running<\/warning>/,
+    );
+
+    ctx.switchSession = async (_sessionPath: string) => ({ cancelled: true });
+
+    await assert.rejects(
+      pi.commands.get("req-reset")!.handler("", ctx),
+      /Session switch cancelled/,
+    );
+
+    assert.equal(pi.sentUserMessages.length, sentMessageCountBeforeReset);
+    assert.equal(ctx.cwd, executionBasePath);
+    assert.equal(process.cwd(), executionBasePath);
+    assert.equal(fs.existsSync(executionBasePath), true);
+    assert.equal(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    assert.ok(
+      ctx.__state.notifications.some((entry) => /Session switch cancelled/.test(entry.message)),
+    );
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(executionBasePath),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
 test("prompt commands skip worktree creation when auto git commit is disabled", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
   try {
@@ -2060,35 +2670,102 @@ test("prompt commands skip worktree creation when auto git commit is disabled",
   }
 });
 
-test("prompt commands capture checking before handoff and running at prompt injection", async () => {
+test("prompt commands capture checking before handoff and running at prompt injection", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  let checkingStatus = "";
+  let handoffStatus = "";
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+    const originalSendUserMessage = pi.sendUserMessage.bind(pi);
+    pi.sendUserMessage = (content: unknown, options?: unknown) => {
+      handoffStatus = ctx.__state.statuses.get("pi-usereq") ?? "";
+      originalSendUserMessage(content, options);
+    };
+    setPromptCommandPostCreateHookForTests(() => {
+      checkingStatus = ctx.__state.statuses.get("pi-usereq") ?? "";
+    });
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+
+    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    assert.ok(worktreeMatch, promptText);
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+    assert.equal(
+      checkingStatus,
+      buildExpectedFakeStatusText({
+        workflowState: "checking",
+        basePath: buildExpectedFakeBasePath(projectBase),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+    assert.equal(
+      handoffStatus,
+      buildExpectedFakeStatusText({
+        workflowState: "checking",
+        basePath: buildExpectedFakeBasePath(executionBasePath),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "running",
+        basePath: buildExpectedFakeBasePath(executionBasePath),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      }),
+    );
+
+    await pi.emit("before_agent_start", {}, ctx);
+    await pi.emit("agent_start", {}, ctx);
+    await pi.emit("agent_end", {
+      messages: [{ role: "assistant", stopReason: "stop", content: [] }],
+    }, ctx);
+  } finally {
+    setPromptCommandPostCreateHookForTests(undefined);
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies every req command except `req-reset` rejects non-`idle` workflow state and transitions to `error`.
+ * @details Starts one no-worktree `req-change` run until workflow state becomes `running`, invokes `req-analyze` and `req-references` while orchestration remains active, and verifies both handlers reject with deterministic diagnostics, emit error notifications, send no additional LLM prompt, and move the shared workflow state to `error` before `agent_end` restores `idle`. Runtime is dominated by temporary project setup plus fake lifecycle dispatch. Side effects are limited to temporary filesystem mutation and fake UI notifications.
+ * @return {Promise<void>} Promise resolved after rejection-path assertions complete.
+ * @throws {AssertionError} Throws when a busy req command starts new orchestration, skips the error transition, or prevents the active no-worktree prompt from returning to `idle`.
+ * @satisfies TST-068
+ */
+test("req commands except req-reset reject non-idle workflow state and transition to error", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
   const previousCwd = process.cwd();
-  let checkingStatus = "";
-  let handoffStatus = "";
   try {
+    writeProjectConfigOverrides(projectBase, { GIT_WORKTREE_ENABLED: "disable" });
     const pi = createFakePi();
     piUsereqExtension(pi);
     const ctx = createFakeCtx(projectBase);
     await pi.emit("session_start", { reason: "startup" }, ctx);
-    const originalSendUserMessage = pi.sendUserMessage.bind(pi);
-    pi.sendUserMessage = (content: unknown, options?: unknown) => {
-      handoffStatus = ctx.__state.statuses.get("pi-usereq") ?? "";
-      originalSendUserMessage(content, options);
-    };
-    setPromptCommandPostCreateHookForTests(() => {
-      checkingStatus = ctx.__state.statuses.get("pi-usereq") ?? "";
-    });
 
     await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
-
-    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
-    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
-    assert.ok(worktreeMatch, promptText);
-    const executionBasePath = worktreeMatch?.[2] ?? "";
     assert.equal(
-      checkingStatus,
+      ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
-        workflowState: "checking",
+        workflowState: "running",
         basePath: buildExpectedFakeBasePath(projectBase),
         docsDir: DEFAULT_DOCS_DIR,
         testsDir: "tests",
@@ -2097,11 +2774,21 @@ test("prompt commands capture checking before handoff and running at prompt inje
         et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
       }),
     );
+
+    await assert.rejects(
+      pi.commands.get("req-analyze")!.handler("Inspect src/index.ts", ctx),
+      /expected idle/,
+    );
+    assert.equal(pi.sentUserMessages.length, 1);
     assert.equal(
-      handoffStatus,
+      ctx.__state.notifications.filter((entry) => /expected idle/.test(entry.message)).length,
+      1,
+    );
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
-        workflowState: "checking",
-        basePath: buildExpectedFakeBasePath(executionBasePath),
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(projectBase),
         docsDir: DEFAULT_DOCS_DIR,
         testsDir: "tests",
         srcDir: ["src"],
@@ -2109,11 +2796,21 @@ test("prompt commands capture checking before handoff and running at prompt inje
         et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
       }),
     );
+
+    await assert.rejects(
+      pi.commands.get("req-references")!.handler("", ctx),
+      /expected idle/,
+    );
+    assert.equal(pi.sentUserMessages.length, 1);
+    assert.equal(
+      ctx.__state.notifications.filter((entry) => /expected idle/.test(entry.message)).length,
+      2,
+    );
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
-        workflowState: "running",
-        basePath: buildExpectedFakeBasePath(executionBasePath),
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(projectBase),
         docsDir: DEFAULT_DOCS_DIR,
         testsDir: "tests",
         srcDir: ["src"],
@@ -2122,33 +2819,64 @@ test("prompt commands capture checking before handoff and running at prompt inje
       }),
     );
 
-    await pi.emit("before_agent_start", {}, ctx);
     await pi.emit("agent_start", {}, ctx);
     await pi.emit("agent_end", {
       messages: [{ role: "assistant", stopReason: "stop", content: [] }],
     }, ctx);
+    assert.equal(
+      ctx.__state.statuses.get("pi-usereq"),
+      buildExpectedFakeStatusText({
+        workflowState: "idle",
+        basePath: buildExpectedFakeBasePath(projectBase),
+        docsDir: DEFAULT_DOCS_DIR,
+        testsDir: "tests",
+        srcDir: ["src"],
+        contextFilledCells: 0,
+        et: "⏱︎ --:-- ⚑ 0:00 ⌛︎0:00",
+      }),
+    );
   } finally {
-    setPromptCommandPostCreateHookForTests(undefined);
     process.chdir(previousCwd);
     fs.rmSync(projectBase, { recursive: true, force: true });
   }
 });
 
-test("prompt commands reject non-idle workflow state before starting a new orchestration", async () => {
+/**
+ * @brief Verifies a worktree-backed prompt still finalizes after a busy req-command rejection moves workflow state to `error`.
+ * @details Starts one worktree-backed `req-change` run until the fake command context remains attached to the execution worktree with workflow state `running`, invokes `req-analyze` while the active run is still in progress so the busy-command guard forces workflow state to `error`, then emits the matched lifecycle completion and verifies `base-path` restoration, worktree plus branch deletion, unchanged prompt count, and final workflow state `idle`. Runtime is dominated by temporary git worktree setup plus fake lifecycle dispatch. Side effects are limited to temporary repository mutation and fake UI notifications.
+ * @return {Promise<void>} Promise resolved after finalization-path assertions complete.
+ * @throws {AssertionError} Throws when busy-command rejection orphaned the successful worktree-backed run or prevented cleanup.
+ * @satisfies TST-068, TST-082
+ */
+test("worktree-backed prompt finalization still succeeds after a busy-command rejection", async () => {
   const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
   try {
-    writeProjectConfigOverrides(projectBase, { GIT_WORKTREE_ENABLED: "disable" });
     const pi = createFakePi();
     piUsereqExtension(pi);
     const ctx = createFakeCtx(projectBase);
+
     await pi.emit("session_start", { reason: "startup" }, ctx);
+    const originalSessionFile = ctx.sessionManager.getSessionFile() ?? "";
+    assert.notEqual(originalSessionFile, "");
 
     await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+
+    const sentMessageCount = pi.sentUserMessages.length;
+    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    assert.ok(worktreeMatch, promptText);
+    const worktreeName = worktreeMatch?.[1] ?? "";
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+
+    assert.equal(ctx.cwd, executionBasePath);
+    assert.equal(process.cwd(), executionBasePath);
+    assert.equal(fs.existsSync(executionBasePath), true);
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
         workflowState: "running",
-        basePath: buildExpectedFakeBasePath(projectBase),
+        basePath: buildExpectedFakeBasePath(executionBasePath),
         docsDir: DEFAULT_DOCS_DIR,
         testsDir: "tests",
         srcDir: ["src"],
@@ -2161,13 +2889,16 @@ test("prompt commands reject non-idle workflow state before starting a new orche
       pi.commands.get("req-analyze")!.handler("Inspect src/index.ts", ctx),
       /expected idle/,
     );
-    assert.equal(pi.sentUserMessages.length, 1);
-    assert.ok(ctx.__state.notifications.some((entry) => /expected idle/.test(entry.message)));
+    assert.equal(pi.sentUserMessages.length, sentMessageCount);
+    assert.equal(
+      ctx.__state.notifications.filter((entry) => /expected idle/.test(entry.message)).length,
+      1,
+    );
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
-        workflowState: "running",
-        basePath: buildExpectedFakeBasePath(projectBase),
+        workflowState: "error",
+        basePath: buildExpectedFakeBasePath(executionBasePath),
         docsDir: DEFAULT_DOCS_DIR,
         testsDir: "tests",
         srcDir: ["src"],
@@ -2176,10 +2907,30 @@ test("prompt commands reject non-idle workflow state before starting a new orche
       }),
     );
 
+    await pi.emit("before_agent_start", {}, ctx);
     await pi.emit("agent_start", {}, ctx);
     await pi.emit("agent_end", {
       messages: [{ role: "assistant", stopReason: "stop", content: [] }],
     }, ctx);
+
+    assert.equal(ctx.cwd, projectBase);
+    assert.equal(process.cwd(), projectBase);
+    assert.equal(ctx.sessionManager.getSessionFile(), originalSessionFile);
+    assert.equal(fs.existsSync(executionBasePath), false);
+    assert.notEqual(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    assert.equal(
+      spawnSync("git", ["status", "--porcelain"], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).stdout.trim(),
+      "",
+    );
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
@@ -2193,6 +2944,7 @@ test("prompt commands reject non-idle workflow state before starting a new orche
       }),
     );
   } finally {
+    process.chdir(previousCwd);
     fs.rmSync(projectBase, { recursive: true, force: true });
   }
 });
@@ -2343,6 +3095,110 @@ test("worktree-enabled prompt commands merge successful runs, restore base-path,
   }
 });
 
+/**
+ * @brief Verifies successful closure stashes tracked `base-path` changes before merge and restores them afterward.
+ * @details Creates tracked `base-path` files, dirties one in the index and one in the worktree after worktree handoff, commits a worktree change, and proves prompt finalization runs `git stash`/merge/`git stash pop` semantics by merging successfully, restoring the local `base-path` changes, deleting the worktree, and surfacing a warning-only notification about the dirty restored base path.
+ * @return {Promise<void>} Promise resolved after stash-assisted merge assertions complete.
+ * @throws {AssertionError} Throws when finalization drops local `base-path` changes, skips the merge, or reports an error instead of a warning.
+ * @satisfies REQ-208, REQ-291, REQ-292
+ */
+test("worktree-backed successful closure stashes tracked base-path changes, merges, restores changes, and warns about dirty base-path", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    const stagedBasePath = path.join(projectBase, "staged-base.txt");
+    const worktreeBasePath = path.join(projectBase, "worktree-base.txt");
+    fs.writeFileSync(stagedBasePath, "staged base clean\n", "utf8");
+    fs.writeFileSync(worktreeBasePath, "worktree base clean\n", "utf8");
+    assert.equal(
+      spawnSync("git", ["add", "staged-base.txt", "worktree-base.txt"], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    const baseCommit = spawnSync("git", ["commit", "-m", "tracked base files"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    });
+    assert.equal(baseCommit.status, 0, baseCommit.stderr);
+
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+    const promptText = String(pi.sentUserMessages[0]?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    assert.ok(worktreeMatch, promptText);
+    const worktreeName = worktreeMatch?.[1] ?? "";
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+
+    await pi.emit("before_agent_start", {}, ctx);
+    await pi.emit("agent_start", {}, ctx);
+    fs.mkdirSync(path.join(executionBasePath, "src"), { recursive: true });
+    fs.writeFileSync(path.join(executionBasePath, "src", "stash-assisted.ts"), "export const STASH_ASSISTED = 1;\n", "utf8");
+    assert.equal(
+      spawnSync("git", ["add", "src/stash-assisted.ts"], {
+        cwd: executionBasePath,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    const worktreeCommit = spawnSync("git", ["commit", "-m", "stash assisted change"], {
+      cwd: executionBasePath,
+      encoding: "utf8",
+    });
+    assert.equal(worktreeCommit.status, 0, worktreeCommit.stderr);
+
+    fs.writeFileSync(stagedBasePath, "staged base dirty\n", "utf8");
+    assert.equal(
+      spawnSync("git", ["add", "staged-base.txt"], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    fs.writeFileSync(worktreeBasePath, "worktree base dirty\n", "utf8");
+
+    await pi.emit("agent_end", {
+      messages: [{ role: "assistant", stopReason: "stop", content: [] }],
+    }, ctx);
+
+    const statusResult = spawnSync("git", ["status", "--porcelain"], {
+      cwd: projectBase,
+      encoding: "utf8",
+    });
+    assert.equal(statusResult.status, 0, statusResult.stderr);
+    assert.equal(process.cwd(), projectBase);
+    assert.equal(ctx.cwd, projectBase);
+    assert.ok(fs.existsSync(path.join(projectBase, "src", "stash-assisted.ts")));
+    assert.equal(fs.readFileSync(stagedBasePath, "utf8"), "staged base dirty\n");
+    assert.equal(fs.readFileSync(worktreeBasePath, "utf8"), "worktree base dirty\n");
+    assert.match(statusResult.stdout, /staged-base\.txt/);
+    assert.match(statusResult.stdout, /worktree-base\.txt/);
+    assert.equal(fs.existsSync(executionBasePath), false);
+    assert.notEqual(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+    );
+    assert.equal(ctx.__state.notifications.filter((entry) => entry.level === "error").length, 0);
+    assert.ok(
+      ctx.__state.notifications.some(
+        (entry) => entry.level === "info"
+          && /WARNING: Restored base-path changes after merge; base-path is not clean\./.test(entry.message),
+      ),
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
 /**
  * @brief Verifies prompt-command bootstrap ignores stale deleted-worktree session metadata on later commands.
  * @details Simulates the `/tmp/debug.json` follow-up failure mode: one successful worktree-backed `req-change` run restores `base-path` and deletes its worktree, then a later `req-change` invocation receives a stale command context whose `cwd` and session getters still point at the removed execution worktree. The test proves command bootstrap MUST discard deleted-worktree cwd/session residue, prepare a fresh worktree with a new identifier, and complete the second successful run without reusing the removed execution path.
@@ -3996,6 +4852,58 @@ test("session_start renders the 0-percent context icon when context usage is emp
   );
 });
 
+/**
+ * @brief Verifies direct status renders refresh context usage before drawing the footer.
+ * @details Exercises `renderPiUsereqStatus(...)` without going through an intercepted lifecycle hook, then mutates the fake `getContextUsage()` result to simulate a post-compaction context reset. The test proves direct rerender call sites must fetch fresh context usage so the `context:` gauge updates immediately instead of reusing stale controller state.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when a direct render ignores the live `getContextUsage()` snapshot or fails to clear the gauge after context reset.
+ * @satisfies REQ-118, REQ-119, REQ-122, REQ-284
+ */
+test("direct status rerenders refresh the context gauge after context reset", () => {
+  const cwd = createTempDir("pi-usereq-context-direct-render-");
+  fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
+  const controller = createPiUsereqStatusController();
+  setPiUsereqStatusConfig(controller, getDefaultConfig(cwd));
+  const contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } = {
+    tokens: 910,
+    contextWindow: 1000,
+    percent: 91,
+  };
+  const ctx = createFakeCtx(cwd, { selects: [] }, {
+    getContextUsage: () => ({ ...contextUsage }),
+  });
+
+  renderPiUsereqStatus(controller, ctx);
+  assert.equal(
+    ctx.__state.statuses.get("pi-usereq"),
+    buildExpectedFakeStatusText({
+      basePath: buildExpectedFakeBasePath(cwd),
+      docsDir: DEFAULT_DOCS_DIR,
+      testsDir: "tests",
+      srcDir: ["src"],
+      contextFilledCells: 10,
+      contextPercent: 91,
+      et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+    }),
+  );
+
+  contextUsage.tokens = null;
+  contextUsage.percent = null;
+  renderPiUsereqStatus(controller, ctx);
+  assert.equal(
+    ctx.__state.statuses.get("pi-usereq"),
+    buildExpectedFakeStatusText({
+      basePath: buildExpectedFakeBasePath(cwd),
+      docsDir: DEFAULT_DOCS_DIR,
+      testsDir: "tests",
+      srcDir: ["src"],
+      contextFilledCells: 0,
+      contextPercent: null,
+      et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+    }),
+  );
+});
+
 /**
  * @brief Verifies stale replacement contexts do not break workflow-state rendering.
  * @details Simulates the guarded pi runtime error thrown when an extension context is accessed after session replacement or reload. The test proves workflow-state updates must preserve internal state while suppressing stale-context render failures instead of surfacing extension errors.
@@ -4092,12 +5000,12 @@ test("context hook refreshes context usage and rounds progress cells upward", as
 
 /**
  * @brief Verifies context-gauge icon cutovers below the error range.
- * @details Replays deterministic context percentages at documented threshold boundaries below `90%` so the status bar proves the `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` transitions while keeping the default-color contract intact. Runtime is O(n) in case count. Side effects are limited to in-memory status updates.
+ * @details Replays deterministic context percentages at documented threshold boundaries below `90%` so the status bar proves the `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` transitions while rendering every non-error band with the same warning-token color used by the `status` value. Runtime is O(n) in case count. Side effects are limited to in-memory status updates.
  * @return {Promise<void>} Promise resolved after all threshold assertions complete.
- * @throws {AssertionError} Throws when any threshold renders the wrong icon.
- * @satisfies TST-096
+ * @throws {AssertionError} Throws when any threshold renders the wrong icon or low-band color.
+ * @satisfies REQ-122, REQ-126, TST-096
  */
-test("context hook applies quarter-threshold gauge icons below the error range", async () => {
+test("context hook applies warning-colored quarter-threshold gauge icons below the error range", async () => {
   const cwd = createTempDir("pi-usereq-context-threshold-status-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
   const contextUsage = { tokens: 0, contextWindow: 1000, percent: 0 };
@@ -4476,11 +5384,12 @@ test("configuration menu orders tool toggles and can enable embedded builtin too
     "references",
     "search",
     "static-check",
+    "summarize",
     "tokens",
     "files-compress",
-    "files-references",
     "files-search",
     "files-static-check",
+    "files-summarize",
     "files-tokens",
     "bash",
     "edit",
@@ -4515,7 +5424,7 @@ test("configuration menu can disable configurable active tools", async () => {
   assert.deepEqual(pi.getActiveTools().filter((toolName: string) => PI_USEREQ_STARTUP_TOOL_NAMES.includes(toolName as never)), []);
 });
 
-test("configuration menu can persist notify and sound settings", async () => {
+test("configuration menu can persist notify and boot-sound settings without changing runtime sound", async () => {
   const cwd = createTempDir("pi-usereq-menu-notify-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
   const pi = createFakePi();
@@ -4529,7 +5438,7 @@ test("configuration menu can persist notify and sound settings", async () => {
       "Notification events",
       "Prompt failed",
       "Save and close",
-      "Enable sound",
+      "Enable sound (boot value)",
       "high",
       "Sound events",
       "Prompt interrupted",
@@ -4551,6 +5460,7 @@ test("configuration menu can persist notify and sound settings", async () => {
     ],
   });
 
+  await pi.emit("session_start", { reason: "startup" }, ctx);
   await command!.handler("", ctx);
 
   const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
@@ -4576,7 +5486,7 @@ test("configuration menu can persist notify and sound settings", async () => {
       srcDir: ["src"],
       contextFilledCells: 0,
       et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
-      sound: "high",
+      sound: "none",
     }),
   );
 });
@@ -4662,7 +5572,7 @@ test("notifications menu escapes pushover text and locks pushover enablement unt
   const renderedNotificationsMenu = (ctx.__state.customRenderLines[2] ?? []).join("\n");
   assert.match(renderedNotificationsMenu, /first line\\nsecond line/);
   assert.match(renderedNotificationsMenu, /<dim>Enable pushover/);
-  assert.match(renderedNotificationsMenu, /<dim>off<\/dim>/);
+  assert.match(renderedNotificationsMenu, /<dim>configure user\/token keys first<\/dim>/);
 });
 
 test("prompt-end pushover requests honor global enable, event toggles, credentials, priority, and templates", async () => {
@@ -5125,9 +6035,11 @@ test("sound routing honors the selected sound state and per-event toggles", asyn
   }
 });
 
-test("sound toggle shortcut cycles persisted pi-notify sound levels", async () => {
+test("sound toggle shortcut cycles active runtime pi-notify sound levels without persisting boot config", async () => {
   const cwd = createTempDir("pi-usereq-shortcut-notify-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
+  const persistedConfigText = `${JSON.stringify(getDefaultConfig(cwd), null, 2)}\n`;
+  fs.writeFileSync(getProjectConfigPath(cwd), persistedConfigText, "utf8");
   const previousCwd = process.cwd();
   const pi = createFakePi();
   process.chdir(cwd);
@@ -5144,8 +6056,7 @@ test("sound toggle shortcut cycles persisted pi-notify sound levels", async () =
 
   for (const expectedSound of ["low", "mid", "high", "none"]) {
     await shortcut!.handler(ctx);
-    const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
-    assert.equal(config["notify-sound"], expectedSound);
+    assert.equal(fs.readFileSync(getProjectConfigPath(cwd), "utf8"), persistedConfigText);
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
@@ -5161,6 +6072,42 @@ test("sound toggle shortcut cycles persisted pi-notify sound levels", async () =
   }
 });
 
+test("session_start loads the active runtime sound from persisted boot config", async () => {
+  const cwd = createTempDir("pi-usereq-session-start-sound-");
+  fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
+  const persistedConfig = getDefaultConfig(cwd);
+  persistedConfig["notify-sound"] = "mid";
+  fs.writeFileSync(
+    getProjectConfigPath(cwd),
+    `${JSON.stringify(persistedConfig, null, 2)}\n`,
+    "utf8",
+  );
+  const previousCwd = process.cwd();
+  const pi = createFakePi();
+  process.chdir(cwd);
+  try {
+    piUsereqExtension(pi);
+  } finally {
+    process.chdir(previousCwd);
+  }
+
+  const ctx = createFakeCtx(cwd);
+  await pi.emit("session_start", { reason: "startup" }, ctx);
+
+  assert.equal(
+    ctx.__state.statuses.get("pi-usereq"),
+    buildExpectedFakeStatusText({
+      basePath: buildExpectedFakeBasePath(cwd),
+      docsDir: DEFAULT_DOCS_DIR,
+      testsDir: "tests",
+      srcDir: ["src"],
+      contextFilledCells: 0,
+      et: "⏱︎ --:-- ⚑ --:-- ⌛︎--:--",
+      sound: "mid",
+    }),
+  );
+});
+
 test("static-check exposes the supported programming languages", () => {
   const supported = getSupportedStaticCheckLanguageSupport();
   assert.equal(supported.length, 20);