@opengsd/gsd-core 1.17.0 → 1.19.0

package/hooks/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
@@ -67,6 +69,8 @@
 //   `git check-ignore` / `git ls-files` / `git rm --cached`, and the
 //   destination of a one-source `cp`/`mv` (#4856). The #4856 carve-outs
 //   fail closed: an option they do not list withdraws them from the segment.
+//   A git global option the walker does not know also keeps the #5045 `-c`
+//   scan running over every later word (see walkGitGlobals).
 //   A shell interpreter (bash/sh/zsh/dash/ksh/su) has its script scanned
 //   whether it arrives via `-c '…'`, a `<( )` file operand, a heredoc /
 //   here-string, or a pipe from a knowable `echo`/`printf` source
@@ -88,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
@@ -146,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.
@@ -192,14 +219,29 @@ const GIT_PATHSPEC_SUBCOMMANDS = new Map([
   }],
 ]);
 
-// git's global options (its own usage line, git 2.49), needed to locate the
-// subcommand. A value option consumes the next word unless written
-// `--opt=value`; an option in neither set fails closed, so a value is never
-// read as the subcommand (`git -C ls-files show HEAD:.env` runs `show`).
-const GIT_GLOBAL_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env']);
+// git's global options (git.c handle_options, git 2.49) — the ONE vocabulary
+// both the #4856 pathspec exemption and the #5045 -c scan walk, via
+// walkGitGlobals. A value option consumes the next word; the long options in
+// GIT_GLOBAL_EQUALS_FORM_OPTIONS also take it attached as `--opt=value`.
+// `-C`, `-c` and the hidden `--shallow-file` accept only the separate word
+// (git rejects `--shallow-file=x` and `-c<name>=<value>`), and
+// `--exec-path` runs a subcommand only as `--exec-path=<path>` (bare, it
+// prints the path and exits). Any other option fails closed for both
+// consumers: its arity is unknown, so its value could be read as the
+// subcommand (`git -C ls-files show HEAD:.env` runs `show`). The pathspec
+// exemption is withdrawn, and the -c scan keeps collecting every later
+// `-c <value>` pair instead of stopping.
+const GIT_GLOBAL_VALUE_OPTIONS = new Set([
+  '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env', '--attr-source',
+  '--shallow-file',
+]);
+const GIT_GLOBAL_EQUALS_FORM_OPTIONS = new Set([
+  '--git-dir', '--work-tree', '--namespace', '--config-env', '--attr-source', '--exec-path',
+]);
 const GIT_GLOBAL_FLAGS = new Set([
   '-p', '--paginate', '-P', '--no-pager', '--no-replace-objects', '--no-lazy-fetch',
   '--no-optional-locks', '--no-advice', '--bare',
+  '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs', '--icase-pathspecs',
 ]);
 
 // #4856: `cp`/`mv` write their destination and never print it, so a secret
@@ -388,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.
@@ -422,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;
@@ -458,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 };
 }
@@ -604,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;
     }
@@ -622,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;
     }
@@ -656,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++;
@@ -752,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_]*=/;
@@ -772,23 +881,83 @@ 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) };
 }
 
