@opengsd/gsd-core 1.15.0 → 1.17.0

package/hooks/gsd-statusline.js

@@ -3,6 +3,14 @@
 // Claude Code Statusline - GSD Edition
 // Shows: model | current task (or GSD state) | directory | context usage
 
+// #5183: Node's on-disk compile cache, so later runs reuse V8's compiled code
+// for unchanged modules. Only as the entry (a test require() is unaffected),
+// skipped under V8 coverage, optional (Bun stubs it), and never fatal.
+// NODE_DISABLE_COMPILE_CACHE (any value) turns it off.
+if (require.main === module && !process.env.NODE_V8_COVERAGE) {
+  try { require('node:module').enableCompileCache?.(); } catch { /* optimization only */ }
+}
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -42,6 +50,7 @@ if (require.main === module) {
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
 const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 const {
   renderBracketPhaseDisplay,
   renderBracketMilestoneDisplay,
@@ -161,6 +170,303 @@ function readStateFileOrNull(statePath) {
   }
 }
 
+/**
+ * The env vars Claude Code itself consults to switch auto-compaction off, and
+ * the values it accepts as true. Both are taken from the shipped binary's own
+ * resolution — `Boolean(truthy(DISABLE_COMPACT) || DISABLE_AUTO_COMPACT)`, and
+ * only when that is false does `autoCompactEnabled` decide — rather than
+ * guessed: an invented name reads as "not disabled" forever, which is exactly
+ * the defect this gate exists to close.
+ *
+ * The truthy set applies to both keys: in the binary (claude 2.1.292) the
+ * second operand is the env registry's `D.bool()` field, which runs the same
+ * `["1","true","yes","on"]` helper as `DISABLE_COMPACT`.
+ */
+const AUTO_COMPACT_DISABLE_ENV_KEYS = ['DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT'];
+const AUTO_COMPACT_ENV_TRUTHY = ['1', 'true', 'yes', 'on'];
+
+/**
+ * Is Claude Code's auto-compact switched off for this session? When it is,
+ * the auto-compact buffer is ordinary usable context, so the meter's 100% is
+ * the model window — otherwise the bar pins at 100% early and the last of
+ * the window is invisible.
+ *
+ * The sources and their precedence mirror Claude Code's own resolution —
+ * either env var wins over the setting, and only then does the setting decide:
+ *   1. env: DISABLE_AUTO_COMPACT, or DISABLE_COMPACT (which switches off
+ *      manual `/compact` as well). Truthy is `1` / `true` / `yes` / `on`,
+ *      trimmed and case-insensitive — Claude Code's own accepted set.
+ *   2. <dir>/.claude/settings.local.json, <dir>/.claude/settings.json
+ *   3. (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json
+ * reading the boolean `autoCompactEnabled`. Fail-soft: anything unreadable
+ * or absent means "not disabled" (current behaviour).
+ */
+function isAutoCompactDisabled(dir, env = process.env) {
+  for (const key of AUTO_COMPACT_DISABLE_ENV_KEYS) {
+    const v = env[key];
+    if (typeof v === 'string' && AUTO_COMPACT_ENV_TRUTHY.includes(v.trim().toLowerCase())) return true;
+  }
+  return readClaudeSetting(dir, env, 'autoCompactEnabled', v => typeof v === 'boolean') === false;
+}
+
+/**
+ * The first value of `key` that `accept` takes, reading the Claude Code
+ * settings files highest precedence first:
+ *   <dir>/.claude/settings.local.json, <dir>/.claude/settings.json,
+ *   (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json.
+ * Fail-soft: an absent or unparseable file is skipped; nothing found is
+ * `undefined`.
+ */
+function readClaudeSetting(dir, env, key, accept) {
+  // Lazy: stop at the first file that answers, so a lower file is never read.
+  for (const file of claudeSettingsPaths(dir, env)) {
+    const settings = readSettingsFile(file);
+    if (settings && accept(settings[key])) return settings[key];
+  }
+  return undefined;
+}
+
+/**
+ * The parsed Claude Code settings files, highest precedence first. An absent,
+ * unparseable or non-object file is left out.
+ */
+function readClaudeSettingsFiles(dir, env) {
+  return claudeSettingsPaths(dir, env).map(readSettingsFile).filter(Boolean);
+}
+
+/**
+ * A settings file larger than this is treated as absent. Claude Code's own
+ * settings files are a few kilobytes; the cap keeps a hostile project's
+ * `.claude/settings.json` from bloating a read that runs on every render.
+ */
+const SETTINGS_FILE_MAX_BYTES = 1024 * 1024;
+
+/**
+ * The parsed settings object in `file`, or null. Only a regular file of at
+ * most SETTINGS_FILE_MAX_BYTES is read: the project's `.claude/` is
+ * repository content, and a FIFO there would block the statusline forever.
+ * The file is opened non-blocking and checked through its own descriptor,
+ * so the check and the read see the same file, and at most the checked size
+ * is read: a file that grew or shrank after the check is absent. A symlink
+ * is followed — a settings file linked in from a dotfiles repo is ordinary.
+ */
+function readSettingsFile(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > SETTINGS_FILE_MAX_BYTES) return null;
+    // One byte past the checked size, so growth after the check shows as a longer read.
+    const buf = Buffer.alloc(st.size + 1);
+    let n = 0;
+    for (let r; n < buf.length && (r = fs.readSync(fd, buf, n, buf.length - n, n)) > 0;) n += r;
+    if (n !== st.size) return null;
+    const settings = JSON.parse(buf.toString('utf8', 0, n));
+    return settings && typeof settings === 'object' && !Array.isArray(settings) ? settings : null;
+  } catch (e) {
+    return null; // absent, unreadable or unparseable — keep looking
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (e) { /* already closed */ }
+    }
+  }
+}
+
+/**
+ * The Claude Code settings file paths, highest precedence first:
+ *   <dir>/.claude/settings.local.json, <dir>/.claude/settings.json,
+ *   (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json.
+ */
+function claudeSettingsPaths(dir, env) {
+  const candidates = [];
+  if (dir) {
+    candidates.push(path.join(dir, '.claude', 'settings.local.json'));
+    candidates.push(path.join(dir, '.claude', 'settings.json'));
+  }
+  let claudeDir;
+  try {
+    claudeDir = env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  } catch (e) {
+    claudeDir = null;
+  }
+  if (claudeDir) {
+    candidates.push(path.join(claudeDir, 'settings.local.json'));
+    candidates.push(path.join(claudeDir, 'settings.json'));
+  }
+  return candidates;
+}
+
+/**
+ * Claude Code's settings key for a model: its canonical name, which also
+ * matches the dated, `[1m]`, Bedrock and Vertex spellings of it
+ * (`claude-opus-5-5[1m]`, `us.anthropic.claude-opus-5-5-v1:0` and
+ * `claude-opus-5-5@20260101` all key as `claude-opus-5-5`). A Bedrock
+ * revision suffix is stripped only after a version or date segment, so a
+ * model whose own name ends in `-v<n>` (`anthropic.claude-v2`) keeps it.
+ * The rules repeat until nothing changes, so a key is its own key: one pass
+ * left `x[1m][1m]` as `x[1m]`. Lowercasing runs once, before the loop (it
+ * can lengthen a string: `İ` becomes two characters); inside the loop every
+ * rule only removes characters, so it ends. A key longer than
+ * MODEL_KEY_MAX_LENGTH is no model's — '' — which also bounds the loop's
+ * work on a hostile settings file. '' for a non-string.
+ */
+const MODEL_KEY_MAX_LENGTH = 256;
+
+function canonicalModelKey(id) {
+  if (typeof id !== 'string') return '';
+  let key = id.toLowerCase();
+  if (key.length > MODEL_KEY_MAX_LENGTH) return '';
+  for (let prev; prev !== key;) {
+    prev = key;
+    key = key.trim()
+      .replace(/(?:\[1m\])+$/, '')
+      .replace(/^(?:[a-z]+\.)?anthropic\./, '')
+      .replace(/(\d)-v\d+(?::\d+)?$/, '$1')
+      .replace(/@\d{8}$/, '')
+      .replace(/-\d{8}$/, '');
+  }
+  return key;
+}
+
+function isAutoCompactWindowValue(v) {
+  return v === 'auto' ||
+    (Number.isInteger(v) && v >= AUTO_COMPACT_WINDOW_MIN && v <= AUTO_COMPACT_WINDOW_MAX);
+}
+
+/**
+ * The `autoCompactWindow` setting for this model, merged across the settings
+ * files the way Claude Code merges it (claude 2.1.292): lowest precedence
+ * first, each file's `modelSettings.<model>.autoCompactWindow` entries
+ * layer over the lower files', and a file that sets a top-level
+ * `autoCompactWindow` replaces the default and drops the lower files'
+ * per-model entries. The model's own entry wins over the default.
+ * `/autocompact` saves the per-model entry; older versions saved the
+ * top-level one. `"auto"` (Claude Code's tuned window) and an absent setting
+ * are null, so the caller falls back to the model window. An invalid value
+ * is treated as absent.
+ */
+function readAutoCompactWindowSetting(dir, env, modelId) {
+  let fallback;
+  let byModel = {};
+  for (const settings of readClaudeSettingsFiles(dir, env).reverse()) {
+    const own = {};
+    const perModel = settings.modelSettings;
+    if (perModel && typeof perModel === 'object' && !Array.isArray(perModel)) {
+      for (const [name, entry] of Object.entries(perModel)) {
+        const v = entry && typeof entry === 'object' ? entry.autoCompactWindow : undefined;
+        if (!isAutoCompactWindowValue(v)) continue;
+        const key = canonicalModelKey(name);
+        // A canonically spelled key wins over another spelling of it.
+        if (name === key || !Object.hasOwn(own, key)) own[key] = v;
+      }
+    }
+    if (isAutoCompactWindowValue(settings.autoCompactWindow)) {
+      fallback = settings.autoCompactWindow;
+      byModel = own;
+    } else {
+      byModel = { ...byModel, ...own };
+    }
+  }
+  const key = canonicalModelKey(modelId);
+  const value = key && Object.hasOwn(byModel, key) ? byModel[key] : fallback;
+  return Number.isInteger(value) ? value : null;
+}
+
+/**
+ * Where Claude Code auto-compacts (#4985). The meter's 100% is this token
+ * count, so it has to be resolved the way Claude Code resolves it:
+ *
+ *   window     CLAUDE_CODE_AUTO_COMPACT_WINDOW (an unparseable or non-positive
+ *              value is ignored; capped at 1M, raised to 100k), else the
+ *              `autoCompactWindow` setting `/autocompact` saves, per model or
+ *              top-level (an integer in 100k–1M; see
+ *              readAutoCompactWindowSetting), else the model window. Always
+ *              capped at the model window.
+ *   threshold  window − min(model max output, 20,000) − 13,000, lowered to
+ *              floor((window − 20,000) × pct / 100) when
+ *              CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (0 < pct ≤ 100) is lower.
+ *
+ * `/context` shows the 33,000 as "Autocompact buffer". The hardcoded 16.5%
+ * this replaces is 33,000 / 200,000, so it was right only on a 200K window
+ * with nothing configured. Every current model's max output is at least
+ * 20,000, so the reserve is taken as 20,000.
+ *
+ * Not visible to a statusline, so not modelled: the `--autocompact` launch
+ * flag, managed-policy settings, and Claude Code's server-side and per-model
+ * window defaults (what `"auto"` resolves to). Those sessions fall back to
+ * the model window.
+ */
+const AUTO_COMPACT_WINDOW_MIN = 100_000;
+const AUTO_COMPACT_WINDOW_MAX = 1_000_000;
+const AUTO_COMPACT_OUTPUT_RESERVE = 20_000;
+const AUTO_COMPACT_SUMMARY_BUFFER = 13_000;
+
+function parseAutoCompactWindowEnv(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return null;
+  const s = raw.trim();
+  const n = /^\d[\d_,]*$/.test(s) ? parseInt(s.replace(/[_,]/g, ''), 10) : parseInt(s, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return Math.max(AUTO_COMPACT_WINDOW_MIN, Math.min(AUTO_COMPACT_WINDOW_MAX, n));
+}
+
+/**
+ * The token count at which Claude Code auto-compacts this session, or null
+ * when auto-compaction is off (see isAutoCompactDisabled).
+ */
+function resolveAutoCompactThreshold(modelWindow, dir, env = process.env, modelId) {
+  if (!(modelWindow > 0) || isAutoCompactDisabled(dir, env)) return null;
+  let window = parseAutoCompactWindowEnv(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW);
+  if (window === null) {
+    window = readAutoCompactWindowSetting(dir, env, modelId) ?? modelWindow;
+  }
+  const effective = Math.min(window, modelWindow) - AUTO_COMPACT_OUTPUT_RESERVE;
+  let threshold = effective - AUTO_COMPACT_SUMMARY_BUFFER;
+  const pct = parseFloat(env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE);
+  if (Number.isFinite(pct) && pct > 0 && pct <= 100) {
+    threshold = Math.min(threshold, Math.floor(effective * (pct / 100)));
+  }
+  return threshold > 0 ? threshold : null;
+}
+
+/**
+ * The context meter, in one scale: `used` + `remaining` = 100, where 100% is
+ * the auto-compact threshold, or the model window when compaction is off.
+ * `usedTokens` is Claude Code's own count (input + cache creation + cache
+ * read of the last turn, the sum /context reports) and `limitTokens` the
+ * token count 100% stands for.
+ *
+ * Taken from token counts, not by re-scaling `remaining_percentage`: that
+ * value is already rounded against the model window, which loses up to 5,000
+ * tokens on a 1M model. Without `current_usage` the tokens are recovered
+ * from the percentage; without `context_window_size` the window is unknown,
+ * so the meter shows Claude Code's own percentage unscaled. Returns null
+ * when there is no usage yet.
+ */
+function contextMeter(contextWindow, dir, env = process.env, modelId) {
+  if (!contextWindow || typeof contextWindow !== 'object') return null;
+  const size = Number(contextWindow.context_window_size);
+  const usage = contextWindow.current_usage;
+  const remainingPct = contextWindow.remaining_percentage;
+  if (size > 0) {
+    let usedTokens = null;
+    if (usage && typeof usage === 'object') {
+      usedTokens = (Number(usage.input_tokens) || 0) +
+        (Number(usage.cache_creation_input_tokens) || 0) +
+        (Number(usage.cache_read_input_tokens) || 0);
+    } else if (remainingPct != null) {
+      usedTokens = Math.round(((100 - remainingPct) * size) / 100);
+    }
+    if (usedTokens !== null) {
+      const limitTokens = resolveAutoCompactThreshold(size, dir, env, modelId) ?? size;
+      const used = Math.max(0, Math.min(100, Math.round((usedTokens / limitTokens) * 100)));
+      return { used, remaining: 100 - used, usedTokens, limitTokens };
+    }
+  }
+  if (remainingPct == null) return null;
+  const used = Math.max(0, Math.min(100, Math.round(100 - remainingPct)));
+  return { used, remaining: 100 - used, usedTokens: null, limitTokens: null };
+}
+
 /**
  * Walk up from dir looking for .planning/STATE.md (flat mode). If an ancestor
  * has no flat STATE.md but IS in workstream mode (.planning/workstreams/
@@ -250,13 +556,12 @@ function readGsdState(dir, opts = {}) {
 function parseStateMd(content) {
   const state = {};
 
-  // YAML frontmatter between --- markers (anchored at file start).
-  // #2754: \r?\n (not literal \n) so a CRLF STATE.md (Windows-authored) parses
-  // identically to LF — pre-fix the literal-\n fence dropped the ENTIRE block.
-  // Mirrors the CRLF-safe extractFrontmatter in src/frontmatter.cts.
-  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (fmMatch) {
-    const fm = fmMatch[1];
+  // YAML frontmatter: the block the one fence owner finds (`locateFrontmatterFence`), so a
+  // CRLF STATE.md (#2754), a BOM, and a `---` inside a value read exactly as every other
+  // STATE.md reader reads them (found while implementing #5105).
+  const fence = locateFrontmatterFence(content);
+  if (fence && fence.closed) {
+    const fm = content.slice(fence.openEnd, fence.bodyEnd);
     // Top-level scalar key: value
     for (const line of fm.split(/\r?\n/)) {
       const m = line.match(/^(\w+):\s*(.+)/);
@@ -822,28 +1127,22 @@ function runStatusline() {
     const model = compactModelName(data.model?.display_name || 'Claude');
     const dir = data.workspace?.current_dir || process.cwd();
     const session = data.session_id || '';
-    const remaining = data.context_window?.remaining_percentage;
 
     // Read .planning config once — used by the context meter (token suffix)
     // and the last-command/position block below. Fail-soft to {}.
     let cfg = {};
     try { cfg = readGsdConfig(dir); } catch (e) {}
 
-    // Context window display (shows USED percentage scaled to usable context)
-    // Claude Code reserves a buffer for autocompact. By default this is ~16.5%
-    // of the total window, but users can override it via CLAUDE_CODE_AUTO_COMPACT_WINDOW
-    // (a token count). When the env var is set, compute the buffer % dynamically so
-    // the meter correctly reflects early-compaction configurations (#2219).
-    const totalCtx = data.context_window?.total_tokens || 1_000_000;
-    const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
-    const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
-      : 16.5;
+    // Context window display: USED percentage of the auto-compact threshold,
+    // so 100% is where Claude Code compacts — resolved from
+    // CLAUDE_CODE_AUTO_COMPACT_WINDOW, the `autoCompactWindow` setting, or the
+    // model window (#2219, #4985). With auto-compact disabled (#4844) 100% is
+    // the model window. Project settings are read from workspace.project_dir,
+    // Claude Code's launch directory, not the current directory.
+    const meter = contextMeter(data.context_window, data.workspace?.project_dir || dir, process.env, data.model?.id);
     let ctx = '';
-    if (remaining != null) {
-      // Normalize: subtract buffer from remaining, scale to usable range
-      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
-      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+    if (meter) {
+      const { used } = meter;
 
       // Write context metrics to bridge file for the context-monitor PostToolUse hook.
       // The monitor reads this file to inject agent-facing warnings when context is low.
@@ -853,15 +1152,20 @@ function runStatusline() {
       if (sessionSafe) {
         try {
           const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
-          // used_pct written to the bridge must match CC's native /context reporting:
-          // raw used = 100 - remaining_percentage (no buffer normalization applied).
-          // The normalized `used` value is correct for the statusline progress bar but
-          // inflates the context monitor warning messages by ~13 points (#2451).
-          const rawUsedPct = Math.round(100 - remaining);
+          // The bridge is on the bar's scale: remaining_percentage counts down
+          // to the auto-compact threshold, so the monitor's WARNING/CRITICAL
+          // fire before compaction rather than after it (#4985). The token
+          // counts let its message match /context, which is what #2451 kept
+          // the bridge raw for; they are absent when the payload has no
+          // context_window_size.
           const bridgeData = JSON.stringify({
             session_id: session,
-            remaining_percentage: remaining,
-            used_pct: rawUsedPct,
+            remaining_percentage: meter.remaining,
+            used_pct: used,
+            ...(meter.usedTokens !== null && {
+              used_tokens: meter.usedTokens,
+              threshold_tokens: meter.limitTokens,
+            }),
             timestamp: Math.floor(Date.now() / 1000)
           });
           fs.writeFileSync(bridgePath, bridgeData);
@@ -1089,6 +1393,9 @@ module.exports = {
   readStateHeadCommits, parseRevListCounts, deriveStateFreshness,
   formatStateFreshness, resolveStatuslineOptions,
   renderBracketPhaseDisplay, renderBracketMilestoneDisplay,
+  isAutoCompactDisabled, AUTO_COMPACT_DISABLE_ENV_KEYS, AUTO_COMPACT_ENV_TRUTHY,
+  resolveAutoCompactThreshold, contextMeter, SETTINGS_FILE_MAX_BYTES,
+  parseAutoCompactWindowEnv, canonicalModelKey, isAutoCompactWindowValue,
 };
 
 /**

package/hooks/gsd-update-banner.js

@@ -12,6 +12,14 @@
 
 'use strict';
 
+// #5183: Node's on-disk compile cache, so later runs reuse V8's compiled code
+// for unchanged modules. Only as the entry (a test require() is unaffected),
+// skipped under V8 coverage, optional (Bun stubs it), and never fatal.
+// NODE_DISABLE_COMPILE_CACHE (any value) turns it off.
+if (require.main === module && !process.env.NODE_V8_COVERAGE) {
+  try { require('node:module').enableCompileCache?.(); } catch { /* optimization only */ }
+}
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');

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

