@opengsd/gsd-core 1.9.0 → 1.9.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.9.0",
+      "version": "1.9.1",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

package/agents/gsd-code-fixer.md

@@ -216,9 +216,36 @@ If a finding references multiple files (in Fix section or Issue section):
 
 This agent runs as a background process that makes commits. Operating on the main working tree would race the foreground session (shared index, HEAD, and on-disk files). Instead, every instance runs in its own isolated worktree.
 
+**#2825: honor `workflow.use_worktrees`.** This is the ONLY writer that hand-rolls a git worktree
+inside the agent prompt; every other writer path (`/gsd:execute-phase`, `/gsd:execute-plan`,
+`/gsd:quick`, `/gsd:diagnose-issues`) reads `workflow.use_worktrees` and skips isolation when it is
+`false`. Read the same flag here and, when it is `false`, edit and commit in the main checkout
+directly (set `wt="."`, no `reviewfix_branch`, no recovery sentinel, no `git worktree add`, and skip
+the cleanup tail — there is no worktree to remove). When the flag is not `false`, the transactional
+worktree path below runs unchanged. A user who explicitly opted out of worktrees must never have a
+worktree created; the hand-rolled worktree also cannot run the project's gates safely (no
+`node_modules`), so the opt-out is also the safe path.
+
 The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/gsd:resume-work`, or `/gsd:progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
 
 ```bash
+# #2825: honor workflow.use_worktrees — the documented opt-out. When false,
+# edit/commit in the main checkout (wt=".", no temp branch, no sentinel, no
+# cleanup tail). Read the flag the same way the four sibling writer workflows
+# do. NOTE: this read parses .planning/config.json directly via `node` rather
+# than the gsd-tools CLI, because setup_worktree runs BEFORE the canonical
+# launcher preamble is sourced — invoking the CLI here would be undefined at
+# runtime and violates the runtime-launcher-parity preamble-ordering rule.
+# Once the preamble is sourced (later steps), the CLI is available.
+USE_WORKTREES=$(node -e '
+  try {
+    const fs = require("fs");
+    const p = (process.env.GSD_PROJECT_DIR || process.cwd()) + "/.planning/config.json";
+    const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+    process.stdout.write(String((cfg.workflow && cfg.workflow.use_worktrees) ?? true));
+  } catch { process.stdout.write("true"); }
+')
+
 # Derive worktree path from padded_phase (parsed from config in next step,
 # but the shell snippet below is illustrative — adapt once config is parsed).
 # In practice: parse padded_phase from config first, then run:
@@ -264,34 +291,47 @@ if [ -f "$sentinel" ]; then
   rm -f "$sentinel"
 fi
 
-wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
-
-# Create a temp branch from the current branch tip so the worktree
-# attaches to that NEW branch rather than the user's currently-checked-out
-# branch (#2990: git refuses to check out the same branch in two
-# worktrees by default; the original `git worktree add "$wt" "$branch"`
-# failed before the agent could do any work). The temp branch shares
-# history with $branch up to the moment of creation, so commits made
-# inside the worktree fast-forward $branch on cleanup.
-reviewfix_branch="gsd-reviewfix/${padded_phase}-$$"
-git worktree add -b "$reviewfix_branch" "$wt" "$branch"
-
-# Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
-# Writing it before would leave a sentinel pointing at a worktree that does
-# not exist if `git worktree add` itself failed.
-node -e '
-  const fs = require("fs");
-  const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
-  fs.writeFileSync(sentinelPath, JSON.stringify({
-    worktree_path,
-    branch,
-    reviewfix_branch,
-    padded_phase,
-    started_at: new Date().toISOString()
-  }, null, 2));
-' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
-
-cd "$wt"
+# #2825: when the user opted out of worktrees, edit/commit in the main
+# checkout directly — no temp branch, no sentinel, no cleanup tail. This is
+# the safe path: the hand-rolled worktree has no node_modules, so it cannot
+# run the project's gates, and an improvised teardown can destroy the real
+# node_modules on Windows (a junction followed by rm -rf). wt="." means every
+# downstream read/edit/commit lands in the main working tree, and the cleanup
+# tail below is a no-op (nothing to fast-forward, no worktree to remove).
+if [ "$USE_WORKTREES" = "false" ]; then
+  wt="."
+  reviewfix_branch="$branch"
+  echo "workflow.use_worktrees=false — editing/committing in the main checkout (no worktree)."
+else
+  wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
+
+  # Create a temp branch from the current branch tip so the worktree
+  # attaches to that NEW branch rather than the user's currently-checked-out
+  # branch (#2990: git refuses to check out the same branch in two
+  # worktrees by default; the original `git worktree add "$wt" "$branch"`
+  # failed before the agent could do any work). The temp branch shares
+  # history with $branch up to the moment of creation, so commits made
+  # inside the worktree fast-forward $branch on cleanup.
+  reviewfix_branch="gsd-reviewfix/${padded_phase}-$$"
+  git worktree add -b "$reviewfix_branch" "$wt" "$branch"
+
+  # Write the recovery sentinel ONLY AFTER `git worktree add` succeeds.
+  # Writing it before would leave a sentinel pointing at a worktree that does
+  # not exist if `git worktree add` itself failed.
+  node -e '
+    const fs = require("fs");
+    const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1);
+    fs.writeFileSync(sentinelPath, JSON.stringify({
+      worktree_path,
+      branch,
+      reviewfix_branch,
+      padded_phase,
+      started_at: new Date().toISOString()
+    }, null, 2));
+  ' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"
+
+  cd "$wt"
+fi
 ```
 
 Concrete steps:
