pi-usereq 0.40.0 → 0.42.0

package/src/core/static-check.ts

@@ -9,8 +9,9 @@ import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 import fg from "fast-glob";
-import type { StaticCheckEntry } from "./config.js";
+import type { StaticCheckEntry, UseReqConfig } from "./config.js";
 import { ReqError } from "./errors.js";
+import { getInstallationPath } from "./path-context.js";
 
 /**
  * @brief Maps user-facing language aliases to canonical static-check language names.
@@ -264,7 +265,7 @@ export function validateStaticCheckEntry(entry: StaticCheckEntry): void {
   if (!cmd) {
     throw new ReqError("Error: Command module requires a cmd argument in --enable-static-check. Format: LANG=Command,CMD[,PARAM...]", 1);
   }
-  if (!findExecutable(cmd)) {
+  if (!resolveCheckerExecutable(cmd)) {
     throw new ReqError(`Error: --enable-static-check Command cmd '${cmd}' is not an executable program on this system.`, 1);
   }
 }
@@ -398,7 +399,7 @@ export class StaticCheckCommand extends StaticCheckBase {
    * @throws {ReqError} Throws when the executable cannot be found on PATH.
    */
   constructor(cmd: string, inputs: string[], extraArgs?: string[], failOnly = false) {
-    if (!findExecutable(cmd)) {
+    if (!resolveCheckerExecutable(cmd)) {
       throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
     }
     super(inputs, extraArgs, failOnly);
@@ -460,7 +461,7 @@ function isExecutableFile(candidate: string): boolean {
  * @param[in] cmd {string} Executable name to locate.
  * @return {string | undefined} Absolute executable path, or `undefined` when not found.
  */
-function findExecutable(cmd: string): string | undefined {
+export function findExecutable(cmd: string): string | undefined {
   if (cmd.includes(path.sep)) {
     return isExecutableFile(cmd) ? path.resolve(cmd) : undefined;
   }
@@ -473,6 +474,59 @@ function findExecutable(cmd: string): string | undefined {
   return undefined;
 }
 
+/**
+ * @brief Resolves one checker executable across bundled `node_modules/.bin` locations and PATH.
+ * @details Probes the installation-owned `node_modules/.bin` directory, the project-scope parent `node_modules/.bin` directory used by `--prefix` layouts, and finally the system PATH scan, returning the first executable match. Runtime is O(p) in PATH entry count plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
+ * @param[in] cmd {string} Executable name or relative path to resolve.
+ * @return {string | undefined} Absolute executable path, or `undefined` when not found in any probed location.
+ * @satisfies REQ-023, REQ-037, DES-018
+ */
+export function resolveCheckerExecutable(cmd: string): string | undefined {
+  if (cmd.includes(path.sep)) {
+    return isExecutableFile(cmd) ? path.resolve(cmd) : undefined;
+  }
+  const installationPath = getInstallationPath();
+  const bundledBinCandidates = [
+    path.join(installationPath, "..", "node_modules", ".bin", cmd),
+    path.join(installationPath, "..", "..", "node_modules", ".bin", cmd),
+  ];
+  for (const candidate of bundledBinCandidates) {
+    if (isExecutableFile(candidate)) {
+      return candidate;
+    }
+  }
+  return findExecutable(cmd);
+}
+
+/**
+ * @brief Determines which enabled static-check executables are missing from the runtime environment.
+ * @details Iterates every enabled language checker entry in the effective config, resolves each `Command` entry executable through `resolveCheckerExecutable`, and collects the missing command names so the caller can surface one consolidated warning. Runtime is O(l * c * p) where l is language count, c is checker count, and p is PATH entry count. Side effects are limited to filesystem reads.
+ * @param[in] config {UseReqConfig} Effective merged configuration.
+ * @return {string[]} Unique command names that are enabled but unresolvable.
+ * @satisfies REQ-341, REQ-343, REQ-344
+ */
+export function checkDefaultCheckersAvailability(config: UseReqConfig): string[] {
+  const missing = new Set<string>();
+  for (const languageConfig of Object.values(config["static-check"] ?? {})) {
+    if (languageConfig.enabled !== "enable") {
+      continue;
+    }
+    for (const entry of languageConfig.checkers) {
+      if (String(entry.module ?? "").trim().toLowerCase() !== "command") {
+        continue;
+      }
+      const cmd = typeof entry.cmd === "string" ? entry.cmd.trim() : "";
+      if (!cmd) {
+        continue;
+      }
+      if (!resolveCheckerExecutable(cmd)) {
+        missing.add(cmd);
+      }
+    }
+  }
+  return [...missing];
+}
+
 /**
  * @brief Dispatches one configured static checker for a single file.
  * @details Selects the debug `Dummy` or user-facing `Command` implementation by module name, normalizes parameter arrays, and runs exactly one checker instance against the target file. Runtime is dominated by the selected checker. Side effects include console output and possible process spawning.
@@ -527,6 +581,9 @@ export function runStaticCheck(argv: string[]): number {
         throw new ReqError("Error: --test-static-check command requires a <cmd> argument.", 1);
       }
       const [cmd, ...files] = rest;
+      if (!resolveCheckerExecutable(cmd!)) {
+        throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
+      }
       return new StaticCheckCommand(cmd!, files).run();
     }
     default:

package/src/index.ts

@@ -172,6 +172,7 @@ import {
 } from "./core/tool-runner.js";
 import { LANGUAGE_TAGS } from "./core/find-constructs.js";
 import {
+  checkDefaultCheckersAvailability,
   getSupportedStaticCheckLanguageSupport,
 } from "./core/static-check.js";
 import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
@@ -910,7 +911,7 @@ function executeStatusTool(operation: () => ToolResult): ReturnType<typeof build
 
 /**
  * @brief Starts delivery of one rendered prompt into the current active session.
- * @details Prefers the replacement-session `sendMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Delivers the rendered prompt as a `display:false` custom message with `triggerTurn:true` so the full content reaches the LLM agent without appearing on screen, and emits a `display:true` command invocation summary so the TUI shows only the compact summary. Returns the underlying hidden-delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose `sendMessage`. Runtime is O(n) in prompt length. Side effects are limited to hidden prompt delivery plus on-screen summary display.
+ * @details Prefers the replacement-session `sendMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Delivers the rendered prompt as a `display:false` custom message with `triggerTurn:true` so the full content reaches the LLM agent without appearing on screen, and emits a `display:true` command invocation summary so the TUI shows only the compact summary. Awaits the non-critical summary delivery and suppresses its failures before dispatching the authoritative hidden prompt turn so a rejecting summary never surfaces as an unhandled rejection that could terminate the process before prompt-end closure runs the worktree merge. Returns the underlying hidden-delivery promise without awaiting the full agent turn so callers can record the `running` workflow transition as soon as prompt handoff is accepted; the returned promise resolves after the hidden prompt message is accepted, which on runtimes whose async replacement-session helpers resolve only after `agent_end` lets prompt-end closure finalize the worktree merge during the awaited delivery. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose `sendMessage`. Runtime is O(n) in prompt length. Side effects are limited to hidden prompt delivery plus on-screen summary display.
  * @param[in] pi {ExtensionAPI} Handler-scoped extension API instance retained as the fallback dispatcher.
  * @param[in] content {string} Rendered prompt markdown.
  * @param[in] summary {string} Command invocation summary text displayed on screen.
@@ -942,9 +943,16 @@ function deliverPromptCommand(
     display: false,
   };
   if (typeof replacementContext?.sendMessage === "function") {
-    replacementContext.sendMessage(summaryMessage);
-    return Promise.resolve(
-      replacementContext.sendMessage(hiddenPromptMessage, { triggerTurn: true }),
+    // The on-screen summary is non-critical; await it and suppress its delivery failures so a
+    // rejecting summary never surfaces as an unhandled rejection that could terminate the
+    // process before the authoritative hidden prompt turn drives prompt-end closure.
+    const summaryDelivery = Promise.resolve(
+      replacementContext.sendMessage(summaryMessage),
+    ).catch(() => {
+      // Intentionally suppressed: the hidden prompt message below is the authoritative turn trigger.
+    });
+    return summaryDelivery.then(() =>
+      replacementContext!.sendMessage!(hiddenPromptMessage, { triggerTurn: true }),
     ).catch((error) => {
       if (isStaleExtensionContextError(error)) {
         return;
@@ -953,9 +961,17 @@ function deliverPromptCommand(
     });
   }
   if (typeof pi.sendMessage === "function") {
-    pi.sendMessage(summaryMessage);
-    pi.sendMessage(hiddenPromptMessage, { triggerTurn: true });
-    return Promise.resolve();
+    // `pi.sendMessage` is a fire-and-forget dispatcher in the pi runtime; chain both deliveries
+    // through one suppressed summary promise so a rejecting summary cannot terminate the process
+    // before the hidden prompt turn drives prompt-end closure.
+    const fallbackSummary = Promise.resolve(
+      pi.sendMessage(summaryMessage),
+    ).catch(() => {
+      // Intentionally suppressed: the hidden prompt message below is the authoritative turn trigger.
+    });
+    return fallbackSummary.then(() => {
+      pi.sendMessage(hiddenPromptMessage, { triggerTurn: true });
+    });
   }
   if (typeof replacementContext?.sendUserMessage === "function") {
     return Promise.resolve(replacementContext.sendUserMessage(content)).catch((error) => {
@@ -1072,7 +1088,7 @@ function logPromptWorkflowEvent(
  * @param[in] projectBase {string} Absolute original project base path.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName} Bundled prompt name.
- * @param[in] nextState {DebugWorkflowState} Next workflow state.
+ * @param[in] nextState {import("./core/extension-status.js").PiUsereqWorkflowState} Next workflow state.
  * @return {void} No return value.
  */
 function transitionPromptWorkflowState(
@@ -1081,7 +1097,7 @@ function transitionPromptWorkflowState(
   projectBase: string,
   config: UseReqConfig,
   promptName: import("./core/prompt-command-catalog.js").PromptCommandName,
-  nextState: DebugWorkflowState,
+  nextState: import("./core/extension-status.js").PiUsereqWorkflowState,
 ): void {
   const previousState = statusController.state.workflowState;
   setPiUsereqWorkflowState(statusController, nextState, ctx);
@@ -1267,6 +1283,13 @@ async function handleExtensionStatusEvent(
     const config = loadProjectConfig(startupCwd);
     applyConfiguredPiUsereqTools(pi, config);
     setPiUsereqStatusConfig(statusController, config);
+    const missingCheckers = checkDefaultCheckersAvailability(config);
+    if (missingCheckers.length > 0) {
+      ctx.ui.notify(
+        `Missing static checkers: ${missingCheckers.join(", ")}\nInstall: run 'npm install' or install each missing checker via your system package manager.`,
+        "warning",
+      );
+    }
   }
   if (hookName === "before_agent_start") {
     const requestForActivation = activePromptRequest ?? pendingPromptRequest;

package/tests/extension-registration.test.ts

@@ -3780,6 +3780,296 @@ test("worktree-backed prompt commands use replacement-session callbacks for prom
   }
 });
 
+/**
+ * @brief Verifies worktree-backed prompt closure still merges and deletes the worktree when prompt delivery uses the production `sendMessage` custom-message path.
+ * @details Simulates the pi runtime `sendMessage(message, { triggerTurn: true })` contract documented for `ReplacedSessionContext`: a `triggerTurn` custom message runs the agent loop which emits `agent_start` then `agent_end` (without a separate `before_agent_start`), and the `sendMessage` promise resolves only after the agent turn completes. The test proves that when the replacement session exposes `sendMessage`, prompt delivery must still drive the prompt-end closure so the worktree branch is merged into `base-path`, the worktree plus branch are deleted, and the workflow state returns to `idle`. Runtime is dominated by temporary git worktree setup and teardown. Side effects are limited to temporary repository mutation and temporary session-file writes.
+ * @return {Promise<void>} Promise resolved after `sendMessage`-driven prompt delivery, merge handling, and restored-base assertions complete.
+ * @throws {AssertionError} Throws when `sendMessage`-driven prompt delivery leaves the worktree unmerged, the worktree or branch retained, or the workflow state not `idle`.
+ * @satisfies REQ-068, REQ-208, REQ-228, REQ-230, REQ-258, REQ-282, DES-016
+ */
+test("worktree-backed prompt commands merge and delete the worktree when prompt delivery uses sendMessage triggerTurn", 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();
+    const originalSwitchSession = ctx.switchSession.bind(ctx);
+    const sentMessages: Array<{ message: unknown; options?: unknown }> = [];
+    let activeSessionCtx: any = ctx;
+    ctx.switchSession = async (
+      sessionPath: string,
+      options?: { withSession?: (replacementCtx: any) => Promise<void> },
+    ) => {
+      const result = await originalSwitchSession(sessionPath);
+      const replacementCwd = readFakeSessionFileCwd(sessionPath, projectBase);
+      const replacementCtx = {
+        ...ctx,
+        cwd: replacementCwd,
+        sessionManager: {
+          ...ctx.sessionManager,
+          getCwd: () => replacementCwd,
+          getSessionFile: () => sessionPath,
+        },
+        async sendUserMessage(content: unknown, sendOptions?: unknown) {
+          pi.sentUserMessages.push({ content, options: sendOptions });
+        },
+        async sendMessage(message: unknown, sendOptions?: unknown) {
+          sentMessages.push({ message, options: sendOptions });
+          if ((sendOptions as { triggerTurn?: boolean } | undefined)?.triggerTurn === true) {
+            await Promise.resolve();
+            await pi.emit("agent_start", {}, activeSessionCtx);
+            await pi.emit("agent_end", {
+              messages: [{ role: "assistant", stopReason: "stop", content: [] }],
+            }, activeSessionCtx);
+          }
+        },
+      };
+      activeSessionCtx = replacementCtx;
+      if (options?.withSession) {
+        process.chdir(replacementCwd);
+        await options.withSession(replacementCtx);
+        ctx.cwd = projectBase;
+        ctx.sessionManager.getSessionFile = () => originalSessionFile;
+        ctx.sessionManager.getCwd = () => projectBase;
+        return result;
+      }
+      ctx.cwd = projectBase;
+      ctx.sessionManager.getSessionFile = () => originalSessionFile;
+      ctx.sessionManager.getCwd = () => projectBase;
+      process.chdir(projectBase);
+      return result;
+    };
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+
+    assert.ok(
+      sentMessages.some((entry) => (entry.options as { triggerTurn?: boolean } | undefined)?.triggerTurn === true),
+      "prompt delivery must use sendMessage with triggerTurn",
+    );
+    const promptMessage = sentMessages.find((entry) =>
+      typeof (entry.message as { content?: unknown } | undefined)?.content === "string"
+      && String((entry.message as { content?: unknown }).content).includes("created worktree-dir"));
+    const promptText = String((promptMessage?.message as { content?: string } | undefined)?.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(process.cwd(), projectBase);
+    assert.equal(fs.existsSync(executionBasePath), false, "worktree directory must be deleted after successful closure");
+    assert.notEqual(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+      "worktree branch must be deleted after successful closure",
+    );
+    const logResult = spawnSync("git", ["log", "--oneline", "-1"], { cwd: projectBase, encoding: "utf8" });
+    assert.match(logResult.stdout, /init/, "base-path must remain on the original head after a no-commit ff-only merge");
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies a rejecting on-screen summary delivery never surfaces as an unhandled rejection and never interrupts the worktree merge.
+ * @details Simulates the pi runtime `sendMessage` contract where the non-critical `display:true` summary delivery rejects (for example because the session is torn down mid-emit during prompt-end closure) while the authoritative `display:false` hidden prompt message with `triggerTurn:true` still drives the agent turn. The test proves `deliverPromptCommand` must await and suppress summary delivery failures so the rejection cannot terminate the process (Node default `--unhandled-rejections=throw`) before prompt-end closure runs the worktree merge, branch deletion, and worktree deletion. Runtime is dominated by temporary git worktree setup and teardown. Side effects are limited to temporary repository mutation and temporary session-file writes.
+ * @return {Promise<void>} Promise resolved after summary-rejection-tolerant prompt delivery, merge handling, and restored-base assertions complete.
+ * @throws {AssertionError} Throws when a rejecting summary surfaces as an unhandled rejection or leaves the worktree unmerged.
+ * @satisfies REQ-068, REQ-208, REQ-228, REQ-230, REQ-258, REQ-282, REQ-334, DES-016
+ */
+test("worktree-backed prompt commands tolerate a rejecting summary sendMessage without interrupting the merge", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  let unhandledRejections: unknown[] = [];
+  const rejectionHandler = (reason: unknown): void => { unhandledRejections.push(reason); };
+  process.on("unhandledRejection", rejectionHandler);
+  try {
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+
+    const originalSessionFile = ctx.sessionManager.getSessionFile();
+    const originalSwitchSession = ctx.switchSession.bind(ctx);
+    const sentMessages: Array<{ message: unknown; options?: unknown }> = [];
+    let activeSessionCtx: any = ctx;
+    ctx.switchSession = async (
+      sessionPath: string,
+      options?: { withSession?: (replacementCtx: any) => Promise<void> },
+    ) => {
+      const result = await originalSwitchSession(sessionPath);
+      const replacementCwd = readFakeSessionFileCwd(sessionPath, projectBase);
+      const replacementCtx = {
+        ...ctx,
+        cwd: replacementCwd,
+        sessionManager: {
+          ...ctx.sessionManager,
+          getCwd: () => replacementCwd,
+          getSessionFile: () => sessionPath,
+        },
+        async sendUserMessage(content: unknown, sendOptions?: unknown) {
+          pi.sentUserMessages.push({ content, options: sendOptions });
+        },
+        async sendMessage(message: unknown, sendOptions?: unknown) {
+          const isTrigger = (sendOptions as { triggerTurn?: boolean } | undefined)?.triggerTurn === true;
+          sentMessages.push({ message, options: sendOptions });
+          if (!isTrigger) {
+            throw new Error("summary sendMessage rejected");
+          }
+          await Promise.resolve();
+          await pi.emit("agent_start", {}, activeSessionCtx);
+          await pi.emit("agent_end", {
+            messages: [{ role: "assistant", stopReason: "stop", content: [] }],
+          }, activeSessionCtx);
+        },
+      };
+      activeSessionCtx = replacementCtx;
+      if (options?.withSession) {
+        process.chdir(replacementCwd);
+        await options.withSession(replacementCtx);
+        ctx.cwd = projectBase;
+        ctx.sessionManager.getSessionFile = () => originalSessionFile;
+        ctx.sessionManager.getCwd = () => projectBase;
+        return result;
+      }
+      ctx.cwd = projectBase;
+      ctx.sessionManager.getSessionFile = () => originalSessionFile;
+      ctx.sessionManager.getCwd = () => projectBase;
+      process.chdir(projectBase);
+      return result;
+    };
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    assert.ok(
+      sentMessages.some((entry) => (entry.options as { triggerTurn?: boolean } | undefined)?.triggerTurn === true),
+      "prompt delivery must still dispatch the hidden prompt message with triggerTurn",
+    );
+    assert.equal(process.cwd(), projectBase, "base-path must be restored after successful closure");
+    assert.equal(unhandledRejections.length, 0, "rejecting summary delivery must not surface as an unhandled rejection");
+    const promptMessage = sentMessages.find((entry) =>
+      typeof (entry.message as { content?: unknown } | undefined)?.content === "string"
+      && String((entry.message as { content?: unknown }).content).includes("created worktree-dir"));
+    const promptText = String((promptMessage?.message as { content?: string } | undefined)?.content ?? "");
+    const worktreeMatch = promptText.match(/created worktree-dir `([^`]+)` and prepared context-path `([^`]+)`\./);
+    const executionBasePath = worktreeMatch?.[2] ?? "";
+    assert.ok(worktreeMatch, promptText);
+    assert.equal(fs.existsSync(executionBasePath), false, "worktree directory must be deleted after successful closure");
+  } finally {
+    process.off("unhandledRejection", rejectionHandler);
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
+/**
+ * @brief Verifies worktree-backed prompt closure still merges and deletes the worktree when prompt delivery falls back to `pi.sendMessage` because the replacement session omits `sendMessage`.
+ * @details Simulates the pi runtime where `ctx.switchSession(...)` exposes a replacement context without `sendMessage` while the top-level `pi.sendMessage` is available as a fire-and-forget custom-message dispatcher. The test proves that even in this fallback path, prompt delivery must drive the prompt-end closure so the worktree branch is merged into `base-path`, the worktree plus branch are deleted, and the workflow state returns to `idle`. Runtime is dominated by temporary git worktree setup and teardown. Side effects are limited to temporary repository mutation and temporary session-file writes.
+ * @return {Promise<void>} Promise resolved after `sendMessage`-fallback prompt delivery, merge handling, and restored-base assertions complete.
+ * @throws {AssertionError} Throws when `pi.sendMessage`-fallback prompt delivery leaves the worktree unmerged, the worktree or branch retained, or the workflow state not `idle`.
+ * @satisfies REQ-068, REQ-208, REQ-228, REQ-230, REQ-258, REQ-282, DES-016
+ */
+test("worktree-backed prompt commands merge and delete the worktree when prompt delivery falls back to pi.sendMessage", async () => {
+  const { projectBase } = initFixtureRepo({ fixtures: [] });
+  const previousCwd = process.cwd();
+  try {
+    const pi = createFakePi();
+    const sentMessages: Array<{ message: unknown; options?: unknown }> = [];
+    (pi as any).sendMessage = (message: unknown, options?: unknown) => {
+      sentMessages.push({ message, options });
+      // Simulate the real SDK fire-and-forget dispatcher: trigger the agent turn asynchronously.
+      if ((options as { triggerTurn?: boolean } | undefined)?.triggerTurn === true) {
+        Promise.resolve().then(async () => {
+          await pi.emit("agent_start", {}, activeSessionCtx);
+          await pi.emit("agent_end", {
+            messages: [{ role: "assistant", stopReason: "stop", content: [] }],
+          }, activeSessionCtx);
+        });
+      }
+    };
+    piUsereqExtension(pi);
+    const ctx = createFakeCtx(projectBase);
+    await pi.emit("session_start", { reason: "startup" }, ctx);
+
+    const originalSessionFile = ctx.sessionManager.getSessionFile();
+    const originalSwitchSession = ctx.switchSession.bind(ctx);
+    let activeSessionCtx: any = ctx;
+    ctx.switchSession = async (
+      sessionPath: string,
+      options?: { withSession?: (replacementCtx: any) => Promise<void> },
+    ) => {
+      const result = await originalSwitchSession(sessionPath);
+      const replacementCwd = readFakeSessionFileCwd(sessionPath, projectBase);
+      const replacementCtx = {
+        ...ctx,
+        cwd: replacementCwd,
+        sessionManager: {
+          ...ctx.sessionManager,
+          getCwd: () => replacementCwd,
+          getSessionFile: () => sessionPath,
+        },
+        async sendUserMessage(content: unknown, sendOptions?: unknown) {
+          pi.sentUserMessages.push({ content, options: sendOptions });
+        },
+      };
+      activeSessionCtx = replacementCtx;
+      if (options?.withSession) {
+        process.chdir(replacementCwd);
+        await options.withSession(replacementCtx);
+        ctx.cwd = projectBase;
+        ctx.sessionManager.getSessionFile = () => originalSessionFile;
+        ctx.sessionManager.getCwd = () => projectBase;
+        return result;
+      }
+      ctx.cwd = projectBase;
+      ctx.sessionManager.getSessionFile = () => originalSessionFile;
+      ctx.sessionManager.getCwd = () => projectBase;
+      process.chdir(projectBase);
+      return result;
+    };
+
+    await pi.commands.get("req-change")!.handler("Adjust docs", ctx);
+    // The real SDK `pi.sendMessage` dispatcher is fire-and-forget; let the simulated agent turn drain.
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    assert.ok(
+      sentMessages.some((entry) => (entry.options as { triggerTurn?: boolean } | undefined)?.triggerTurn === true),
+      "prompt delivery must use pi.sendMessage with triggerTurn",
+    );
+    const promptMessage = sentMessages.find((entry) =>
+      typeof (entry.message as { content?: unknown } | undefined)?.content === "string"
+      && String((entry.message as { content?: unknown }).content).includes("created worktree-dir"));
+    const promptText = String((promptMessage?.message as { content?: string } | undefined)?.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(process.cwd(), projectBase);
+    assert.equal(fs.existsSync(executionBasePath), false, "worktree directory must be deleted after successful closure");
+    assert.notEqual(
+      spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${worktreeName}`], {
+        cwd: projectBase,
+        encoding: "utf8",
+      }).status,
+      0,
+      "worktree branch must be deleted after successful closure",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
 /**
  * @brief Verifies worktree-backed prompt orchestration against the pi runtime session-switch contract.
  * @details Simulates the current pi runtime behavior discovered in `/tmp/pi-mono`: `ctx.switchSession(...)` exposes the replacement session through `withSession(...)` and replacement-session contexts while the host process cwd stays anchored to the original project directory until the extension updates it explicitly. The test proves prompt delivery and prompt-end closure must synchronize `process.cwd()` with the active worktree session during execution and restore `base-path` plus remove the worktree after successful merge even when the pi host leaves cwd unchanged. Runtime is dominated by temporary git worktree setup and teardown. Side effects are limited to temporary repository mutation and temporary session-file writes.
@@ -5595,7 +5885,7 @@ test("default configuration applies the documented static-check, debug, notify,
     { module: "Command", cmd: "node", params: ["--check"] },
   ], "enable"));
   assert.deepEqual(config["static-check"].TypeScript, createStaticCheckLanguageConfig([
-    { module: "Command", cmd: "npx", params: ["eslint"] },
+    { module: "Command", cmd: "eslint", params: [] },
   ], "enable"));
   assert.deepEqual(config["static-check"].Ruby, createStaticCheckLanguageConfig([], "disable"));
   assert.equal(config.DEBUG_ENABLED, "disable");

package/tests/prompt-command-summary.test.ts

@@ -0,0 +1,36 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  DEFAULT_STATIC_CHECK_LANGUAGES,
+  getDefaultConfig,
+} from "../src/core/config.js";
+import { renderPromptCommandSummary } from "../src/core/prompts.js";
+
+/**
+ * @brief Builds a configuration with no enabled context files, no enabled static-check languages, and no enabled tools.
+ * @details Clones the documented default configuration, disables every context-file flag, forces every canonical static-check language to `disable`, and empties the enabled-tool list so the command invocation summary is forced to render the `none` placeholder for all three empty-category fields. Runtime is O(l) in supported language count. No external state is mutated.
+ * @param[in] projectBase {string} Absolute project root path used to seed the default configuration.
+ * @return {ReturnType<typeof getDefaultConfig>} Configuration object with all three summary categories empty.
+ */
+function buildEmptySummaryConfig(projectBase: string): ReturnType<typeof getDefaultConfig> {
+  const config = getDefaultConfig(projectBase);
+  config["context-files-requirements"] = false;
+  config["context-files-references"] = false;
+  config["context-files-workflow"] = false;
+  for (const language of DEFAULT_STATIC_CHECK_LANGUAGES) {
+    config["static-check"][language] = { ...config["static-check"][language], enabled: "disable" };
+  }
+  config["enabled-tools"] = [];
+  return config;
+}
+
+test("renderPromptCommandSummary renders none for empty context files, static code checks, and enabled tools", () => {
+  const projectBase = process.cwd();
+  const config = buildEmptySummaryConfig(projectBase);
+  const summary = renderPromptCommandSummary("analyze", "Inspect runtime behavior", config);
+  assert.match(summary, /Command: ANALYZE/);
+  assert.match(summary, /User's Request: Inspect runtime behavior/);
+  assert.match(summary, /- context files:       none/);
+  assert.match(summary, /- static code checks:  none/);
+  assert.match(summary, /- enabled tools:       none/);
+});

package/tests/static-check-bundled.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @file
+ * @brief Verifies bundled static-checker resolution, postinstall exit-code invariants, and session_start missing-checker notification.
+ * @details Exercises `resolveCheckerExecutable` bundled-bin precedence, the `scripts/install-static-checkers.ts` exit-code-0 invariant, and the `checkDefaultCheckersAvailability` helper used during `session_start`. Runtime is dominated by filesystem metadata checks and optional child-process execution. Side effects are limited to temporary filesystem reads and bounded writes under the installation-owned `node_modules/.bin` with cleanup.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import {
+  resolveCheckerExecutable,
+  checkDefaultCheckersAvailability,
+} from "../src/core/static-check.js";
+import { getInstallationPath } from "../src/core/path-context.js";
+import { getDefaultConfig } from "../src/core/config.js";
+import { main as installStaticCheckersMain } from "../scripts/install-static-checkers.ts";
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const TSX_LOADER = require.resolve("tsx", { paths: [ROOT] });
+
+/**
+ * @brief Resolves the bundled `node_modules/.bin` directory probed by `resolveCheckerExecutable`.
+ * @details Computes the first bundled-bin candidate directory derived from the runtime installation path so tests can create and clean up temporary fake executables at the exact probed location. Runtime is O(1). No side effects occur.
+ * @return {string} Absolute bundled `node_modules/.bin` directory path.
+ */
+function getBundledBinDir(): string {
+  return path.join(getInstallationPath(), "..", "node_modules", ".bin");
+}
+
+test("resolveCheckerExecutable probes bundled node_modules/.bin before PATH scan", () => {
+  const binDir = getBundledBinDir();
+  const fakeName = "pi-usereq-fake-checker";
+  const fakeBin = path.join(binDir, fakeName);
+  const dirExisted = fs.existsSync(binDir);
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(fakeBin, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    const resolved = resolveCheckerExecutable(fakeName);
+    assert.ok(resolved, "expected bundled-bin candidate to resolve");
+    assert.equal(resolved, fakeBin);
+  } finally {
+    if (fs.existsSync(fakeBin)) {
+      fs.rmSync(fakeBin, { force: true });
+    }
+    if (!dirExisted && fs.existsSync(binDir)) {
+      fs.rmSync(binDir, { recursive: true, force: true });
+    }
+  }
+});
+
+test("resolveCheckerExecutable falls back to PATH scan for system executables", () => {
+  const resolved = resolveCheckerExecutable("node");
+  assert.ok(resolved, "expected 'node' to resolve via PATH scan");
+});
+
+test("resolveCheckerExecutable returns undefined for non-existent commands", () => {
+  const resolved = resolveCheckerExecutable("pi-usereq-definitely-not-a-real-binary-xyz");
+  assert.equal(resolved, undefined);
+});
+
+test("scripts/install-static-checkers.ts always returns exit code 0", () => {
+  const exitCode = installStaticCheckersMain([]);
+  assert.equal(exitCode, 0);
+  const exitCodeWithArgs = installStaticCheckersMain(["--ignored"]);
+  assert.equal(exitCodeWithArgs, 0);
+});
+
+test("scripts/install-static-checkers.ts exits 0 when invoked as a subprocess", () => {
+  const result = spawnSync(
+    "node",
+    ["--import", TSX_LOADER, path.join(ROOT, "scripts", "install-static-checkers.ts")],
+    { encoding: "utf8" },
+  );
+  assert.equal(result.status, 0);
+});
+
+test("checkDefaultCheckersAvailability returns missing enabled checkers for default config", () => {
+  const config = getDefaultConfig(process.cwd());
+  const missing = checkDefaultCheckersAvailability(config);
+  assert.ok(Array.isArray(missing), "expected an array of missing checker names");
+  for (const checker of ["cppcheck", "clang-format"]) {
+    if (!resolveCheckerExecutable(checker)) {
+      assert.ok(missing.includes(checker), `expected missing checker '${checker}' to be reported`);
+    }
+  }
+});
+
+test("checkDefaultCheckersAvailability returns empty array when all checkers disabled", () => {
+  const config = getDefaultConfig(process.cwd());
+  for (const languageConfig of Object.values(config["static-check"])) {
+    languageConfig.enabled = "disable";
+  }
+  const missing = checkDefaultCheckersAvailability(config);
+  assert.equal(missing.length, 0);
+});