pi-usereq 0.40.0 → 0.41.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,7 +1,7 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.71"
+version: "0.0.73"
 date: "2026-07-10"
 author: "OpenAI Codex"
 scope:
@@ -162,6 +162,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-335**: MUST display a command invocation summary on screen for every bundled prompt-backed `req-<prompt>` command containing the command name, passed arguments, and active configuration.
 - **REQ-336**: MUST render the command invocation summary with the command name without the `req-` prefix in uppercase and the user request arguments.
 - **REQ-337**: MUST include `docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools` in the command invocation summary.
+- **REQ-338**: MUST render `none` for the command invocation summary `context files`, `static code checks`, and `enabled tools` fields whenever their respective enabled-item list is empty.
 - **REQ-008**: MUST provide a `Language static code checkers` submenu that adds global Command entries by guided language flow, removes configured global checker entries, toggles local per-language enablement, and resets static-check configuration.
 - **REQ-160**: MUST hardcode `Command` as the only user-configurable static-check module and omit module-selection UI from static-check configuration menus.
 - **REQ-161**: MUST hide `Dummy` from user-configurable static-check menus while preserving existing-config parsing and debug-driver support for `Dummy` entries.
@@ -395,12 +396,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-325**: MUST reject `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` execution when `DEBUG_TOOL_COMMANDS_ENABLED=disable`.
 - **REQ-326**: MUST add a top-level `Context Files` row to the `pi-usereq` menu between `Unit tests directory` and `Auto git commit`.
 - **REQ-327**: MUST expose a `Context Files` submenu with separate enable toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` in that order.
-- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to enabled.
+- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to disabled.
 - **REQ-329**: MUST replace the `%%CONTEXT_FILES%%` prompt token with one markdown section per enabled context file in the order `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md`.
 - **REQ-330**: MUST render each `%%CONTEXT_FILES%%` section as the file-name heading, an HTML `<file name="<docs-dir>/<filename>">` reference with `%%DOC_PATH%%` pre-substituted, and the raw file content inside four-backtick `markdown` fences.
 - **REQ-331**: MUST omit the `%%CONTEXT_FILES%%` section for any disabled flag or missing context file without surfacing an error.
 - **REQ-332**: MUST inject `%%CONTEXT_FILES%%` content verbatim after every other prompt replacement so literal `%%...%%` tokens inside context files are not substituted.
-- **REQ-333**: MUST restore all three `Context Files` flags to enabled when the `Context Files` subtree `Reset defaults` is approved.
+- **REQ-333**: MUST restore all three `Context Files` flags to disabled when the `Context Files` subtree `Reset defaults` is approved.
 
 ## 4. Test Requirements
 - **TST-001**: MUST verify extension activation registers every documented prompt command, agent tool, and configuration command while omitting tool-name slash commands, `test-static-check`, and the removed standalone config-viewer command.
@@ -522,6 +523,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-118**: MUST verify the `Context Files` submenu persists the three context-file flags in local configuration with immediate-save, reset, and focus-preserving re-render behavior.
 - **TST-119**: MUST verify `%%CONTEXT_FILES%%` replacement emits one section per enabled existing file in the documented order and omits disabled or missing files.
 - **TST-120**: MUST verify `%%CONTEXT_FILES%%` sections use the file-name heading, the pre-substituted HTML file reference, and four-backtick `markdown` fences around raw content.
+- **TST-122**: MUST verify the command invocation summary renders `none` for `context files`, `static code checks`, and `enabled tools` when no items are enabled in each respective category.
 
 ## 5. Observed Component Model
 

package/pi-usereq/docs/WORKFLOW.md

@@ -575,8 +575,8 @@
             - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
         - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`src/core/prompts.ts`]
           - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.ts`]
