pi-usereq 0.43.0 → 0.45.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.75"
-date: "2026-07-10"
+version: "0.0.77"
+date: "2026-07-13"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -93,6 +93,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-016**: MUST deliver rendered bundled-prompt content to the LLM through `sendMessage` as a `display:false` custom message with `triggerTurn:true` and MUST NOT use `sendUserMessage` when `sendMessage` is available.
 - **DES-017**: MUST declare `pyright`, `ruff`, and `eslint` as pinned caret-range npm dependencies and register a `postinstall` script that installs bundled static checkers.
 - **DES-018**: MUST resolve checker executables by probing bundled `node_modules/.bin` paths relative to the installation path before falling back to `PATH` scan.
+- **DES-019**: MUST resolve the `%%INSTALLATION_PATH%%` keyword inside static-check `Command` `cmd` fields to the runtime installation path within `resolveCheckerExecutable` before executable probing.
+- **DES-020**: MUST extend `scripts/install-static-checkers.ts` to best-effort approve pending npm install scripts for bundled checker dependencies before probing bundled executables.
 
 ### 3.2 Functions
 - **REQ-001**: MUST access bundled prompts, git execution instructions, templates, and guidelines from `<installation-path>/resources` without requiring user-home resource copies before prompt or tool execution.
@@ -166,10 +168,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **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-008**: MUST provide a `Language static code checkers` submenu that adds, views, confirms-before-removes, and resets global Command checker entries, plus toggles local per-language enablement.
 - **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.
-- **REQ-248**: MUST render 20 per-language static-check toggle rows between `Remove static code checker` and `Reset defaults`, with right-aligned `on|off` values derived from persisted local enablement.
+- **REQ-248**: MUST render 20 per-language static-check toggle rows between `Reset static code checker` and `Reset defaults`, with right-aligned `on|off` values derived from persisted local enablement.
 - **REQ-249**: MUST persist local `static-check.<language>.enabled` with allowed values `enable|disable` and global `static-check.<language>.checkers` as ordered arrays.
 - **REQ-250**: MUST default global `static-check.C` and `static-check.C++` checker arrays to documented `cppcheck` and `clang-format` Command entries.
 - **REQ-251**: MUST default global `static-check.Python`, `JavaScript`, and `TypeScript` checker arrays to their documented Command entries.
@@ -258,7 +260,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-290**: MUST preserve the successful worktree execution transcript in the restored client-visible session after successful closure.
 - **REQ-291**: MUST detect staged or unstaged `base-path` changes before successful closure merge and execute `git stash`, merge, and `git stash pop` in that order when changes exist.
 - **REQ-292**: MUST complete successful stash-assisted closure without surfacing an error and MUST emit a warning that the restored `base-path` is not clean after merge.
-- **REQ-209**: MUST restore the original session-backed `base-path`, notify the pi CLI of closure failure, and retain the worktree plus branch when orchestrated session closure is interrupted, failed, aborted, or incomplete.
+- **REQ-209**: MUST retain the worktree execution session, worktree, and branch, notify the pi CLI of closure failure, park workflow state in `error`, and leave the original base-path session unresumed when orchestrated session closure is interrupted, failed, aborted, or incomplete.
 - **REQ-221**: MUST maintain one prompt-orchestration state machine with states `idle`, `checking`, `running`, `merging`, and `error`.
 - **REQ-222**: MUST render `status` as the first single-line status field and refresh it on every internal or pi CLI state transition.
 - **REQ-223**: MUST render `status:error` with theme `error` plus terminal blink when supported, and other `status` values with the existing non-error status-bar convention.
@@ -283,7 +285,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-313**: MUST make failing `req-reset` surface restoration or cleanup failures, transition workflow state to `error`, and preserve already-completed cleanup effects.
 - **REQ-228**: MUST transition workflow state to `merging` immediately before merge and worktree/branch deletion begin during successful orchestrated session closure.
 - **REQ-229**: MUST transition workflow state to `error` and notify the pi CLI when base-path restoration, merge, or worktree/branch deletion verification fails during orchestrated session closure.
-- **REQ-230**: MUST transition workflow state to `idle` before the orchestrated session-closure handler returns.
+- **REQ-230**: MUST transition workflow state to `idle` before the orchestrated session-closure handler returns for completed runs.
 - **REQ-219**: MUST verify created worktree registration via `git worktree list`, branch presence via `git branch` list, and filesystem path existence before changing the prompt execution path or dispatching a prompt message.
 - **REQ-256**: MUST store `base-path`, `context-path`, `git-path`, `parent-path`, `base-dir`, `worktree-dir`, `worktree-path`, branch name, original session file, and execution session file inside prompt-orchestration runtime state.
 - **REQ-272**: MUST verify post-switch execution targets before agent start using replacement-session context when available, the persisted execution-session header cwd, and `process.cwd()`, and MUST NOT rely on stale pre-switch session-bound objects.