@@ -305,9 +345,18 @@ Concrete steps:
 
 **If `git worktree add` fails**, surface the error and exit — do not force-remove the path, as another concurrent run may be holding it. Do not write the sentinel (the worktree does not exist). Do not delete `$reviewfix_branch` either; if `-b` failed, no temp branch was created.
 
-**Cleanup tail (transactional, ALWAYS — even on failure):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order:
+**Cleanup tail (transactional, ALWAYS — even on failure — when a worktree was created):** After writing REVIEW-FIX.md and before returning to the orchestrator, run the cleanup in this exact order. (When `workflow.use_worktrees` is `false`, no worktree was created — the cleanup is a no-op and the bash below early-exits.)
 
 ```bash
+# #2825: when worktrees were disabled, there is nothing to clean up — the
+# agent edited/committed on $branch directly in the main checkout (wt=".",
+# reviewfix_branch==$branch, no sentinel, no temp worktree). Skip the whole
+# tail; the four steps below are all no-ops or harmful (e.g. `git worktree
+# remove "."` ) in that mode.
+if [ "$USE_WORKTREES" = "false" ]; then
+  exit 0
+fi
+
 # Step 1 (#2990): fast-forward $branch to capture the commits the agent
 # made on $reviewfix_branch. Run from the main repo (not $wt) — the user's
 # checkout owns $branch. --ff-only ensures we never silently drop or
