@opengsd/gsd-core 1.18.0 → 1.19.0

package/gsd-core/workflows/spec-phase.md

@@ -61,7 +61,7 @@ INIT=$(gsd_run init phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `state_path`, `requirements_path`, `roadmap_path`, `planning_path`, `response_language`, `commit_docs`.
+Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `state_path`, `requirements_path`, `roadmap_path`, `planning_path`, `has_spec`, `spec_path`, `response_language`, `commit_docs`.
 
 **If `response_language` is set:** All user-facing text in this workflow — narration between tool calls, status updates, progress notes, findings, questions, and report prose — MUST be in `{response_language}`. Technical terms, code, and file paths stay in English.
 
@@ -72,12 +72,9 @@ Use /gsd:progress to see available phases.
 ```
 Exit.
 
-**Check for existing SPEC.md:**
-```bash
-ls ${phase_dir}/*-SPEC.md 2>/dev/null | grep -v AI-SPEC | head -1 || true
-```
+**Check for existing SPEC.md:** use `has_spec` and `spec_path` from init (one shared definition of the phase SPEC: a plain `*-SPEC.md`, never `*-AI-SPEC.md` or `*-UI-SPEC.md`). Do not glob for it.
 
-If SPEC.md already exists:
+If `has_spec` is true:
 
 **If `--auto`:** Auto-select "Skip" — leave the existing SPEC.md unchanged and exit with the same
 message the interactive "Skip" prints. Log: `[auto] SPEC.md exists — reusing as-is.` An unattended

package/gsd-core/workflows/verify-work.md

@@ -75,6 +75,7 @@ registry, not hardcoded here.
 ```bash
 VERIFY_PRE_HOOKS_JSON=$(gsd_run loop render-hooks verify:pre --raw)
 PHASE_DIR=$(printf '%s' "$INIT" | jq -r '.phase_dir // empty')
+PHASE_NUMBER=$(printf '%s' "$INIT" | jq -r '.phase_number // empty')
 ```
 
 Read the `activeHooks` array from `VERIFY_PRE_HOOKS_JSON` in-context (do NOT pipe through a shell parser).
@@ -87,12 +88,12 @@ Read the `activeHooks` array from `VERIFY_PRE_HOOKS_JSON` in-context (do NOT pip
 
 Record the union of `produces` artefact names declared by the active step entries as `VERIFY_PRE_PRODUCED` — `extract_tests` consumes it below. An entry declaring `produces: []` contributes nothing, which is the normal case.
 
-⚠ **Validate `check` before shell use** (third-party manifest input) — `loop-hook-dispatch.md` § `gate`.
+⚠ **Validate `check` before shell use** (third-party manifest input; wherever `${hook.check.query}` appears, write the dot-normalized query, each `.` as `-`, and validate and pass that same value) — `loop-hook-dispatch.md` § `gate`.
 
 Resolve active gate hooks from `VERIFY_PRE_HOOKS_JSON` where `kind == "gate"`.
 For each active gate hook, run its declared check (a `check.query` gate runs
 `gsd_run check ${hook.check.query} "${PHASE_DIR}" --raw`; a `predicate` gate
-runs `gsd_run check predicate --predicate '<hook.check.predicate as JSON>' --phase-dir "${PHASE_DIR}" --raw`):
+runs `gsd_run check predicate --predicate '<hook.check.predicate as JSON>' --phase-dir "${PHASE_DIR}" --phase-number "${PHASE_NUMBER}" --raw`):
 
 ```bash
 GATE_RESULT=$(gsd_run check "${hook_check_query}" "${PHASE_DIR}" --raw) && CHECK_EXIT=0 || CHECK_EXIT=$?
@@ -799,7 +800,7 @@ Spawn gsd-plan-checker against the fix plans (iteration_count starts at 1), mode
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
 On return:
-- **VERIFICATION PASSED:** Proceed to `present_ready`
+- **VERIFICATION PASSED:** If the return lists an entry whose severity is BLOCKER or WARNING, in the YAML issues block or listed in prose (a mention such as "no warnings" or a zero count is not an entry), handle it as ISSUES FOUND below, counting the prose entries as BLOCKER/WARNING entries; the sentinel never decides alone, and an entry with a missing or unrecognized severity counts as a BLOCKER (#5578). Otherwise proceed to `present_ready`
 - **ISSUES FOUND:** Count BLOCKER + WARNING entries in the YAML issues block; an entry whose severity is missing or unrecognized counts as a BLOCKER (fail closed). If zero — every entry is explicitly INFO — display `ℹ advisory — {dimension}: {description}` per entry and proceed to `present_ready`; INFO is advisory and never enters the loop (#3724). Otherwise proceed to `revision_loop`
 
 Exact Agent() prompt fields: `gsd-core/workflows/verify-work/detail/elaboration.md` § 2.

package/hooks/dist/gsd-agent-isolation-guard.js

@@ -71,7 +71,7 @@ if (require.main === module && !process.env.NODE_V8_COVERAGE) {
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, agedNoneGovernsDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
 
@@ -465,6 +465,16 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
     };
   }
 
+  // #5479: a recorded sequential degrade (`none`) for THIS dispatch's phase keeps governing it after the
+  // trust window. Without this, an executor that ran longer than SENTINEL_STALE_MS made the next
+  // flag-less dispatch of the same phase fall back to the registry capability ("this host CAN
+  // isolate") and be denied for a degrade the workflow legitimately recorded. The predicate only
+  // loosens toward `none`, only for the phase the dispatch itself names, never for a future-dated
+  // record (see agedNoneGovernsDispatch).
+  if (sentinel.present && sentinel.stale && agedNoneGovernsDispatch(sentinel, dispatchIds, { clock })) {
+    return { gsdProject: true, isolation: 'none', harnessFlag: null, error: null, sentinelDiscarded: null };
+  }
+
   // Sentinel absent, stale, or does not apply to this dispatch (F2 mismatch):
   // conservative fallback (#3045 finding — must still cover fail-closed case
   // (a): a project that opted out of worktrees entirely via

package/hooks/dist/gsd-cursor-subagent-start.js

@@ -70,7 +70,7 @@ const { allow } = require('./lib/hook-exit.js');
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
 // writeCursorHooksJson so the require always resolves post-install.
 const { resolveStatePath } = require('./lib/cursor-workspace.js');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, agedNoneGovernsDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 // #3582: gsd-core/bin/lib/*.cjs (runtime-homes.cjs, worktree-safety.cjs,
 // runtime-name-policy.cjs, capability-registry.cjs — required below, inside
@@ -518,9 +518,13 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
 
   let declaredIsolation;
   try {
+    // #5479: an aged recorded `none` for this dispatch's phase keeps governing it — the same predicate,
+    // and so the same verdicts, as the Claude guard (hooks/gsd-agent-isolation-guard.js).
     declaredIsolation = (sentinel.present && !sentinel.stale && applies)
       ? sentinel.isolation
-      : resolveFallbackIsolation(root, configPath);
+      : (sentinel.present && sentinel.stale && agedNoneGovernsDispatch(sentinel, dispatchIds, { clock }))
+        ? 'none'
+        : resolveFallbackIsolation(root, configPath);
   } catch {
     return {
       action: 'deny',

package/hooks/dist/gsd-path-export.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// SessionStart hook: put the installed gsd-core `bin/` directory (which holds `gsd_run`) on the
+// PATH of every later Bash tool call in this Claude Code session (#5465).
+//
+// Why a hook: the resolver snippet (gsd-core/workflows/_runtime-launcher.snippet.sh) persists its
+// PATH export through $CLAUDE_ENV_FILE, but Claude Code provides that variable only to SessionStart,
+// Setup, CwdChanged and FileChanged hooks, never to a workflow Bash block. So the write never fired
+// and a later block that called `gsd_run` without re-including the resolver got "command not found"
+// (hidden by `2>/dev/null || echo <fallback>`). This hook writes the same line from the one place
+// the variable exists. The snippet's in-block write stays for users who export the variable
+// themselves.
+//
+// Fail-open and side-effect-minimal by design: it only ever appends one line to the file Claude Code
+// hands to SessionStart hooks, only for a directory that contains an installed `gsd_run`, and any
+// problem (no variable, no gsd_run, unwritable file) exits 0 without output.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { allow } = require('./lib/hook-exit.js');
+
+/**
+ * The `bin/` directory next to this hook's install root: hooks live in `<root>/hooks/` and the
+ * runtime in `<root>/gsd-core/` for global, project-local and plugin layouts alike. Returns the
+ * real path, or null when `gsd_run` is not there.
+ */
+function resolveBinDir(hookDir) {
+  try {
+    const bin = fs.realpathSync(path.join(hookDir, '..', 'gsd-core', 'bin'));
+    return fs.statSync(path.join(bin, 'gsd_run')).isFile() ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The directory as the bash that sources $CLAUDE_ENV_FILE spells it. On Windows the env file is
+ * sourced by Git Bash, where `:` separates PATH entries and a drive letter is `/c/...`, which is
+ * also what the resolver snippet writes (it derives the directory from bash's `$GSD_TOOLS`). A
+ * native `C:\Users\x\...` would split at the colon and never resolve.
+ */
+function shellPath(dir, platform = process.platform) {
+  if (platform !== 'win32') return dir;
+  const m = /^([A-Za-z]):[\\/](.*)$/.exec(dir);
+  const rest = (m ? m[2] : dir.replace(/^[\\/]+/, '')).replace(/\\/g, '/');
+  return m ? `/${m[1].toLowerCase()}/${rest}` : dir.replace(/\\/g, '/');
+}
+
+/** The exact line the resolver snippet writes: `export PATH='<dir>':"$PATH"` with `'` escaped. */
+function exportLine(binDir, platform = process.platform) {
+  return `export PATH='${shellPath(binDir, platform).replace(/'/g, "'\\''")}':"$PATH"`;
+}
+
+/**
+ * Append the export to `envFile` unless it is already there. Returns true when it wrote.
+ * Never throws.
+ */
+function persistPath(envFile, binDir) {
+  try {
+    const line = exportLine(binDir);
+    let existing = '';
+    try {
+      existing = fs.readFileSync(envFile, 'utf8');
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') return false;
+    }
+    if (existing.split(/\r?\n/).includes(line)) return false;
+    const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    fs.appendFileSync(envFile, `${prefix}${line}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  const envFile = process.env.CLAUDE_ENV_FILE;
+  if (typeof envFile !== 'string' || envFile.trim() === '') return;
+  const binDir = resolveBinDir(__dirname);
+  if (binDir === null) return;
+  persistPath(envFile, binDir);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch {
+    // A PATH convenience must never fail session start.
+  }
+  allow();
+}
+
+module.exports = { resolveBinDir, shellPath, exportLine, persistPath };

package/hooks/dist/gsd-secret-read-guard.js

@@ -56,7 +56,9 @@
 //   EOF)"` — is never operand-checked, so prose mentioning `.env` is safe.
 //   pass 2 groups tokens by segment and evaluates each on its own:
 //   input redirect targets (`<`, `N<`) are always checked; the command word is
-//   located past `sudo`/`env VAR=x`/`nohup`-style prefixes; a closed set of
+//   located past wrapper prefixes AND their own options (`sudo -u U`,
+//   `env -i VAR=x`, `timeout -s KILL 5`, `nice -n 5`, `stdbuf -oL`, `exec`;
+//   see WRAPPERS, #5627); a closed set of
 //   NON-READING commands (test/[/ls/stat/rm/touch/echo/…) exempts that
 //   segment's operands — `[ -f .env ]` and `ls .env*` are existence checks
 //   GSD's own agents run — while `cp`/`mv`/`ln`/`git` are deliberately NOT
@@ -90,7 +92,9 @@
 //   (`cat .e*`), interpreter one-liners (`python -c "open('.env')"`), a piped
 //   script from a non-echo source (`cat gen.sh | bash`, `curl … | sh`), reads
 //   inside scripts the agent executes, and `glob: '*'` reaching a
-//   NON-gitignored `.env`. The promise is "no looser than the retired rules
+//   NON-gitignored `.env`, and a wrapper (or wrapper option taking a
+//   separate value) the WRAPPERS table does not list, or `env -S 'script'` (the split string is skipped as
+//   the option's value). The promise is "no looser than the retired rules
 //   on plain commands, without arming the compound-`cd` prompt". Writes to
 //   secret files are out of scope (Write/Edit were never gated). Commands
 //   over 1 MiB are denied outright (`command-too-large`) rather than
@@ -148,8 +152,29 @@ const MAX_GLOB_ALTERNATIVES = 64;
 const NON_SECRET_ENV_SUFFIXES = new Set(['example', 'sample', 'template', 'dist']);
 
 // Command-prefix wrappers to look through when locating the command word at
-// the head of a segment (same set as hooks/gsd-windsurf-pre-command.js).
-const CMD_PREFIXES = new Set(['sudo', 'env', 'command', 'nice', 'nohup', 'time', 'doas']);
+// the head of a segment (#5627). Each wrapper runs the words that follow its
+// own options, so the table records what resolveCommand must step over:
+//   short    letters of short options that take a value (`-n 5`, `-n5`)
+//   long     long options that take a SEPARATE value word (`--adjustment 5`);
+//            `--opt=value` is one word and needs no entry
+//   assigns  leading `VAR=value` words belong to the wrapper (env)
+//   operands positional words after the options (timeout's DURATION)
+// Taken from sudo(8), doas(1), env(1), nice(1), time(1), timeout(1),
+// stdbuf(1), setsid(1) and bash's `command`/`exec`. A wrong entry fails open
+// (the option's value becomes the command word), so keep it to the man pages.
+const WRAPPERS = new Map([
+  ['sudo', { short: 'CDghpRrTtUu', long: ['--close-from', '--chdir', '--group', '--host', '--prompt', '--chroot', '--role', '--command-timeout', '--type', '--other-user', '--user'] }],
+  ['doas', { short: 'Cu' }],
+  ['env', { short: 'uCSaP', long: ['--unset', '--chdir', '--split-string', '--argv0'], assigns: true }],
+  ['nice', { short: 'n', long: ['--adjustment'] }],
+  ['nohup', {}],
+  ['command', {}],
+  ['time', { short: 'fo', long: ['--format', '--output'] }],
+  ['timeout', { short: 'sk', long: ['--signal', '--kill-after'], operands: 1 }],
+  ['stdbuf', { short: 'ioe', long: ['--input', '--output', '--error'] }],
+  ['setsid', {}],
+  ['exec', { short: 'a' }],
+]);
 
 // Commands whose ordinary operands are file NAMES, never file CONTENTS. A
 // closed set on purpose: anything not listed is assumed to read.
@@ -405,6 +430,20 @@ function classifyGrepGlob(glob) {
 // Bash command scan — pass 1: tokenizer
 // ---------------------------------------------------------------------------
 
+// Which reading of a heredoc the scan is making (#5513). The guard scans a command that
+// opens a heredoc under every reading below and denies if any of them finds a secret read
+// (see findSecretReadUnderOtherReadings), so a change of reading can add a denial but
+// never remove one.
+//  - heredocBodiesSkippedInSpans: bash 5 skips the bodies of heredocs opened inside a
+//    `$( )` span when it looks for the closing `)`; bash 3.2.57 (still `/bin/bash` on
+//    macOS) does not, so a `)` on a body line closes the substitution and the rest of
+//    that line runs as the OUTER command.
+//  - heredocTagsAsWords: an unquoted tag is a bash word (a CR and a substitution belong
+//    to it). false is the earlier reading, where the tag stopped at any whitespace and at
+//    `(`: kept as a reading so nothing the guard denied before is allowed now.
+let heredocBodiesSkippedInSpans = true;
+let heredocTagsAsWords = true;
+
 // Index of the `)` closing a `$(` / `<(` / `>(` opened just before `i`, or
 // str.length when unterminated. Quote- and heredoc-aware so a `)` inside a
 // quoted string or a heredoc body never closes the span early.
@@ -439,7 +478,7 @@ function findParenClose(str, i) {
       i = j === -1 ? str.length : j + 1;
       continue;
     }
-    if (ch === '<' && str[i + 1] === '<' && str[i + 2] !== '<') {
+    if (heredocBodiesSkippedInSpans && ch === '<' && str[i + 1] === '<' && str[i + 2] !== '<') {
       const tag = readHeredocTag(str, i + 2);
       heredocTags.push(tag);
       i = tag.end;
@@ -475,7 +514,34 @@ function readHeredocTag(str, i) {
     i = j === -1 ? str.length : j + 1;
   } else {
     if (str[i] === '\\') { quoted = true; i++; }
-    while (i < str.length && !/[\s;&|<>()]/.test(str[i])) tag += str[i++];
+    // #5513: an unquoted tag is a bash WORD. It ends only at a metacharacter (space, tab,
+    // newline, `;&|<>()`): a carriage return is not one, so `EOF` + CR is the tag and the
+    // CRLF terminator line matches it; and a substitution inside the word belongs to it,
+    // taken literally (`E$(x)F` waits for the line `E$(x)F`).
+    while (i < str.length && !(heredocTagsAsWords ? /[ \t\n;&|<>()]/ : /[\s;&|<>()]/).test(str[i])) {
+      if (!heredocTagsAsWords) { tag += str[i++]; continue; }
+      if (str[i] === '$' && str[i + 1] === '(') {
+        const e = findParenClose(str, i + 2);
+        tag += str.slice(i, e + 1);
+        i = e + 1;
+        continue;
+      }
+      if (str[i] === '$' && str[i + 1] === '{') {
+        const j = str.indexOf('}', i);
+        const e = j === -1 ? str.length - 1 : j;
+        tag += str.slice(i, e + 1);
+        i = e + 1;
+        continue;
+      }
+      if (str[i] === '`') {
+        const j = str.indexOf('`', i + 1);
+        const e = j === -1 ? str.length - 1 : j;
+        tag += str.slice(i, e + 1);
+        i = e + 1;
+        continue;
+      }
+      tag += str[i++];
+    }
   }
   return { tag, quoted, stripTabs, end: i };
 }
@@ -621,6 +687,7 @@ function tokenize(str) {
       hasWord = true;
       const e = findParenClose(str, i + 2);
       nested.push(str.slice(i + 2, e));
+      if (expectTag && heredocTagsAsWords) buf += str.slice(i, e + 1); // #5513: the tag is taken literally
       i = e + 1;
       continue;
     }
@@ -639,6 +706,7 @@ function tokenize(str) {
       const j = str.indexOf('`', i + 1);
       const e = j === -1 ? str.length : j;
       nested.push(str.slice(i + 1, e));
+      if (expectTag && heredocTagsAsWords) buf += str.slice(i, e + 1); // #5513: the tag is taken literally
       i = e + 1;
       continue;
     }
@@ -673,6 +741,14 @@ function tokenize(str) {
       continue;
     }
 
+    // #5513: a CR is not a bash metacharacter, so inside a heredoc tag it is part of the word
+    // (a CRLF command's terminator line is `EOF` + CR).
+    if (ch === '\r' && expectTag && hasWord && heredocTagsAsWords) {
+      buf += ch;
+      i++;
+      continue;
+    }
+
     if (ch === ' ' || ch === '\t' || ch === '\r') {
       flush();
       i++;
@@ -769,17 +845,33 @@ function tokenize(str) {
 // Bash command scan — pass 2: per-segment evaluation
 // ---------------------------------------------------------------------------
 
-// `@file` (curl -d), `--flag=value`, `-Xvalue` → the operand that names the file.
-function normalizeOperand(text) {
+// Option characters of a bundled short cluster (`-2nif`).
+const CLUSTER_FLAG_CHAR_RE = /[A-Za-z0-9]/;
+
+// True when an operand word names a secret file. `@file` (curl -d) and
+// `--flag=value` are stripped to the value. In a single-dash word
+// (`/^-[^-]./`, so `-2if.env` counts too) the value of a bundled cluster
+// starts right after its run of option characters (#5046): `-if.env` holds
+// `.env`, `-nf=.env` holds `.env` after the `=`. That value is checked as
+// well as the historical two-character strip, so the verdict is never looser
+// than base and costs a fixed number of `namesSecret` calls (at most three,
+// whatever the word's length). The option run also swallows a value's leading
+// letters and digits, so `-fapp.env` is denied although `cat app.env` is not:
+// a fail-safe false positive, pinned in tests.
+function operandNamesSecret(text) {
   let v = text;
   if (v.startsWith('@')) v = v.slice(1);
   if (v.startsWith('--')) {
     const eq = v.indexOf('=');
     if (eq !== -1) v = v.slice(eq + 1);
-  } else if (/^-[A-Za-z]./.test(v)) {
-    v = v.slice(2);
+    return namesSecret(v);
   }
-  return v;
+  if (!/^-[^-]./.test(v)) return namesSecret(v);
+  if (namesSecret(v.slice(2))) return true;
+  let end = 1;
+  while (end < v.length && CLUSTER_FLAG_CHAR_RE.test(v[end])) end++;
+  if (end > 2 && namesSecret(v.slice(end))) return true;
+  return v[end] === '=' && namesSecret(v.slice(end + 1));
 }
 
 const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
@@ -789,18 +881,55 @@ const DASH_C_RE = /^-[A-Za-z]*c$/;
 
 const GROUPING_SEPS = new Set(['(', ')', '{', '}']);
 
+// How many words the option `word` occupies for wrapper `spec`: 2 when it
+// takes a separate value word, else 1.
+function wrapperOptionWidth(word, spec) {
+  if (word.startsWith('--')) {
+    if (word.includes('=')) return 1;
+    // getopt_long accepts any unambiguous prefix (`--adj 5`).
+    return word.length > 2 && (spec.long || []).some((l) => l.startsWith(word)) ? 2 : 1;
+  }
+  const valued = spec.short || '';
+  for (let i = 1; i < word.length; i++) {
+    if (valued.includes(word[i])) return i === word.length - 1 ? 2 : 1; // `-n5` carries its value
+  }
+  return 1;
+}
+
+// Index of the first word after a wrapper's own options, assignments and
+// positional operands (`-n 5`, `-i A=1`, `-s KILL 5`, `--`).
+function skipWrapperArgs(words, start, spec) {
+  let idx = start;
+  let optionsEnded = false;
+  while (idx < words.length) {
+    const text = words[idx].text;
+    if (spec.assigns && ASSIGNMENT_RE.test(text)) {
+      idx++;
+    } else if (!optionsEnded && text === '--') {
+      optionsEnded = true;
+      idx++;
+    } else if (!optionsEnded && text.length > 1 && text.startsWith('-')) {
+      idx += wrapperOptionWidth(text, spec);
+    } else {
+      break;
+    }
+  }
+  if (!spec.operands) return idx;
+  idx = Math.min(idx + spec.operands, words.length);
+  // `timeout 5 -- cmd`: some getopt builds still accept `--` after DURATION.
+  return idx < words.length && words[idx].text === '--' ? idx + 1 : idx;
+}
+
 // Command base + operands after leading `VAR=val` assignments and prefix
-// wrappers (`sudo`, `env VAR=x`, …), or null when nothing but prefixes remain.
+// wrappers with their own options (`sudo -u root`, `env -i VAR=x`,
+// `timeout -s KILL 5`, `nice -n 5`, …), or null when nothing but prefixes remain.
 function resolveCommand(words) {
   let idx = 0;
   while (idx < words.length && ASSIGNMENT_RE.test(words[idx].text)) idx++;
   while (idx < words.length) {
-    const base = lastSegment(words[idx].text).toLowerCase();
-    if (!CMD_PREFIXES.has(base)) break;
-    idx++;
-    if (base === 'env') {
-      while (idx < words.length && ASSIGNMENT_RE.test(words[idx].text)) idx++;
-    }
+    const spec = WRAPPERS.get(lastSegment(words[idx].text).toLowerCase());
+    if (!spec) break;
+    idx = skipWrapperArgs(words, idx + 1, spec);
   }
   if (idx >= words.length) return null;
   return { base: lastSegment(words[idx].text).toLowerCase(), operands: words.slice(idx + 1) };
@@ -962,6 +1091,26 @@ function precedingOp(s, bySeg, sepAfter) {
   return { op, prevSeg: p };
 }
 
+// #5513: the same scan under the other readings of a heredoc: bash 3.2.57's `$( )` span
+// (bodies not skipped) and the earlier tag reading (tag ends at any whitespace). Only a
+// command that opens a heredoc can read differently, so the extra passes are skipped for
+// every other command.
+function findSecretReadUnderOtherReadings(command) {
+  if (!command.includes('<<')) return null;
+  for (const [bodiesSkipped, tagsAsWords] of [[false, true], [true, false]]) {
+    heredocBodiesSkippedInSpans = bodiesSkipped;
+    heredocTagsAsWords = tagsAsWords;
+    try {
+      const hit = findSecretRead(command, 0);
+      if (hit) return hit;
+    } finally {
+      heredocBodiesSkippedInSpans = true;
+      heredocTagsAsWords = true;
+    }
+  }
+  return null;
+}
+
 // Returns the offending token text, or null.
 function findSecretRead(command, depth) {
   const { tokens, nested } = tokenize(command);
@@ -1040,7 +1189,7 @@ function findSecretRead(command, depth) {
             const hit = findSecretRead(src, depth + 1);
             if (hit) return hit;
           }
-        } else if (namesSecret(normalizeOperand(w.text))) return w.text;
+        } else if (operandNamesSecret(w.text)) return w.text;
       }
       continue;
     }
@@ -1070,7 +1219,7 @@ function findSecretRead(command, depth) {
     const nameOnly = nameOnlyOperandIndices(base, operands);
     for (let k = 0; k < operands.length; k++) {
       if (nameOnly.has(k)) continue;
-      if (namesSecret(normalizeOperand(operands[k].text))) return operands[k].text;
+      if (operandNamesSecret(operands[k].text)) return operands[k].text;
     }
   }
   return null;
@@ -1088,21 +1237,6 @@ function isDebuggerAgent(value) {
   return value.slice(value.lastIndexOf(':') + 1) === DEBUGGER_AGENT_NAME;
 }
 
-// `timeout [flags] DURATION cmd …` is not in CMD_PREFIXES because its first
-// operand is a duration, not the command. Returns the command that follows it.
-function unwrapTimeout(cmd) {
-  let { base, operands } = cmd;
-  while (base === 'timeout') {
-    let k = 0;
-    while (k < operands.length && operands[k].text.startsWith('-')) k++;
-    k++; // the DURATION operand
-    const rest = resolveCommand(operands.slice(k));
-    if (!rest) return null;
-    ({ base, operands } = rest);
-  }
-  return { base, operands };
-}
-
 // Returns the `--agent` value text of a debugger launch, or null.
 function findDebuggerCliSpawn(command, depth) {
   const { tokens, nested } = tokenize(command);
@@ -1134,8 +1268,7 @@ function findDebuggerCliSpawn(command, depth) {
     }
     if (!words.length) continue;
 
-    const first = resolveCommand(words);
-    const cmd = first && unwrapTimeout(first);
+    const cmd = resolveCommand(words);
     if (!cmd) continue;
     const { base, operands } = cmd;
 
@@ -1248,7 +1381,7 @@ function scanXargsPipe(operands, s, bySeg, sepAfter, depth) {
   const prevCmd = resolveCommand((bySeg.get(prevSeg) || []).filter((t) => t.kind === 'word'));
   if (!prevCmd) return null;
   for (const w of prevCmd.operands) {
-    if (namesSecret(normalizeOperand(w.text))) return w.text;
+    if (operandNamesSecret(w.text)) return w.text;
   }
   return null;
 }
@@ -1423,7 +1556,7 @@ process.stdin.on('end', () => {
     const command = typeof data.tool_input.command === 'string' ? data.tool_input.command : '';
     if (command === '') allow(undefined);
     if (command.length > MAX_COMMAND_LENGTH) emitBlock('command-too-large', tool, '');
-    const hit = findSecretRead(command, 0);
+    const hit = findSecretRead(command, 0) || findSecretReadUnderOtherReadings(command);
     if (hit !== null) emitBlock('secret-read', tool, hit);
     const spawn = findDebuggerCliSpawn(command, 0);
     if (spawn !== null) emitBlock('debugger-cli-spawn', tool, spawn);

package/hooks/dist/gsd-statusline.js

@@ -889,8 +889,40 @@ function compactModelName(name) {
 // are a fixed array, and the workspace dir is passed via -C. Fails silently
 // (segment absent) outside a repo, without git, or on timeout.
 
+// #5048: bound for the `git status` spawn below. With GIT_OPTIONAL_LOCKS=0 the
+// spawn no longer writes the refreshed index back, so what is left is reading
+// the index and stat-ing the tracked paths. The bound keeps a hung network
+// filesystem from stalling a render for long while leaving room for a cold stat
+// cache on a large repo. The figure was chosen, not measured: time
+// `git status --porcelain=v2 --branch` on a large tree with a cold cache before
+// changing it. Exported so the test can pin the bound instead of restating the
+// literal (which is how the constant and its assertion drifted before).
 const GIT_STATUS_TIMEOUT_MS = 1500;
 
+/**
+ * #5048: env for the read-only git spawn in this file.
+ *
+ * By default `git status` refreshes the index and takes an *optional*
+ * `.git/index.lock` to write the refreshed copy back. That is a write the
+ * caller never asked for, and it turns a pure read into a contender for the
+ * lock a real `git add` / `git commit` needs — a read-only statusline render
+ * can then make a concurrent commit fail with
+ * `Unable to create '.git/index.lock': File exists`. The statusline spawns
+ * git on every render, so the lock is re-created continuously.
+ *
+ * The env block itself is owned by src/read-only-git-env.cts and shared with
+ * every other read-only seam (`execGit` in src/shell-command-projection.cts,
+ * `readGitSignals` in src/smart-entry.cts, `gitExec` in
+ * src/pristine-baseline.cts, the two blocking guards). This hook reads it per
+ * call rather than snapshotting at load, so a later `process.env` mutation is
+ * visible and the seams behave identically.
+ *
+ * Deliberately NOT applied to the `git rev-list` spawn in
+ * readStateHeadCommits(): that walks the commit graph and never opens the
+ * index, so the variable would be a no-op there.
+ */
+const { readOnlyGitEnv } = require('../gsd-core/bin/lib/read-only-git-env.cjs');
+
 /**
  * Run `git status --porcelain=v2 --branch` in dir.
  * Returns raw stdout, or null when git is missing, dir isn't a repo, or the
@@ -902,7 +934,7 @@ function readGitStatus(dir) {
     // or untracked files; overflow still degrades safely to segment-absent via
     // the catch below.
     return childProcess.execFileSync('git', ['-C', dir, 'status', '--porcelain=v2', '--branch'],
-      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv() });
   } catch (e) {
     return null;
   }
@@ -995,7 +1027,7 @@ function isValidStateHeadStamp(raw) {
  */
 function readStateHeadCommits(root, stamp) {
   try {
-    return childProcess.execFileSync('git',
+    return childProcess.execFileSync('git', // allow-index-refresh: rev-list walks the commit graph and never opens the index
       ['-C', root, 'rev-list', '--left-right', '--count', `${stamp}...HEAD`],
       { encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
@@ -1396,6 +1428,7 @@ module.exports = {
   isAutoCompactDisabled, AUTO_COMPACT_DISABLE_ENV_KEYS, AUTO_COMPACT_ENV_TRUTHY,
   resolveAutoCompactThreshold, contextMeter, SETTINGS_FILE_MAX_BYTES,
   parseAutoCompactWindowEnv, canonicalModelKey, isAutoCompactWindowValue,
+  GIT_STATUS_TIMEOUT_MS,
 };
 
 /**

package/hooks/dist/gsd-windsurf-pre-write.js

@@ -49,8 +49,35 @@ const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib
 // timeout does. The guard keeps its fail-open posture either way.
 const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: BLOCKING_GUARD_PROBE_TIMEOUT_MS, windowsHide: true };
 
+// #5048: GIT_OPTIONAL_LOCKS=0 on every git call from this hook. `git rev-parse`
+// never opens the index, so this is inert for today's callers; it is set anyway
+// so the read-only invariant has no holes if a `status` / `diff` caller is ever
+// added here. git refreshes the index and takes an *optional*
+// `.git/index.lock` on some reads, and this hook runs on every tool call, so a
+// read here can otherwise fail a concurrent `git add` / `git commit` with
+// `Unable to create '.git/index.lock': File exists`.
+//
+// The env block is owned by src/read-only-git-env.cts and shared with every
+// other read-only seam (built artifact, not a sibling hooks/-tree file — same
+// rule hooks/lib/git-cmd.js follows for token-scanner). It is read per spawn,
+// not snapshotted at load, so the two guards behave identically.
+// Parity: tests/git-optional-locks-parity.test.cjs.
+// A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
+// (#3582), so the compiled owner can be absent. This guard only runs
+// `git rev-parse`, which never opens the index, so the unmodified environment
+// loses nothing; requiring the artifact unguarded would throw at load and the
+// containment guard would silently stop running.
+let readOnlyGitEnv = () => process.env;
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ readOnlyGitEnv } = require('../gsd-core/bin/lib/read-only-git-env.cjs'));
+} catch {
+  // artifact absent and not buildable: keep the inert fallback above
+}
+
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
 }
 
 // Walk up from `start` to find the nearest existing DIRECTORY (not merely an