@@ -411,6 +413,14 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-342**: MUST keep `STATIC_CHECK_MODULES`, `dispatchStaticCheckForFile` signature, and `StaticCheckEntry` shape unchanged when adding bundled executable resolution.
 - **REQ-343**: MUST NOT transition workflow state or abort `session_start` when one or more enabled static checkers are missing.
 - **REQ-344**: MUST place the `session_start` missing-checker helper in `src/core/static-check.ts` so `src/index.ts` remains thin.
+- **REQ-345**: MUST expose `View static code checker` immediately before `Remove static code checker` inside the `Language static code checkers` submenu.
+- **REQ-346**: MUST make `View static code checker` render configured checker entries as read-only disabled inspection rows terminated by a `Close` row without mutating configuration.
+- **REQ-347**: MUST expose `Reset static code checker` immediately after `Remove static code checker` inside the `Language static code checkers` submenu.
+- **REQ-348**: MUST make `Reset static code checker` restore global checker arrays plus derived local enable flags to embedded defaults after explicit user confirmation.
+- **REQ-349**: MUST render the targeted configured checker entries and require explicit user confirmation before `Remove static code checker` removes any global checker entries.
+- **REQ-350**: MUST substitute the `%%INSTALLATION_PATH%%` keyword with the runtime extension installation path inside static-check `Command` `cmd` fields before executable resolution and execution.
+- **REQ-351**: MUST resolve bundled static-check executables from the extension installation `node_modules/.bin` so default configuration requires no target-project module installation.
+- **REQ-352**: MUST best-effort approve pending npm install scripts for bundled checker dependencies during extension install or run so embedded checkers execute without manual approval.
 
 ## 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.
@@ -421,7 +431,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-005**: MUST verify the configuration menu saves `docs-dir` locally and `AUTO_GIT_COMMIT`, `GIT_WORKTREE_ENABLED`, plus `GIT_WORKTREE_PREFIX` globally immediately after each change.
 - **TST-084**: MUST verify local configuration persistence trims trailing `/` and keeps `docs-dir`, `tests-dir`, and `src-dir` relative.
 - **TST-046**: MUST verify `Language static code checkers` omits module selection, raw-spec actions, supported-language reference actions, and hides `Dummy`, `Pylance`, and `Ruff` from user-configurable actions.
-- **TST-077**: MUST verify `Language static code checkers` renders 20 per-language `on|off` toggle rows between `Remove static code checker` and `Reset defaults`, and persists toggle changes only in local configuration.
+- **TST-077**: MUST verify `Language static code checkers` renders 20 per-language `on|off` toggle rows between `Reset static code checker` and `Reset defaults`, and persists toggle changes only in local configuration.
 - **TST-078**: MUST verify default configuration stores documented per-language `enabled` flags locally and checker lists globally for `C`, `C++`, `Python`, `JavaScript`, and `TypeScript`.
 - **TST-108**: MUST verify guided static-check entry addition updates global checker lists and sets the targeted local enable flag to `enable`, and guided removal updates global checker lists.
 - **TST-112**: MUST verify `--enable-static-check` stores checker commands in global configuration and preserves local enablement according to the documented defaulting rules.
@@ -510,7 +520,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-055**: MUST verify bundled prompt-backed `req-<prompt>` commands enforce the documented required-doc matrix, create no worktree, and dispatch no prompt when a required doc is missing.
 - **TST-056**: MUST verify worktree-backed `req-<prompt>` commands derive `worktree-dir` from persisted `GIT_WORKTREE_PREFIX` for both default and override values.
 - **TST-057**: MUST verify `req-<prompt>` commands create `worktree-path`, dispatch prompts through the replacement-session context of the switched execution session, and run tool executions against prepared `context-path`.
-- **TST-058**: MUST verify worktree-backed `req-<prompt>` commands skip merge plus worktree/branch deletion, restore `base-path`, and notify pi CLI of closure failure when the matched run ends interrupted, failed, or aborted.
+- **TST-058**: MUST verify worktree-backed `req-<prompt>` commands skip merge plus worktree/branch deletion, retain the worktree execution session, notify closure failure, and park workflow state `error` when the matched run ends interrupted, failed, or aborted.
 - **TST-061**: MUST verify `req-<prompt>` commands skip worktree creation when `AUTO_GIT_COMMIT=disable`, even if persisted `GIT_WORKTREE_ENABLED=enable`.
 - **TST-064**: MUST verify worktree-backed `req-<prompt>` commands confirm created worktree directory plus branch existence before prompt dispatch and abort without dispatch when verification fails.
 - **TST-067**: MUST verify `status:error` renders with blinking error styling and non-error `status` values follow the documented status-bar theme convention.