@@ -354,7 +403,7 @@ fi
 rm -f "$sentinel"
 ```
 
-This cleanup is unconditional — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
+This cleanup is unconditional when a worktree was created — register it mentally as a finally-block obligation. If the agent exits early (config error, no findings, etc.), still run the cleanup tail in order (fast-forward → worktree remove → temp branch delete → sentinel rm) before exit. (When `workflow.use_worktrees` is `false`, no worktree exists and the bash above early-exits before these steps.) The sentinel must NEVER be removed before `git worktree remove` succeeds. The temp branch must NEVER be deleted while the fast-forward is in a diverged state.
 </step>
 
 <step name="load_context">
@@ -587,9 +636,33 @@ _Iteration: {N}_
 
 <critical_rules>
 
-**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail unconditionally when done (treat it as a finally block). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
-
-**ALWAYS run the transactional cleanup tail in order** (#2839, #2990): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/gsd:resume-work`, or `/gsd:progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail when done (treat it as a finally block) — but only when a worktree was actually created; when `workflow.use_worktrees` is `false` the cleanup early-exits (no worktree to remove). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+
+**#2825 — honor `workflow.use_worktrees`.** Before creating a worktree, read the
+`workflow.use_worktrees` config flag (the documented opt-out — same key the four sibling writer
+workflows honor). `setup_worktree` reads it via `node` directly from `.planning/config.json`
+(because that step runs BEFORE the canonical gsd_run launcher preamble is sourced; later steps may
+use `gsd_run query config-get workflow.use_worktrees`). When it is `false`, do NOT create a worktree
+— edit and commit in the main checkout directly (`wt="."`, no temp branch, no sentinel, no cleanup
+tail). A user who opted out of worktrees must
+never have one created. See the `setup_worktree` step for the gated bash.
+
+**NEVER `rm -rf` a possible reparse point** (#2825). On Windows, `node_modules` inside the worktree
+may be a junction/reparse point whose target is the REAL `node_modules` in the main checkout — and
+`rm -rf` follows the link and deletes the target's contents (silent, misdiagnosable data loss). Do
+NOT improvise a `node_modules` teardown. The worktree has no `node_modules` by design; if you need
+the project's gates, run them in the main checkout after the fast-forward, OR leave the worktree's
+dependency handling to `git worktree remove` (which does not recurse into a separately-managed
+link). Never use `rm -rf` (or `2>/dev/null || rm -rf || true`) as a fallback for removing a path
+that might be a reparse point — on failure, STOP and surface the error rather than falling through
+to a destructive remove.
+
+**Record where verification ran** (#2825). The REVIEW-FIX.md verification section must state whether
+the gates ran in the main checkout or the isolated worktree, so a reader can tell whether the numbers
+are reproducible from the tree they are looking at (a worktree-env run is not reproducible from the
+main checkout after teardown).
+
+**ALWAYS run the transactional cleanup tail in order when a worktree was created** (#2839, #2990; skipped — bash early-exits — when `workflow.use_worktrees` is `false`): the cleanup is four steps with strict ordering. (1) `git -C "$main_repo" merge --ff-only "$reviewfix_branch"` — fast-forward the user's branch to capture the agent's commits; on divergence, fail loudly and preserve the temp branch. (2) `git worktree remove "$wt" --force`. (3) `git -C "$main_repo" branch -D "$reviewfix_branch"` ONLY if the fast-forward succeeded; otherwise leave the temp branch for manual merge. (4) `rm -f "$sentinel"` (the recovery sentinel at `${phase_dir}/.review-fix-recovery-pending.json`). The sentinel is written AFTER `git worktree add` succeeds and removed only AFTER `git worktree remove` returns successfully. The temp branch is deleted only when the fast-forward succeeded. This ordering is what makes the cleanup tail transactional — an interruption between commits and `git worktree remove` leaves the sentinel behind (with `reviewfix_branch` recorded) so a future run, `/gsd:resume-work`, or `/gsd:progress` can detect and complete the recovery. Reversing the order recreates the orphan-worktree bug.
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 

package/bin/install.js

@@ -6983,6 +6983,47 @@ function writeCopilotHookConfig(targetDir) {
  * Generate config.toml and per-agent .toml files for Codex.
  * Reads agent .md files from source, extracts metadata, writes .toml configs.
  */
+
+/**
+ * #2834: Write ~/.gsd/defaults.json for non-Claude runtimes — sets
+ * resolve_model_ids="omit" (so resolveModelInternal() returns '' instead of
+ * Claude aliases the runtime can't resolve) and runtime=<runtime> (so
+ * resolveRuntime() resolves correctly out of the box). MUST be called BEFORE
+ * installCodexConfig (or any other step that reads defaults.json at generation
+ * time), so a clean first install produces correctly-model-routed agent TOMLs.
+ * No-op for Claude runtimes (Claude is the resolveRuntime fallback + has native
+ * model aliases). Preserves an explicit `true` opt-in and existing values.
+ */
+function writeNonClaudeDefaults(runtime) {
+  if (_hostBehaviors(runtime).nativeModelAliases || process.env.GSD_TEST_MODE) return;
+  const gsdDir = path.join(os.homedir(), '.gsd');
+  const defaultsPath = path.join(gsdDir, 'defaults.json');
+  try {
+    fs.mkdirSync(gsdDir, { recursive: true });
+    let defaults = {};
+    try { defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')); } catch { /* new file */ }
+    if (defaults === null || typeof defaults !== 'object' || Array.isArray(defaults)) {
+      defaults = {};
+    }
+    // Three-valued domain: false/absent → aliases; true → full IDs; "omit" → ''.
+    const existing = defaults.resolve_model_ids;
+    const shouldDefaultToOmit = existing !== true && existing !== 'omit';
+    if (shouldDefaultToOmit) {
+      defaults.resolve_model_ids = 'omit';
+      fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
+      console.log(`  ${green}✓${reset} Set resolve_model_ids: "omit" in ~/.gsd/defaults.json`);
+    }
+    // #2395: persist runtime for non-Claude runtimes.
+    if (defaults.runtime === undefined || defaults.runtime === null || defaults.runtime === '') {
+      defaults.runtime = runtime;
+      fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
+      console.log(`  ${green}✓${reset} Set runtime: "${runtime}" in ~/.gsd/defaults.json`);
+    }
+  } catch (e) {
+    console.log(`  ${yellow}⚠${reset} Could not write ~/.gsd/defaults.json: ${e.message}`);
+  }
+}
+
 function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-sandbox') {
   // ADR-1239 Phase B write-confinement: every Codex config write stays under targetDir.
   const configPath = assertDestWithinConfigHome(targetDir, 'config.toml');
@@ -11586,6 +11627,10 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
 
     let agentCount = 0;
     if (!isMinimalMode(_effectiveInstallMode)) {
+      // #2834: write ~/.gsd/defaults.json (resolve_model_ids + runtime) BEFORE generating
+      // agent TOMLs — installCodexConfig reads defaults.json at generation time, so on a
+      // clean first install the runtime-aware model resolver must already know the runtime.
+      writeNonClaudeDefaults(runtime);
       try {
         // Generate Codex config.toml and per-agent .toml files.
         agentCount = installCodexConfig(targetDir, agentsSrc, plan.sandboxTier);
@@ -12361,58 +12406,11 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
     configureAntigravityMcpConfig(isGlobal, configDir);
   }
 
-  // For non-Claude runtimes, DEFAULT resolve_model_ids to "omit" in ~/.gsd/defaults.json
-  // when it is absent or falsy, so resolveModelInternal() returns '' instead of Claude
-  // aliases (opus/sonnet/haiku) the runtime can't resolve. An explicit `true` opt-in
-  // (resolveModelInternal returns full materialized model IDs) MUST be preserved —
-  // rewriting it to "omit" would make generated agent manifests inherit the active
-  // chat model instead of pinning the resolved model. See #1156 (default-to-omit
-  // intent) and #1569 (preserve explicit true). Guard matches the #130-class pattern
-  // on configureOpencodePermissions above.
-  if (!_hostBehaviors(runtime).nativeModelAliases && !process.env.GSD_TEST_MODE) {
-    const gsdDir = path.join(os.homedir(), '.gsd');
-    const defaultsPath = path.join(gsdDir, 'defaults.json');
-    try {
-      fs.mkdirSync(gsdDir, { recursive: true });
-      let defaults = {};
-      try { defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')); } catch { /* new file */ }
-      // Recover a malformed (valid-JSON-but-non-object) defaults.json to a fresh object so
-      // the write below succeeds and the file is no longer broken. Without this, `null` /
-      // `[]` / a number / a string bypass the parse catch and either throw a TypeError on
-      // property access (swallowed by the outer try/catch, leaving the file broken) or get
-      // a property set that won't round-trip through JSON.stringify. (#1657)
-      if (defaults === null || typeof defaults !== 'object' || Array.isArray(defaults)) {
-        defaults = {};
-      }
-      // Three-valued domain: false/absent → aliases; true → full IDs; "omit" → ''.
-      // Honor ONLY an explicit canonical `true` opt-in (full model IDs) and an existing
-      // "omit"; default everything else — absent, falsy, OR any non-canonical value — to
-      // "omit", the safe non-Claude default. Allowlist-based so malformed values
-      // (0, "", "yes", {}, …) don't leak Claude aliases the runtime can't resolve (#1569).
-      const existing = defaults.resolve_model_ids;
-      const shouldDefaultToOmit = existing !== true && existing !== 'omit';
-      if (shouldDefaultToOmit) {
-        defaults.resolve_model_ids = 'omit';
-        fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
-        console.log(`  ${green}✓${reset} Set resolve_model_ids: "omit" in ~/.gsd/defaults.json`);
-      }
-
-      // #2395: also persist `runtime: <runtime>` for non-Claude runtimes, so
-      // resolveRuntime() (precedence: GSD_RUNTIME env > config.runtime > 'claude')
-      // resolves to the install's actual runtime identity out of the box — without
-      // this, agent_runtime and every runtime-branded slash hint falls through to
-      // the hard-coded 'claude' default. Mirrors the resolve_model_ids write above:
-      // honor an explicit pre-existing value (any string), only default-populating
-      // when absent. Claude is the resolveRuntime() fallback, so it needs no write.
-      if (defaults.runtime === undefined || defaults.runtime === null || defaults.runtime === '') {
-        defaults.runtime = runtime;
-        fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
-        console.log(`  ${green}✓${reset} Set runtime: "${runtime}" in ~/.gsd/defaults.json`);
-      }
-    } catch (e) {
-      console.log(`  ${yellow}⚠${reset} Could not write ~/.gsd/defaults.json: ${e.message}`);
-    }
-  }
+  // #2834: defaults.json (resolve_model_ids + runtime) is now written BEFORE
+  // installCodexConfig via writeNonClaudeDefaults(runtime) — extracted into a
+  // function so it can run at the right point in the flow (before agent TOML
+  // generation reads it). This call is idempotent (preserves existing values).
+  writeNonClaudeDefaults(runtime);
 
   // program + command are now single-source lookups (ADR-1239 Phase B / #1679):
   // program is the runtime display label; command is the per-host /gsd-new-project

package/gsd-core/bin/gsd-tools.cjs

@@ -3033,6 +3033,29 @@ function runWithTimeout(argv) {
   const detached = !isWin && secs > 0;
   const spawnFailureCode = (err) =>
     (err && err.code === 'ENOENT' ? 127 : err && err.code === 'EACCES' ? 126 : 125);
+  // #2667: on Windows, a `.cmd`/`.bat`/`.exe` command cannot be spawned directly
+  // — Node's CVE-2024-27980 hardening (April 2024, all active lines incl. 22.x)
+  // throws EINVAL when child_process.spawn is given a `.cmd`/`.bat` without a
+  // shell, so e.g. `run-with-timeout 120 -- node_modules/.bin/fallow.cmd` silently
+  // produced empty stdout + exit 125 and the fallow pre-pass no-op'd.
+  //
+  // We do NOT use `shell: true` for this: with `shell:true`, Node space-joins the
+  // unescaped cmdArgs into a cmd.exe command string (DEP0190) — that would re-open
+  // a shell-injection surface and violate the recorded no-shell-for-argv-array
+  // contract (DEFECT.UNBOUNDED-SUBPROCESS, CONTEXT.md:772). Instead we spawn
+  // `cmd.exe /c <cmd> <args>` with an explicit argv ARRAY, which is what Node's
+  // own exec does internally and keeps every arg a discrete, un-interpolated
+  // token. The gate is NARROW: it fires ONLY for the Windows shim extensions,
+  // never for the `bash -c` callers (command is `bash`, no such suffix), so the 7
+  // bash callers keep their array-only argv on every platform. POSIX untouched.
+  // NOTE: .exe is INTENTIONALLY excluded — real PE executables (node.exe, etc.)
+  // spawn fine directly and mediating them through cmd.exe /c breaks the timeout
+  // cap's process-group kill (the wrapped child escapes reap → exit 124 never
+  // fires) and risks cmd.exe mis-parsing an arg like `-e "setTimeout(()=>{})"`.
+  // Only .cmd/.bat are the CVE-2024-27980 EINVAL cases that require mediation.
+  const winShim = isWin && /\.(cmd|bat)$/i.test(path.basename(cmd));
+  const spawnCmd = winShim ? (process.env.ComSpec || 'cmd.exe') : cmd;
+  const spawnArgs = winShim ? ['/d', '/s', '/c', cmd, ...cmdArgs] : cmdArgs;
   // Node's setTimeout delay is a 32-bit signed ms int; a larger value silently
   // clamps to 1ms → a spurious immediate timeout. Cap the budget (~24.8 days).
   const timerMs = Math.min(Math.round(secs * 1000), 2 ** 31 - 1);
@@ -3043,7 +3066,11 @@ function runWithTimeout(argv) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(cmd, cmdArgs, { stdio: 'inherit', detached });
+      // #2667: on win32 `.cmd`/`.bat`/`.exe`, spawn cmd.exe with an explicit argv
+      // array (spawnCmd/spawnArgs) rather than the shim directly — preserves the
+      // array-only, no-shell-string argv contract. `detached` is always false on
+      // win32, so it never co-occurs with the cmd.exe mediation.
+      child = spawn(spawnCmd, spawnArgs, { stdio: 'inherit', detached });
     } catch (err) {
       process.stderr.write(`run-with-timeout: ${cmd}: ${err && err.message ? err.message : 'failed to start'}\n`);
       resolve(spawnFailureCode(err));
@@ -3309,7 +3336,11 @@ async function main() {
   // move the other at the same time (keep them consistent).
   const SKIP_ROOT_RESOLUTION = new Set([
     'generate-slug', 'current-timestamp', 'verify-path-exists',
-    'verify-summary', 'template', 'frontmatter', 'detect-custom-files',
+    // #2844: verify-summary was previously skipped, leaving relative file-claim
+    // paths resolved against the raw process.cwd() — invoking from a subdirectory
+    // manufactured "missing files" on an otherwise-correct SUMMARY. It now goes
+    // through findProjectRoot so claims resolve against the project root.
+    'template', 'frontmatter', 'detect-custom-files',
     // #1854: restore-custom-files operates on a runtime config dir passed
     // explicitly via --config-dir; it never reads .planning/.
     'restore-custom-files',