@@ -31,14 +31,23 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { allow, deny } = require('./lib/hook-exit.js');
-const { reportIfUndetermined } = require('./lib/git-probe.js');
+const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
 // migrated to hook-exit.js's deny(undefined, reason) — see
 // gsd-windsurf-pre-command.js's identical note for the fixed defect
 // (terminateNow's fd 1/fd 2 writes now run in independent try/catch blocks).
 
-const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };
+// Shared blocking-guard probe budget (hooks/lib/git-probe.js, #5180): a timed-out
+// probe fails open, so it is sized for a starved host. Windsurf documents NO
+// hook timeout (docs.devin.ai/desktop/cascade/hooks lists only an aspirational
+// "sub-100ms" target) and this surface's registration entry
+// (buildWindsurfHookEntry in src/runtime-hooks-surface.cts) carries none, so the
+// host budget is UNKNOWN. This guard runs at most 3 sequential probes (15 s
+// worst case); that worst case is NOT claimed to fit any host budget — if
+// Windsurf kills the hook sooner, the host kill fails open exactly as a probe
+// 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 };
 
 function git(args, cwd) {
   return spawnSync('git', args, { ...SPAWNOPT, cwd });

package/hooks/gsd-workflow-guard.js

@@ -22,7 +22,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined } = require('./lib/git-probe.js');
+const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard is almost entirely advisory (fail open — a broken advisory must
 // never wedge every tool call), with ONE hard block (#3504 force-add-on-
@@ -87,11 +87,12 @@ function currentBranch(cwd) {
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,
     // #3504: bounded — this ran unbounded before, an indefinite hang under a
-    // wedged git would hang every PreToolUse call. Host wiring allows a 5s
-    // budget for the whole hook, so the probe gets 2s of it; a timeout
+    // wedged git would hang every PreToolUse call. The probe gets the shared
+    // blocking-guard budget (hooks/lib/git-probe.js, #5180), well inside the
+    // 120s host budget this guard is registered with (#3981); a timeout
     // returns '' (branch unknown), which both the block decision and the
     // fail-closed re-check treat as "cannot establish agent branch".
-    timeout: 2000,
+    timeout: BLOCKING_GUARD_PROBE_TIMEOUT_MS,
     killSignal: 'SIGTERM',
   });
   // #3911: a timeout/spawn-failure here previously degraded to '' exactly