@@ -536,6 +546,11 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-123**: MUST verify `resolveCheckerExecutable` probes bundled `node_modules/.bin` paths before `PATH` scan.
 - **TST-124**: MUST verify `scripts/install-static-checkers.ts` always returns exit code `0` regardless of probe or install outcomes.
 - **TST-125**: MUST verify `session_start` emits one warning notification for missing enabled checkers without aborting or transitioning workflow state.
+- **TST-126**: MUST verify `View static code checker` appears before `Remove static code checker` and renders configured checkers as read-only inspection rows.
+- **TST-127**: MUST verify `Reset static code checker` appears after `Remove static code checker` and restores embedded defaults after explicit confirmation.
+- **TST-128**: MUST verify `Remove static code checker` previews targeted checker entries and requires explicit confirmation before removing configured global checker entries.
+- **TST-129**: MUST verify `resolveCheckerExecutable` substitutes `%%INSTALLATION_PATH%%` with the runtime installation path inside static-check `Command` `cmd` fields.
+- **TST-130**: MUST verify `scripts/install-static-checkers.ts` best-effort approves pending npm install scripts and always returns exit code `0`.
 
 ## 5. Observed Component Model
 

package/pi-usereq/docs/WORKFLOW.md

@@ -51,7 +51,7 @@
   - Threads: no explicit threads detected
 - ID: `PROC:install-static-checkers`
   - Type: Process
-  - Role: Best-effort npm `postinstall` installer that probes bundled static-checker executables, attempts `npm install` on miss, and prints platform guidance for native checkers.
+  - Role: Best-effort npm `postinstall` installer that approves pending install scripts, probes bundled static-checker executables, attempts `npm install` on miss, and prints platform guidance for native checkers.
   - Entrypoints:
     - `main(...)` [`scripts/install-static-checkers.ts`]
   - Parent Process: none
@@ -990,7 +990,7 @@
       - `setPiUsereqRuntimeSoundLevel(...)`: store the cycled runtime sound level and refresh the footer [`src/core/extension-status.ts`]
         - `renderPiUsereqStatus(...)`: refresh the single-line footer after shortcut-driven runtime sound changes [`src/core/extension-status.ts`]
     - `registerExtensionStatusHooks(...)`: register shared wrappers for lifecycle telemetry hooks and suppress the documented stale-extension-context callbacks that can arrive after successful session replacement [`src/index.ts`]
-      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers, tool-result debug logging, dedicated workflow-closure plus shutdown diagnostics built from pre-shutdown prompt snapshots, workflow-state transitions, recover a live bootstrap cwd during `session_start` when stale context mirrors still point at deleted worktrees, matched-success prompt-command restoration to `base-path` plus stash-assisted merge and worktree deletion even after a busy-command rejection moved workflow state to `error`, warning-only closure notifications when restored `base-path` changes are reapplied, stale-safe closure notifications, and matched-failure base-path restoration plus closure-error notification using persisted replacement-session contexts when event hooks omit `switchSession()` [`src/index.ts`]
+      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers, tool-result debug logging, dedicated workflow-closure plus shutdown diagnostics built from pre-shutdown prompt snapshots, workflow-state transitions, recover a live bootstrap cwd during `session_start` when stale context mirrors still point at deleted worktrees, matched-success prompt-command restoration to `base-path` plus stash-assisted merge and worktree deletion even after a busy-command rejection moved workflow state to `error`, warning-only closure notifications when restored `base-path` changes are reapplied, stale-safe closure notifications, and matched-failure worktree-execution-session retention plus closure-error notification and workflow `error` parking without resuming `base-path` so the failure stays visible, leaving `base-path` restoration plus worktree and branch cleanup to `req-reset` [`src/index.ts`]
         - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the startup context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
         - `syncContextCwdMirror(...)`: best-effort realign the startup context `cwd` mirror to the recovered live cwd before startup config loads [`src/index.ts`]
         - `loadProjectConfig(...)`: session-start configuration load from the recovered live cwd [`src/index.ts`]
@@ -1098,7 +1098,7 @@
           - `finalizePromptCommandMerge(...)`: inspect tracked `base-path` changes, run `git stash` plus `git stash pop` around the existing `--ff-only` merge when tracked changes exist, emit a warning-only merge result after reapplying local changes, and append selected merge debug entries [`src/core/prompt-command-runtime.ts`]
             - `listPromptTrackedBasePathChanges(...)`: parse tracked staged or unstaged `git status --porcelain` rows and ignore untracked or ignored rows before stash-assisted merge selection [`src/core/prompt-command-runtime.ts`]
           - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful stash-assisted fast-forward merge [`src/core/prompt-command-runtime.ts`]