+/**
+ * Rescan only the command-valued -c keys selected by #5045. This deliberately
+ * does not resolve config files, --config-env/GIT_CONFIG_* values, or other
+ * executing keys (diff drivers, filters, credential helpers, ssh, gpg).
+ * Those are documented gaps, not a promise of complete Git config analysis.
+ * Global option values and subcommand arguments are data, not more -c flags.
+ */
+function scanGitConfig(operands, depth) {
+  for (const config of walkGitGlobals(operands).configs) {
+    const eq = config.indexOf('=');
+    if (eq === -1) continue;
+    const key = config.slice(0, eq).toLowerCase();
+    const value = config.slice(eq + 1);
+    let script;
+    if (key.startsWith('alias.') && value.startsWith('!')) script = value.slice(1);
+    else if (key === 'diff.external') script = value;
+    else continue;
+    const hit = findSecretRead(script, depth + 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 // Operand indices the segment's command consumes as a NAME, never as
 // CONTENTS (#4639, #4856). Only these positions skip the operand check;
 // every other operand is still checked, so a carve-out cannot launder a read
@@ -820,26 +989,38 @@ function isListedFlag(text, flags) {
   return /^-[A-Za-z]+$/.test(text) && [...text.slice(1)].every((ch) => flags.has(`-${ch}`));
 }
 
-// Index of git's subcommand past its global options, or -1 when an option
-// outside GIT_GLOBAL_VALUE_OPTIONS / GIT_GLOBAL_FLAGS precedes it.
-function gitSubcommandIndex(operands) {
+// Walks git's global options (see GIT_GLOBAL_VALUE_OPTIONS). `sub` is the
+// subcommand's index, or -1 when an unlisted option (or the end of the words)
+// comes first; `configs` holds every `-c` value seen on the way, in order.
+// Past an unlisted option the subcommand cannot be located, so `configs`
+// conservatively takes the word after every later `-c` as well: a read
+// still needs a command-valued key, so a harmless value stays allowed.
+function walkGitGlobals(operands) {
+  const configs = [];
   for (let k = 0; k < operands.length; k++) {
     const t = operands[k].text;
-    if (!t.startsWith('-')) return k;
-    if (GIT_GLOBAL_VALUE_OPTIONS.has(t)) { k++; continue; }
+    if (!t.startsWith('-')) return { sub: k, configs };
+    if (GIT_GLOBAL_VALUE_OPTIONS.has(t)) {
+      if (t === '-c' && k + 1 < operands.length) configs.push(operands[k + 1].text);
+      k++;
+      continue;
+    }
     if (GIT_GLOBAL_FLAGS.has(t)) continue;
     const eq = t.indexOf('=');
-    const isLongValueForm = t.startsWith('--') && eq !== -1 && GIT_GLOBAL_VALUE_OPTIONS.has(t.slice(0, eq));
-    if (!isLongValueForm) return -1;
+    if (t.startsWith('--') && eq !== -1 && GIT_GLOBAL_EQUALS_FORM_OPTIONS.has(t.slice(0, eq))) continue;
+    for (let j = k + 1; j + 1 < operands.length; j++) {
+      if (operands[j].text === '-c') configs.push(operands[++j].text);
+    }
+    return { sub: -1, configs };
   }
-  return -1;
+  return { sub: -1, configs };
 }
 
 // #4856: the pathspec operands of a GIT_PATHSPEC_SUBCOMMANDS invocation. git
 // permutes options, so one may follow a pathspec; after `--` every word is a
 // pathspec. The subcommand is matched case-sensitively, as git looks it up.
 function gitPathspecIndices(operands) {
-  const sub = gitSubcommandIndex(operands);
+  const { sub } = walkGitGlobals(operands);
   const spec = sub === -1 ? undefined : GIT_PATHSPEC_SUBCOMMANDS.get(operands[sub].text);
   if (!spec) return new Set();
   const pathspecs = new Set();
@@ -910,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);
@@ -988,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;
     }
@@ -1007,12 +1208,18 @@ function findSecretRead(command, depth) {
       // `bash .env` (file mode) is caught by the operand check below.
     }
 
+    // Git -c can carry a shell script instead of a file-name operand (#5045).
+    if ((base === 'git' || base === 'git.exe') && depth < MAX_NESTING_DEPTH) {
+      const hit = scanGitConfig(operands, depth);
+      if (hit) return hit;
+    }
+
     if (NON_READING_COMMANDS.has(base)) continue;
 
     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;
@@ -1030,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);
@@ -1076,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;
 
@@ -1190,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;
 }
@@ -1365,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/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/gsd-validate-commit.sh

@@ -39,6 +39,27 @@ cleanup_temp_files() {
 }
 trap cleanup_temp_files EXIT
 
+# The first line of $1 (everything before the first newline), matched BYTE-wise.
+#
+# `${1%%$'\n'*}` is a longest-suffix glob match, and on bash 3.2 (macOS's
+# /bin/bash) in a multibyte locale such as en_US.UTF-8 it costs ~3.5 s on a
+# 112KB value (#5473, measured inside the macOS conformance job: the same hook
+# on the same 114750-byte command took ~5.6 s under LC_ALL=en_US.UTF-8 and
+# ~0.55 s under LC_ALL=C, and a trace put 3.5 s of it on this expansion). A
+# newline is the same single byte in every locale, so matching it byte-wise
+# changes no result.
+#
+# ONLY call this inside a command substitution, `SUBJECT=$(gsd_first_line "$MSG")`:
+# the substitution's subshell is what keeps LC_ALL=C from leaking into the rest
+# of the hook, whose regexes and length arithmetic keep the caller's locale. A
+# substitution is a fork with no pipe between two processes, so it keeps the
+# property the pure-expansion form was chosen for (no `head -1` SIGPIPE race
+# under `set -euo pipefail`, #4429); printf is a builtin, so no exec either.
+gsd_first_line() {
+  LC_ALL=C
+  printf '%s' "${1%%$'\n'*}"
+}
+
 # The 10 built-in Conventional Commits types — the SINGLE declaration (#3811
 # review finding: this was previously hand-typed a second time inside the
 # node -e script below, a generative-fix-divergence risk per CLAUDE.md's
@@ -575,18 +596,19 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       SUBJECT=$(GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" MSG="$MSG" node -e "
         const {resolveCommitSubject}=require(process.env.GIT_CMD_LIB);
         process.stdout.write(resolveCommitSubject(process.env.MSG));
-      " 2>/dev/null) || SUBJECT="${MSG%%$'\n'*}"
+      " 2>/dev/null) || SUBJECT=$(gsd_first_line "$MSG")
     else
-      # Pure parameter expansion, not `echo "$MSG" | head -1`: that pipeline
+      # Pure parameter expansion (in gsd_first_line), not
+      # `echo "$MSG" | head -1`: that pipeline
       # raced a SIGPIPE under `set -euo pipefail` whenever $MSG had a body
       # (the common case) — `head -1` can close its read end as soon as it
       # has the first line, and if `echo`'s write lands after that close,
       # `echo` dies with signal 13 (exit 141), which is NOT suppressed by
       # `set -e` and aborted the whole hook intermittently (observed in
-      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). Zero
-      # subprocesses here means zero pipe/race surface. Equivalent to
+      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). No pipe
+      # means no race surface. Equivalent to
       # `head -1` for single-line, multi-line, and trailing-newline input.
-      SUBJECT="${MSG%%$'\n'*}"
+      SUBJECT=$(gsd_first_line "$MSG")
     fi
     # Single source of truth for the accepted commit-type list (#3811): the
     # 10 built-ins plus whatever passed the safe-token filter above. Both the

package/hooks/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

package/hooks/gsd-workflow-guard.js

@@ -81,7 +81,7 @@ function forceGitAddCwds(command, defaultCwd) {
 }
 
 function currentBranch(cwd) {
-  const result = spawnSync('git', ['branch', '--show-current'], {
+  const result = spawnSync('git', ['branch', '--show-current'], { // allow-index-refresh: reads HEAD only, never opens the index
     cwd,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],