-        - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name, user request arguments, and active configuration fields [`src/core/prompts.ts`]
-        - `deliverPromptCommand(...)`: dispatch the rendered prompt as a hidden `display:false` custom message plus a `display:true` summary into the current recorded session, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.ts`]
+        - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name, user request arguments, and active configuration fields, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`src/core/prompts.ts`]
+        - `deliverPromptCommand(...)`: dispatch the rendered prompt as a hidden `display:false` custom message plus a `display:true` summary into the current recorded session, awaiting and suppressing summary delivery failures before the hidden prompt turn, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.ts`]
           - External boundaries: `RecordingExtensionAPI.sendMessage(...)` or fallback `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload plus summary.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
           - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, plus display-only local and global config-path rows [`src/index.ts`]
@@ -880,8 +880,8 @@
         - `writePersistedPromptCommandSessionContext(...)`: store the reusable command-capable replacement-session context for later closure handling [`src/core/prompt-command-state.ts`]
         - `clearPersistedPromptCommandSessionContext(...)`: drop reusable command-context persistence when worktree routing is inactive [`src/core/prompt-command-state.ts`]
       - `logPromptWorkflowEvent(...)`: append selected workflow-activation debug entries [`src/index.ts`]
-      - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name without the `req-` prefix in uppercase, user request arguments, and active configuration fields [`src/core/prompts.ts`]
-      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt as a hidden `display:false` custom message with `triggerTurn:true` plus a `display:true` command invocation summary into the current active session after execution-session activation is verified, preferring replacement-session `sendMessage(...)` when available, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
+      - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name without the `req-` prefix in uppercase, user request arguments, and active configuration fields, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`src/core/prompts.ts`]
+      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt as a hidden `display:false` custom message with `triggerTurn:true` plus a `display:true` command invocation summary into the current active session after execution-session activation is verified, preferring replacement-session `sendMessage(...)` when available, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable, awaiting and suppressing the non-critical summary delivery before 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, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
         - `writePersistedPromptCommandRuntimeState(...)`: mirror the prepared prompt execution plan into process-scoped persistence before the worktree session switch returns control [`src/core/prompt-command-state.ts`]
         - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendMessage(...)` [`src/core/extension-status.ts`]
         - External boundaries: replacement-session `sendMessage(...)` or `pi.sendMessage(...)` delivers the hidden rendered prompt payload plus the displayed summary into the active `AgentSession`; fallback replacement-session `sendUserMessage(...)` or `pi.sendUserMessage(...)` delivers the rendered prompt payload when `sendMessage(...)` is unavailable.

package/src/core/config.ts

@@ -214,14 +214,14 @@ export const DEFAULT_TESTS_DIR = "tests";
 export const DEFAULT_SRC_DIRS = ["src"];
 /**
  * @brief Defines the default value for every persisted context-file injection flag.
- * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to enabled so the bundled canonical documents remain part of the prompt context unless the user explicitly disables one. Lookup complexity is O(1).
+ * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to disabled so the bundled canonical documents are excluded from the prompt context unless the user explicitly enables one. Lookup complexity is O(1).
  * @satisfies REQ-328
  */