-        - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path when interrupted, failed, or unmatched prompt-end events skip merge and retain the worktree for manual recovery, reusing the persisted replacement-session context when lifecycle hooks omit `switchSession()` [`src/core/prompt-command-runtime.ts`]
+        - `restorePromptCommandExecution(...)`: reset runtime path state for non-worktree prompt-end events; worktree-backed interrupted, failed, aborted, or incomplete runs skip restoration, retain the worktree execution session, park workflow state in `error`, and leave `base-path` restoration plus worktree and branch cleanup to `req-reset` [`src/core/prompt-command-runtime.ts`]
           - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
             - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
           - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
@@ -1191,12 +1191,12 @@
         - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
           - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
           - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-    - `configureStaticCheckMenu(...)`: interactive editor that adds and removes global Command entries while toggling local per-language enable flags [`src/index.ts`]
+    - `configureStaticCheckMenu(...)`: interactive editor that adds, inspects, confirms-before-removes, and resets global Command entries while toggling local per-language enable flags [`src/index.ts`]
       - `getStaticCheckLanguageConfigForMenu(...)`: resolve a menu-facing per-language static-check object [`src/index.ts`]
       - `countConfiguredStaticCheckLanguages(...)`: count languages that retain global checker entries [`src/index.ts`]
       - `countEnabledStaticCheckLanguages(...)`: count languages whose local enable flag is on [`src/index.ts`]
       - `formatStaticCheckLanguagesSummary(...)`: summarize enabled languages and configured global checker languages [`src/index.ts`]
-      - `buildStaticCheckMenuChoices(...)`: serialize guided add/remove actions plus direct per-language local toggle rows [`src/index.ts`]
+      - `buildStaticCheckMenuChoices(...)`: serialize guided add/view/remove/reset actions plus direct per-language local toggle rows [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
@@ -1208,6 +1208,11 @@
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
+      - `formatStaticCheckCheckerEntry(...)`: format one checker entry as a shell-like command summary for inspection and confirmation menus [`src/index.ts`]
+      - `formatStaticCheckLanguageCheckerSummary(...)`: summarize configured checkers for one language as a delimited command list [`src/index.ts`]
+      - `buildStaticCheckViewChoices(...)`: serialize configured checkers as read-only disabled inspection rows terminated by a `Close` row [`src/index.ts`]
+      - `buildStaticCheckRemovalConfirmationChoices(...)`: serialize targeted checker preview rows plus approve and abort actions for removal confirmation [`src/index.ts`]
+      - `confirmStaticCheckRemoval(...)`: open one explicit removal-confirmation submenu and return the approval result [`src/index.ts`]
       - `resetStaticCheckConfig(...)`: restore documented per-language static-check defaults [`src/index.ts`]
         - `getDefaultStaticCheckConfig(...)`: build documented per-language static-check defaults [`src/core/config.ts`]
           - `createStaticCheckLanguageConfig(...)`: clone checker entries and derive the enable flag [`src/core/config.ts`]
@@ -1302,8 +1307,10 @@
   - Looping model: single-pass probe plus optional install with no persistent loop.
   - Threads: no explicit threads detected.
 - Internal Call-Trace Tree:
-  - `main(...)`: probe each bundled npm checker, attempt best-effort install on miss, print native-checker guidance, and return `0` [`scripts/install-static-checkers.ts`]
-    - `resolveCheckerExecutable(...)`: resolve one checker across bundled `node_modules/.bin` locations and PATH scan [`src/core/static-check.ts`]
+  - `main(...)`: best-effort approve pending npm install scripts, probe each bundled npm checker, attempt best-effort install on miss, print native-checker guidance, and return `0` [`scripts/install-static-checkers.ts`]
+    - `approvePendingInstallScripts(...)`: best-effort approve pending npm install scripts for bundled checker dependencies before probing [`scripts/install-static-checkers.ts`]
+      - `hasPendingInstallScriptPackages(...)`: report whether the parsed pending-scripts payload references install-script packages [`scripts/install-static-checkers.ts`]
+    - `resolveCheckerExecutable(...)`: resolve one checker across `%%INSTALLATION_PATH%%` keyword, bundled `node_modules/.bin`, and PATH scan locations [`src/core/static-check.ts`]
       - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
         - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
     - `attemptBundledInstall(...)`: best-effort `npm install <pkg>@<range> --no-save --prefix <install-root>` swallowing all errors [`scripts/install-static-checkers.ts`]

package/scripts/install-static-checkers.ts

@@ -42,6 +42,52 @@ function bundledCheckerRange(pkg: string): string {
   }
 }
 