package/hooks/gsd-worktree-path-guard.js

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined } = require('./lib/git-probe.js');
+const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard's outer catch has always exited 0 (fail open): a path guard that
 // cannot resolve the worktree must not block the user's edit — its whole job
@@ -28,7 +28,11 @@ const { reportIfUndetermined } = require('./lib/git-probe.js');
 // rather than inheriting a default (#3911).
 const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
-const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };
+// A timed-out git probe fails OPEN (see ON_CRASH above), so the per-probe
+// budget is the shared blocking-guard value, sized for a starved host rather
+// than git's ~0.1s typical run (rationale and arithmetic in
+// hooks/lib/git-probe.js, #5180). This guard runs at most 3 sequential probes.
+const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: BLOCKING_GUARD_PROBE_TIMEOUT_MS, windowsHide: true };
 
 function git(args, cwd) {
   return spawnSync('git', args, { ...SPAWNOPT, cwd });

package/hooks/hooks.json

@@ -12,32 +12,32 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-prompt-guard.js\"", "timeout": 5 },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-prompt-guard.js\"", "timeout": 120 },
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-read-guard.js\"", "timeout": 5 }
         ]
       },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-worktree-path-guard.js\"", "timeout": 5 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-worktree-path-guard.js\"", "timeout": 120 }
         ]
       },
       {
         "matcher": "Write",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-write-guard.js\"", "timeout": 5 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-write-guard.js\"", "timeout": 120 }
         ]
       },
       {
         "matcher": "Read|Grep|Bash",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-secret-read-guard.js\"", "timeout": 5 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-secret-read-guard.js\"", "timeout": 120 }
         ]
       },
       {
         "matcher": "Agent|Task",
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-agent-isolation-guard.js\"", "timeout": 5 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-agent-isolation-guard.js\"", "timeout": 120 }
         ]
       }
     ],