-export const DEFAULT_CONTEXT_FILES_FLAG = true;
+export const DEFAULT_CONTEXT_FILES_FLAG = false;
 
 /**
  * @brief Normalizes one persisted context-file injection flag.
- * @details Returns the documented default (`true`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection enabled. Runtime is O(1). No external state is mutated.
+ * @details Returns the documented default (`false`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection disabled. Runtime is O(1). No external state is mutated.
  * @param[in] value {unknown} Candidate persisted context-file flag.
  * @return {boolean} Normalized context-file injection flag.
  * @satisfies REQ-328

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

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
@@ -20,6 +20,7 @@ import {
   type DebugWorkflowState,
 } from "./debug-runtime.js";
 import { type PromptCommandName } from "./prompt-command-catalog.js";
+export { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
   isSameOrAncestorPath,
   normalizeRelativeDirContract,
@@ -119,14 +120,13 @@ interface PromptCommandActiveContext extends PromptCommandSessionContext {
 
 /**
  * @brief Describes one serializable session entry copied into a materialized execution-session file.
- * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. The interface is compile-time only and introduces no runtime cost.
+ * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. Mirrors the SDK `SessionEntryBase` shape without an index signature so the SDK `SessionEntry` union remains structurally assignable for passthrough serialization. The interface is compile-time only and introduces no runtime cost.
  */
 interface PromptCommandSessionEntry {
   type: string;
   id: string;
   parentId: string | null;
   timestamp: string;
-  [key: string]: unknown;
 }
 
 /**
@@ -705,7 +705,7 @@ async function switchPromptCommandSession(
     throw new ReqError(`ERROR: Prompt orchestration requires ctx.switchSession() for ${sessionFile}.`, 1);
   }
   let replacementContext: PromptCommandActiveContext | undefined;
-  let switchResult: { cancelled?: boolean } | void;
+  let switchResult: { cancelled?: boolean } | void = undefined;
   try {
     switchResult = await ctx.switchSession(sessionFile, {
       withSession: async (activeContext) => {
@@ -840,9 +840,9 @@ const PROMPT_REQUIRED_DOCS: Record<PromptCommandName, readonly PromptRequiredDoc
  * @details Delegates to `spawnSync`, preserves the supplied working directory, and returns the raw subprocess result used by prompt-command orchestration. Runtime is dominated by external process execution. Side effects include process spawning.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 decoded stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/prompts.ts

@@ -375,12 +375,12 @@ export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
 
 /**
  * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
- * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
  * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
  * @param[in] args {string} User request arguments passed to the slash command.
  * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
  * @return {string} Multi-line command invocation summary text.
- * @satisfies REQ-335, REQ-336, REQ-337
+ * @satisfies REQ-335, REQ-336, REQ-337, REQ-338
  */
 export function renderPromptCommandSummary(
   promptName: string,
@@ -390,17 +390,17 @@ export function renderPromptCommandSummary(
   const contextFiles = CONTEXT_FILE_DESCRIPTORS
     .filter((descriptor) => config[descriptor.flagKey])
     .map((descriptor) => descriptor.fileName.replace(/\.md$/, "").toLowerCase())
-    .join(", ");
+    .join(", ") || "none";
   const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
     .filter((language) => config["static-check"][language]?.enabled === "enable")
-    .join(", ");
-  const enabledTools = [...config["enabled-tools"]]
+    .join(", ") || "none";
+  const enabledTools = ([...config["enabled-tools"]]
     .sort((left, right) =>
       comparePiUsereqStartupToolNames(
         left as PiUsereqStartupToolName,
         right as PiUsereqStartupToolName,
       ))
-    .join(", ");
+    .join(", ") || "none");
   const effectiveWorktree = resolveEffectiveGitWorktreeEnabled(
     config.AUTO_GIT_COMMIT,
     config.GIT_WORKTREE_ENABLED,

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

@@ -4,7 +4,7 @@
  * @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import path from "node:path";
 import type { UseReqConfig } from "./config.js";
 import { ReqError } from "./errors.js";
@@ -39,9 +39,9 @@ export interface ReqReferencesCommandPlan {
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

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

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import {
   normalizeGitWorktreePrefix,
   type UseReqConfig,
@@ -63,9 +63,9 @@ type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

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

@@ -5,7 +5,7 @@
  */
 
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { isSameOrAncestorPath } from "./path-context.js";
 
@@ -14,9 +14,9 @@ import { isSameOrAncestorPath } from "./path-context.js";
  * @details Delegates to `spawnSync`, keeps execution synchronous for deterministic command flows, and supports an optional working directory. Runtime is dominated by the spawned git process. Side effects include subprocess creation.
  * @param[in] command {string[]} Git executable plus argument vector.
  * @param[in] cwd {string | undefined} Optional working directory.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runGitCapture(command: string[], cwd?: string): ReturnType<typeof spawnSync> {
+function runGitCapture(command: string[], cwd?: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/index.ts

@@ -910,7 +910,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 +942,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 +960,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 +1087,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 +1096,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);

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.