+/**
+ * @brief Reports whether one parsed `npm approve-scripts --allow-scripts-pending` payload references pending install-script packages.
+ * @details Accepts an array of package specifiers or a map of package specifiers to pending-script descriptors, treating any non-empty array or non-empty object with at least one entry as pending. Runtime is O(n) in pending entry count. No external state is mutated.
+ * @param[in] pending {unknown} Parsed JSON payload emitted by `npm approve-scripts --allow-scripts-pending`.
+ * @return {boolean} `true` when at least one pending install-script package is referenced.
+ */
+function hasPendingInstallScriptPackages(pending: unknown): boolean {
+  if (Array.isArray(pending)) {
+    return pending.length > 0;
+  }
+  if (pending && typeof pending === "object") {
+    return Object.keys(pending as Record<string, unknown>).length > 0;
+  }
+  return false;
+}
+
+/**
+ * @brief Best-effort approves pending npm install scripts for bundled checker dependencies.
+ * @details Probes `npm approve-scripts --allow-scripts-pending`, parses the JSON payload when available, and runs `npm approve-scripts --all` only when pending script-bearing packages are detected so bundled checkers and their transitive dependencies execute without manual script approval. Swallows all errors so the postinstall flow never fails. Runtime is dominated by npm execution. Side effects include optional writes to the installation-owned `package.json` allowScripts map and subprocess spawning.
+ * @return {void} No return value.
+ * @satisfies DES-020, REQ-352
+ */
+function approvePendingInstallScripts(): void {
+  const pendingResult = spawnSync(
+    "npm",
+    ["approve-scripts", "--allow-scripts-pending", "--json"],
+    { encoding: "utf8" },
+  );
+  if (pendingResult.error || (pendingResult.status !== null && pendingResult.status !== 0)) {
+    return;
+  }
+  let pendingPayload: unknown;
+  try {
+    pendingPayload = JSON.parse(pendingResult.stdout ?? "");
+  } catch {
+    return;
+  }
+  if (!hasPendingInstallScriptPackages(pendingPayload)) {
+    return;
+  }
+  const approveResult = spawnSync("npm", ["approve-scripts", "--all"], { encoding: "utf8" });
+  if (approveResult.error) {
+    process.stderr.write(`Warning: failed to approve pending install scripts: ${approveResult.error.message}\n`);
+  }
+}
+
 /**
  * @brief Prints platform-specific install guidance for native checkers.
  * @details Detects the current platform and emits one consolidated stderr line per native checker describing the recommended system package manager command. Runtime is O(1). Side effect: writes to stderr.
@@ -101,10 +147,11 @@ function attemptBundledInstall(pkg: string): void {
  * @details Probes each bundled npm checker through `resolveCheckerExecutable`, attempts a best-effort install on miss, prints native-checker guidance for unresolvable native checkers, and always returns `0` so `npm install` never fails because of missing optional checkers. Runtime is dominated by PATH probing and optional npm execution. Side effects include stdout/stderr writes and best-effort `npm install` subprocess spawning. The script never modifies git-tracked files.
  * @param[in] argv {string[]} Raw CLI arguments (unused, retained for CLI convention parity).
  * @return {number} Always returns `0`.
- * @satisfies REQ-339, DES-017
+ * @satisfies REQ-339, DES-017, DES-020, REQ-352
  */
 export function main(argv = process.argv.slice(2)): number {
   void argv;
+  approvePendingInstallScripts();
   for (const checker of BUNDLED_NPM_CHECKERS) {
     if (resolveCheckerExecutable(checker)) {
       process.stdout.write(`Bundled static checker '${checker}' is available.\n`);

package/src/core/static-check.ts

@@ -399,11 +399,12 @@ 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 (!resolveCheckerExecutable(cmd)) {
+    const resolvedCmd = resolveCheckerExecutable(cmd);
+    if (!resolvedCmd) {
       throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
     }
     super(inputs, extraArgs, failOnly);
-    this.cmd = cmd;
+    this.cmd = cmd.includes("%%INSTALLATION_PATH%%") ? resolvedCmd : cmd;
     this.label = `Command[${cmd}]`;
   }
 
@@ -475,20 +476,25 @@ export function findExecutable(cmd: string): string | 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.
+ * @brief Resolves one checker executable across installation-keyword, bundled `node_modules/.bin`, and PATH locations.
+ * @details Substitutes the `%%INSTALLATION_PATH%%` keyword with the runtime installation path and verifies the resulting explicit path when present, then 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 so default configuration requires no target-project module installation. 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, explicit path, or `%%INSTALLATION_PATH%%`-anchored 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
+ * @satisfies REQ-023, REQ-037, DES-018, DES-019, REQ-350, REQ-351
  */
 export function resolveCheckerExecutable(cmd: string): string | undefined {
+  if (cmd.includes("%%INSTALLATION_PATH%%")) {
+    const installationPath = getInstallationPath();
+    const resolvedPath = cmd.split("%%INSTALLATION_PATH%%").join(installationPath);
+    return isExecutableFile(resolvedPath) ? path.resolve(resolvedPath) : 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),
+    path.join(installationPath, "..", "..", ".bin", cmd),
   ];
   for (const candidate of bundledBinCandidates) {
     if (isExecutableFile(candidate)) {

package/src/index.ts

@@ -1454,6 +1454,26 @@ async function handleExtensionStatusEvent(
         ) {
           notifyContextSafely(promptContext, finalization.warningMessage, "info");
         }
+      } else if (closureFailureMessage !== undefined) {
+        // Worktree-backed run that ended interrupted, failed, aborted, or
+        // incomplete (REQ-209): keep the worktree execution session visible,
+        // surface the closure-failure error, park the workflow in `error`, and
+        // retain the active request so `req-reset` can restore `base-path` and
+        // remove the retained worktree plus branch. The original base-path
+        // session MUST NOT be resumed here so the failure stays visible.
+        notifyContextSafely(promptContext, closureFailureMessage, "error");
+        if (debugConfig) {
+          transitionPromptWorkflowState(
+            statusController,
+            promptContext,
+            activePromptRequest.basePath,
+            debugConfig,
+            activePromptRequest.promptName,
+            "error",
+          );
+        } else {
+          setPiUsereqWorkflowState(statusController, "error", promptContext);
+        }
       } else {
         try {
           promptContext = (await restorePromptCommandExecution(
@@ -1463,9 +1483,6 @@ async function handleExtensionStatusEvent(
               ? { config: debugConfig, workflowState: statusController.state.workflowState }
               : undefined,
           ) ?? promptContext) as typeof ctx;
-          if (closureFailureMessage !== undefined) {
-            notifyContextSafely(promptContext, closureFailureMessage, "error");
-          }
         } catch (error) {
           promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
           if (debugConfig) {
@@ -1483,19 +1500,21 @@ async function handleExtensionStatusEvent(
           notifyContextSafely(promptContext, error instanceof Error ? error.message : String(error), "error");
         }
       }
-      statusController.state.pendingPromptRequest = undefined;
-      statusController.state.activePromptRequest = undefined;
-      if (debugConfig) {
-        transitionPromptWorkflowState(
-          statusController,
-          promptContext,
-          activePromptRequest.basePath,
-          debugConfig,
-          activePromptRequest.promptName,
-          "idle",
-        );
-      } else {
-        setPiUsereqWorkflowState(statusController, "idle", promptContext);
+      if (closureFailureMessage === undefined) {
+        statusController.state.pendingPromptRequest = undefined;
+        statusController.state.activePromptRequest = undefined;
+        if (debugConfig) {
+          transitionPromptWorkflowState(
+            statusController,
+            promptContext,
+            activePromptRequest.basePath,
+            debugConfig,
+            activePromptRequest.promptName,
+            "idle",
+          );
+        } else {
+          setPiUsereqWorkflowState(statusController, "idle", promptContext);
+        }
       }
     }
   }
@@ -3772,7 +3791,7 @@ function formatStaticCheckLanguagesSummary(config: UseReqConfig): string {
  * @details Serializes guided Command-oriented add and remove actions, renders one direct on/off toggle row for every supported language, and appends canonical terminal rows while omitting raw-spec and reference-only actions. Runtime is O(l). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
- * @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248
+ * @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248, REQ-345, REQ-347
  */
 function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const supportedLanguages = getSupportedStaticCheckLanguageSupport();
@@ -3784,11 +3803,23 @@ function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenu
       value: `${supportedLanguages.length} languages`,
       description: "Select a supported language, then configure one Command static-check executable.",
     },
+    {
+      id: "view-static-check-entry",
+      label: "View static code checker",
+      value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
+      description: "Inspect the configured Command static-check entries for every language without mutating configuration.",
+    },
     {
       id: "remove-static-check-entry",
       label: "Remove static code checker",
       value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
-      description: "Remove every configured static-check entry for one language.",
+      description: "Preview and confirm removal of every configured static-check entry for one language.",
+    },
+    {
+      id: "reset-static-check-entry",
+      label: "Reset static code checker",
+      value: "embedded defaults",
+      description: "Restore the documented per-language static-check defaults after explicit confirmation.",
     },
     ...supportedLanguages.map(({ language, extensions }) => {
       const languageConfig = getStaticCheckLanguageConfigForMenu(config, language);
@@ -3858,13 +3889,164 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
   ];
 }
 
+/**
+ * @brief Formats one static-check checker entry as a compact command summary.
+ * @details Joins the module command plus its parameter list into a single shell-like token sequence so inspection and confirmation menus can render checker identity deterministically. Runtime is O(p) in parameter count. No external state is mutated.
+ * @param[in] entry {StaticCheckEntry} Static-check configuration entry.
+ * @return {string} Compact command summary string.
+ */
+function formatStaticCheckCheckerEntry(entry: StaticCheckEntry): string {
+  const cmd = typeof entry.cmd === "string" ? entry.cmd.trim() : "";
+  const params = Array.isArray(entry.params) ? entry.params.map(String) : [];
+  return [cmd, ...params].filter((value) => value !== "").join(" ");
+}
+
+/**
+ * @brief Summarizes every configured checker for one language as a delimited command list.
+ * @details Joins each checker entry summary with `; ` so the value column exposes the full language configuration in one row. Runtime is O(c * p). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] language {string} Canonical language name.
+ * @return {string} Delimited checker summary string, or `(none)` when no checkers are configured.
+ */
+function formatStaticCheckLanguageCheckerSummary(config: UseReqConfig, language: string): string {
+  const checkers = getStaticCheckLanguageConfigForMenu(config, language).checkers;
+  if (checkers.length === 0) {
+    return "(none)";
+  }
+  return checkers.map(formatStaticCheckCheckerEntry).join("; ");
+}
+
+/**
+ * @brief Builds the shared settings-menu choices for the read-only static-check inspection submenu.
+ * @details Exposes only configured languages as disabled rows whose value column renders the full checker command list, appends one selectable `Close` row, and emits a disabled placeholder when no language is configured so the submenu never mutates configuration. Runtime is O(l * c * p). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered read-only inspection choices.
+ * @satisfies REQ-346
+ */
+function buildStaticCheckViewChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+  const configured = getSupportedStaticCheckLanguageSupport()
+    .filter(({ language }) => getStaticCheckLanguageConfigForMenu(config, language).checkers.length > 0);
+  if (configured.length === 0) {
+    return [
+      {
+        id: "view-static-check-empty",
+        label: "No configured static checkers",
+        value: "(none)",
+        description: "Configure at least one Command static-check entry before inspecting configuration.",
+        disabled: true,
+        labelTone: "dim",
+        valueTone: "dim",
+      },
+      {
+        id: "view-static-check-close",
+        label: "Close",
+        value: "",
+        description: "Close the static-check inspection view and return to the previous menu.",
+      },
+    ];
+  }
+  return [
+    ...configured.map(({ language, extensions }) => {
+      const languageConfig = getStaticCheckLanguageConfigForMenu(config, language);
+      const summary = formatStaticCheckLanguageCheckerSummary(config, language);
+      const checkerCount = languageConfig.checkers.length;
+      const suffix = checkerCount === 1 ? "checker" : "checkers";
+      return {
+        id: `view-static-check-language:${language}`,
+        label: language,
+        value: summary,
+        description: `Read-only inspection of the configured Command static-check entries for ${language}. Supported extensions: ${extensions.join(", ")}. ${checkerCount} ${suffix}.`,
+        disabled: true,
+        labelTone: "dim" as const,
+        valueTone: "dim" as const,
+      };
+    }),
+    {
+      id: "view-static-check-close",
+      label: "Close",
+      value: "",
+      description: "Close the static-check inspection view and return to the previous menu.",
+    },
+  ];
+}
+
+/**
+ * @brief Builds the confirmation submenu choices for removing one configured static-check language.
+ * @details Renders each configured checker as a disabled preview row, appends explicit approve and abort actions, and falls back to one disabled no-op row when the language has no checkers. Runtime is O(c * p). No external state is mutated.
+ * @param[in] language {string} Canonical language name targeted for removal.
+ * @param[in] checkers {StaticCheckEntry[]} Configured checker entries that removal would clear.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered removal-confirmation choices.
+ * @satisfies REQ-349
+ */
+function buildStaticCheckRemovalConfirmationChoices(
+  language: string,
+  checkers: StaticCheckEntry[],
+): PiUsereqSettingsMenuChoice[] {
+  const previewRows = checkers.length > 0
+    ? checkers.map((entry, index) => ({
+      id: `removal-preview:${language}:${index}`,
+      label: formatStaticCheckCheckerEntry(entry),
+      value: `${language} checker`,
+      description: `Remove the configured Command static-check entry ${formatStaticCheckCheckerEntry(entry)} from ${language}.`,
+      disabled: true,
+      labelTone: "dim" as const,
+      valueTone: "dim" as const,
+    }))
+    : [{
+      id: `removal-preview:${language}:none`,
+      label: `No configured checkers for ${language}`,
+      value: "nothing to remove",
+      description: `No configured static-check entries exist for ${language}.`,
+      disabled: true,
+      labelTone: "dim" as const,
+      valueTone: "dim" as const,
+    }];
+  return [
+    ...previewRows,
+    {
+      id: "removal-approve",
+      label: "Approve removal",
+      value: `${checkers.length} ${checkers.length === 1 ? "checker" : "checkers"}`,
+      description: `Remove every configured static-check entry for ${language}.`,
+    },
+    {
+      id: "removal-abort",
+      label: "Abort removal",
+      value: "keep current",
+      description: `Keep the configured static-check entries for ${language}.`,
+    },
+  ];
+}
+
+/**
+ * @brief Opens one explicit removal-confirmation submenu for a configured static-check language.
+ * @details Renders the targeted checker entries before removal and returns `true` only when the user selects the explicit approval action. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] language {string} Canonical language name targeted for removal.
+ * @param[in] checkers {StaticCheckEntry[]} Configured checker entries that removal would clear.
+ * @return {Promise<boolean>} `true` when the removal is explicitly approved.
+ * @satisfies REQ-349
+ */
+async function confirmStaticCheckRemoval(
+  ctx: ExtensionCommandContext,
+  language: string,
+  checkers: StaticCheckEntry[],
+): Promise<boolean> {
+  const choice = await showPiUsereqSettingsMenu(
+    ctx,
+    `Remove static code checker: ${language}`,
+    buildStaticCheckRemovalConfirmationChoices(language, checkers),
+  );
+  return choice === "removal-approve";
+}
+
 /**
  * @brief Runs the interactive static-check configuration menu.
- * @details Lets the user add and remove global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user add, inspect, confirm-before-remove, and reset global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253
+ * @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253, REQ-345, REQ-346, REQ-347, REQ-348, REQ-349
  */
 async function configureStaticCheckMenu(
   ctx: ExtensionCommandContext,
@@ -3959,6 +4141,11 @@ async function configureStaticCheckMenu(
       continue;
     }
 
+    if (staticChoice === "view-static-check-entry") {
+      await showPiUsereqSettingsMenu(ctx, "View static code checker", buildStaticCheckViewChoices(config));
+      continue;
+    }
+
     if (staticChoice === "remove-static-check-entry") {
       const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "Remove static code checker", buildConfiguredStaticCheckLanguageChoices(config));
       if (!configuredLanguage) {
@@ -3985,12 +4172,40 @@ async function configureStaticCheckMenu(
         ctx.ui.notify("Restored default static code checker configuration", "info");
         continue;
       }
+      const targetedCheckers = getStaticCheckLanguageConfigForMenu(config, configuredLanguage).checkers;
+      const removalApproved = await confirmStaticCheckRemoval(ctx, configuredLanguage, targetedCheckers);
+      if (!removalApproved) {
+        ctx.ui.notify(`Aborted removal of static-check entries for ${configuredLanguage}`, "info");
+        continue;
+      }
       config["static-check"][configuredLanguage] = createStaticCheckLanguageConfig([]);
       onConfigChange();
       ctx.ui.notify(`Removed static-check entries for ${configuredLanguage}`, "info");
       continue;
     }
 
+    if (staticChoice === "reset-static-check-entry") {
+      const approved = await confirmResetChanges(
+        ctx,
+        "Confirm static-check reset",
+        [{
+          label: "Language static code checkers",
+          previousValue: formatStaticCheckLanguagesSummary(config),
+          nextValue: formatStaticCheckLanguagesSummary({ ...config, "static-check": getDefaultStaticCheckConfig() }),
+        }].filter((change) => change.previousValue !== change.nextValue),
+        "Approve restoring the documented per-language static-check defaults.",
+        "Abort the static-check reset and keep the current values.",
+      );
+      if (!approved) {
+        ctx.ui.notify("Aborted static-check reset", "info");
+        continue;
+      }
+      resetStaticCheckConfig(config);
+      onConfigChange();
+      ctx.ui.notify("Restored default static code checker configuration", "info");
+      continue;
+    }
+
     if (staticChoice === "reset-defaults") {
       const approved = await confirmResetChanges(
         ctx,