package/hooks/lib/cli-exit.js

@@ -185,6 +185,17 @@ function setPendingOutcome(v) {
 function getPendingOutcome() {
     return globalThis[PENDING_OUTCOME_KEY];
 }
+/**
+ * Declare the outcome a void-returning `main()` ends with (#5170, ADR-5057 §4): writes the
+ * pending-outcome cell that `runMain` projects. Validates `name` is an outcome
+ * `projectOutcome` accepts (PASS, FAIL or a registered name) and THROWS otherwise, so a typo'd
+ * name fails at the declaration rather than at process exit. Call it AFTER `output()`, which
+ * rewrites the cell on every call. `output()` and this are the only writers of the cell.
+ */
+function declareOutcome(name) {
+    projectOutcome(name, 'v1');
+    setPendingOutcome(name);
+}
 const EXIT_CONTRACT_FLAG_PREFIX = '--exit-contract=';
 /** Scan argv for the FIRST `--exit-contract=<value>` token; undefined if absent. */
 function findExitContractFlag(argv) {
@@ -557,4 +568,5 @@ module.exports = {
     terminateNow,
     setPendingOutcome,
     getPendingOutcome,
+    declareOutcome,
 };

package/hooks/lib/git-probe.js

@@ -81,4 +81,20 @@ function reportIfUndetermined(hookName, probeLabel, result) {
   }
 }
 
-module.exports = { classifyGitProbe, reportIfUndetermined };
+// Per-probe budget for the git probes of BLOCKING guards. A probe that times
+// out fails OPEN (see reportIfUndetermined above), which is the same outcome
+// as the host killing the hook — so a budget sized to git's ~0.1s typical run
+// silently disables the gate on a starved host (a 2000ms budget was exceeded
+// on a loaded Windows runner, #5180). Worst case for a guard that runs up to
+// BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES sequential probes:
+//   3 x 5000ms + ~500ms node start/kill/reap = ~15.5s,
+// inside the 120s host budget blocking guards are registered with (#3981).
+const BLOCKING_GUARD_PROBE_TIMEOUT_MS = 5000;
+const BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES = 3;
+
+module.exports = {
+  classifyGitProbe,
+  reportIfUndetermined,
+  BLOCKING_GUARD_PROBE_TIMEOUT_MS,
+  BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES,
+};

package/hooks/lib/isolation-sentinel.js

@@ -23,8 +23,8 @@
 // explicit fallback for the per-plan submodule-degrade override and shares
 // the exact same atomic-write implementation.
 //
-// Sentinel path: `<cwd>/.gsd/dispatch-isolation-sentinel.json`. `.gsd` is
-// gitignored (root `.gitignore`'s bare `.gsd` entry matches at any depth),
+// Sentinel path: `<cwd>/.gsd/dispatch-isolation-sentinel.json`. The writer
+// seeds `.gsd/.gitignore` so this stays ignored in user projects too,
 // and lives inside the checkout that ran the workflow — concurrent worktrees
 // of the same repo are separate directories on disk, so each gets its own
 // sentinel with no cross-worktree collision, no lock file needed.