@opengsd/gsd-core 1.11.0 → 1.12.0

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

@@ -37,7 +37,7 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 If $ARGUMENTS contains a phase number, load context:
 
 ```bash
-_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[A-Za-z0-9._-]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[A-Za-z0-9._-]+')
 PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[A-Za-z0-9._-]+//g' | xargs)
@@ -61,15 +61,26 @@ MVP_MODE=$(gsd_run query phase.mvp-mode "${phase_number}" ${GSD_WS} --pick activ
 </step>
 
 <step name="verify_pre_hooks">
-**Verify:pre gate dispatch.** Before verification begins, dispatch every active
-gate hook registered at the `verify:pre` loop extension point. Each gate is
-data-driven — resolved from the capability registry, not hardcoded here.
+**Verify:pre capability dispatch.** Before verification begins, dispatch every
+active hook registered at the `verify:pre` loop extension point — of **every**
+kind, not gates alone. Each hook is data-driven — resolved from the capability
+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')
 ```
 
+Read the `activeHooks` array from `VERIFY_PRE_HOOKS_JSON` in-context (do NOT pipe through a shell parser).
+
+**If `activeHooks` is empty or absent:** skip silently to `check_active_session`.
+
+**Contribution dispatch:** inject every `kind == "contribution"` fragment per @gsd-core/references/loop-hook-dispatch.md (skip when none), before the steps and gates below.
+
+**Step dispatch:** dispatch every `kind == "step"` hook per @gsd-core/references/loop-hook-dispatch.md (skip when none) — not one shape of one. A step here is advisory: it never blocks the start of UAT, and a step that errors is routed by its own `onError` without failing verification. ⚠ **Validate `ref.command` in-context before any shell use** (third-party manifest input) — loop-hook-dispatch.md § `step`.
+
+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`.
 
 Resolve active gate hooks from `VERIFY_PRE_HOOKS_JSON` where `kind == "gate"`.
@@ -187,6 +198,35 @@ Read the JSON result (`mode`, `total`, `all_auto_covered`, `auto_passed[]`, `pre
 
 The cold-start smoke test injection below still applies in `coverage` mode.
 
+**Verify:pre produced-artefact seam (#3866).** If `VERIFY_PRE_PRODUCED` (recorded in
+`verify_pre_hooks`) is empty or absent, skip this paragraph entirely — derivation is unchanged.
+Otherwise, for each artefact name in it, locate the artefact the producing step wrote under
+`$PHASE_DIR` and merge its checkpoints into the test list **additively**.
+
+**The artefact contract.** A consumable artefact is a Markdown file holding a list of checkpoint
+entries in the **same shape `extract_tests` already emits and `create_uat_file` already consumes** —
+each entry a `name` (brief test name) and an `expected` (specific, user-observable outcome).
+Nothing else is read: extra fields are ignored, not an error. There is no new schema and no new
+parser — a producing step writes what a checkpoint already looks like. An artefact that yields zero
+parseable entries is treated exactly like an absent one (see below).
+
+Merge rules:
+
+- ⚠ **Validate the artefact name in-context before resolving it** (third-party manifest input).
+  An artefact name is a registry-declared name, **not** a path: check the value you read from
+  `produces` against `^[A-Za-z0-9][A-Za-z0-9._-]*$` yourself — **never** by pasting it into a
+  shell command to be tested there. A name carrying `/`, `..`, a leading `-`, a leading path
+  separator, or any shell metacharacter is a malformed manifest: record a warning, skip that
+  name, continue. Only a validated name is resolved, and only against what the step wrote inside
+  `$PHASE_DIR` — never above it, and never through a symlink that leaves it.
+- A name with no artefact on disk means that step was inactive, skipped, or failed. Note it to the
+  user and derive normally — **never drop a deliverable and never block UAT over it.**
+- Merged entries are added to, never subtracted from, what `coverage:` classification and the
+  prose fallback produce. An `auto_passed[]` entry stays un-presented; a `present[]` entry stays a
+  human checkpoint. This seam can deepen UAT, not suppress it.
+- Deduplicate against already-derived checkpoints by `name`, keeping the earlier entry's
+  `expected` text so a produced artefact cannot silently rewrite a criterion.
+
 **Extract testable deliverables from SUMMARY.md (legacy fallback — used when `mode: legacy`):**
 
 Parse for:
@@ -534,6 +574,8 @@ VERIFY_POST_HOOKS_JSON=$(gsd_run loop render-hooks verify:post --raw)
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
+**Generic step dispatch:** dispatch every `kind == "step"` hook from `VERIFY_POST_HOOKS_JSON` per @gsd-core/references/loop-hook-dispatch.md (skip silently when none). Each step is advisory and best-effort — honor `onError` and continue. The secure-phase handling below is an additional specialization of one such hook, not a replacement for the generic dispatch.
+
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.
 
 If an active secure-phase step hook exists AND `SECURITY_FILE` is empty, dispatch the registry-provided skill stem:
@@ -633,7 +675,7 @@ All tests passed. Phase {phase} marked complete.
 <step name="scan_phase_artifacts">
 Run phase artifact scan to surface any open items before marking phase verified:
 
-`audit-open` is CJS-only until registered on `gsd-tools.cjs query`:
+`audit-open` is CJS-only until registered on `gsd_run query`:
 
 ```bash
 gsd_run query audit-open --json
@@ -647,9 +689,12 @@ Parse the JSON output. For the CURRENT PHASE ONLY, surface:
 If any are found, display:
 ```
 Phase {N} Artifact Check
-─────────────────────────────────────────────────
+
+---
+
 {list each item with status and file path}
-─────────────────────────────────────────────────
+
+---
 These items are open. Proceed anyway? [Y/n]
 ```
 
@@ -685,9 +730,7 @@ Diagnosis runs automatically - no user prompt. Parallel agents investigate simul
 
 Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► PLANNING FIXES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► PLANNING FIXES
 
 ◆ Spawning planner for gap closure... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
@@ -752,9 +795,7 @@ On return:
 
 Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► VERIFYING FIX PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► VERIFYING FIX PLANS
 
 ◆ Spawning plan checker... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
@@ -858,9 +899,7 @@ Wait for user response.
 **Present completion and next steps:**
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► FIXES READY ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► FIXES READY ✓
 
 **Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
 
@@ -871,7 +910,7 @@ Wait for user response.
 
 Plans verified and ready for execution.
 
-───────────────────────────────────────────────────────────────
+---
 
 ## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
@@ -879,7 +918,7 @@ Plans verified and ready for execution.
 
 `/clear` then `/gsd:execute-phase {phase} --gaps-only`
 
-───────────────────────────────────────────────────────────────
+---
 ```
 </step>
 

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

@@ -65,6 +65,23 @@ const path = require('path');
 const os = require('os');
 const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+
+// Required at module top, alongside the other ./lib requires — NOT behind
+// ensureRuntimeBuild() below. Terminating on a parse/timeout failure must
+// never depend on the gitignored build artifacts this hook self-heals for
+// its own registry lookups (#3911).
+//
+// This guard's outer catch (main(), below) has always exited 0 (fail open):
+// that outer catch only covers payload PARSING failing before applicability
+// could even be determined (malformed stdin JSON, etc.) — the guard's real
+// fail-closed logic (a GSD project whose dispatch-isolation configuration
+// cannot be verified) is handled separately, inside evaluateDispatch/
+// resolveIsolationState, and already returns a 'block' decision through the
+// normal exit-2 path rather than through this catch. So an unparseable
+// payload has nothing to enforce; allowing it preserves today's behavior
+// exactly.
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 // #3582: gsd-core/bin/lib/*.cjs (runtime-name-policy.cjs, capability-registry.cjs
 // below) are tsc build artifacts (ADR-457), gitignored and absent on a raw
 // plugin-marketplace / git-clone install that never ran `npm run build:lib`.
@@ -95,40 +112,40 @@ function parseHarnessFlag(flag) {
   return { param: m[1], value: m[2] };
 }
 
-// ─── #3566: per-install runtime marker ────────────────────────────────────────
+// ─── #3897 rung 2: per-install runtime marker, single canonical owner ────────
 // bin/install.js writes `<install>/gsd-core/.gsd-runtime` for EVERY runtime
 // install (#2297), co-located with VERSION. Unlike `~/.gsd/defaults.json` —
 // which is host-wide and names whichever runtime's install ran LAST, the exact
 // leakage #2840's config.cjs change exists to prevent — the marker describes
 // THIS install, which is the property runtime identity needs on a machine
-// with 2+ runtimes. Mirrors readInstallRuntimeMarker in src/model-resolver.cts
-// (same cache + test-seam shape); this hook cannot import that module without
-// dragging the whole model-resolution stack into a PreToolUse hot path, so the
-// 5-line read lives here against the same sibling-layout assumption the hook's
-// own require('../gsd-core/bin/lib/…') already makes. Epic #3473 B3 owns
-// consolidating every marker reader into one shared seam.
-let _installMarkerCache; // undefined = unread; null = known absent; string = value
-
+// with 2+ runtimes. Previously this hook held its own private reader/cache
+// (one of four #3897 found); it now delegates to the single canonical owner,
+// `src/runtime-slash.cts` (compiled to gsd-core/bin/lib/runtime-slash.cjs),
+// reached through `ensureRuntimeBuild()` like every other compiled-lib require
+// in this file (`scripts/lint-hooks-runtime-build-seam.cjs`).
 function readInstallRuntimeMarker() {
-  if (_installMarkerCache !== undefined) return _installMarkerCache;
   try {
-    const markerPath = path.join(__dirname, '..', 'gsd-core', '.gsd-runtime');
-    const raw = fs.readFileSync(markerPath, 'utf-8').trim();
-    _installMarkerCache = raw || null;
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    return runtimeSlash.readInstallRuntimeMarker();
   } catch {
-    // No marker: dev/source tree, or an install predating #2297 — "no signal
-    // from this rung", never a resolution failure. Falls through to the
-    // defaults rung below.
-    _installMarkerCache = null;
+    // Unbuilt runtime library, or any other failure reaching the canonical
+    // owner — "no signal from this rung" (N4), never a resolution failure.
+    return null;
   }
-  return _installMarkerCache;
 }
 
-// Test seam for the marker rung (the dev/source tree has no marker file, so
-// the read always bottoms out at null there — same seam contract as
-// model-resolver.cts's _setInstallRuntimeMarkerForTests, #2297).
+// Test seam for the marker rung — forwards to the canonical owner's seam so
+// this hook and runtime-slash.cjs always share one cache (#3897 rung 2).
 function _setInstallRuntimeMarkerForTests(value) {
-  _installMarkerCache = value;
+  try {
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    runtimeSlash._setInstallRuntimeMarkerForTests(value);
+  } catch {
+    // Test-only seam; an unbuilt library here means the test itself will fail
+    // downstream, which is a louder and more actionable signal than throwing here.
+  }
 }
 
 /**
@@ -282,18 +299,40 @@ function resolveRegistryIsolation(cwd, configPath) {
 
   if (isolation === 'harness-worktree') {
     let useWorktrees = true;
+    // #3972: the opt-out read shares the ONE owner every other
+    // isolation-deciding surface uses — planning-workspace's
+    // worktreesOptedOut ladder (scoped own-key wins; root inherited under
+    // the GSD_WORKSTREAM gate; strict === false). A flat single-file read
+    // here made a workstream-LOCAL opt-out invisible, so the sentinel-absent
+    // fallback denied a sequential dispatch the config explicitly allowed.
+    // Reached through ensureRuntimeBuild() like every other compiled-lib
+    // require in this file (scripts/lint-hooks-runtime-build-seam.cjs); if
+    // the library is unreachable the flat-root read below remains as the
+    // degraded fallback — today's behavior, never worse.
+    let ladderAnswered = false;
     try {
-      const raw = fs.readFileSync(configPath, 'utf-8');
-      const parsedCfg = JSON.parse(raw);
-      if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
-          typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
-        useWorktrees = false;
-      }
+      ensureRuntimeBuild();
+      const { worktreesOptedOut } = require('../gsd-core/bin/lib/planning-workspace.cjs');
+      useWorktrees = !worktreesOptedOut(cwd);
+      ladderAnswered = true;
     } catch {
-      // Unreadable config already propagated to the outer caller's catch
-      // before this point in practice (resolveRuntimeIdentity reads it
-      // first); tolerate defensively and keep the conservative (enforce)
-      // default rather than silently disabling the guard.
+      // Unbuilt runtime library or a ladder failure — fall through to the
+      // legacy flat-root read (conservative: keep enforcing).
+    }
+    if (!ladderAnswered) {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsedCfg = JSON.parse(raw);
+        if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
+            typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
+          useWorktrees = false;
+        }
+      } catch {
+        // Unreadable config already propagated to the outer caller's catch
+        // before this point in practice (resolveRuntimeIdentity reads it
+        // first); tolerate defensively and keep the conservative (enforce)
+        // default rather than silently disabling the guard.
+      }
     }
     if (!useWorktrees) isolation = 'none';
   }
@@ -476,7 +515,7 @@ function evaluateDispatch(data, { clock = Date } = {}) {
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
 function main() {
   let input = '';
-  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  const stdinTimeout = setTimeout(() => allow(undefined), 3000);
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
   process.stdin.on('end', () => {
@@ -486,18 +525,18 @@ function main() {
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
         const out = { decision: 'block', reason: decision.reason, reason_code: decision.reasonCode };
-        process.stdout.write(JSON.stringify(out));
         // Kimi feeds stderr (not stdout) back to the model on exit 2.
-        process.stderr.write(decision.reason);
-        process.exit(2);
+        deny(out, decision.reason);
       }
-      process.exit(0);
+      allow(undefined);
     } catch {
       // Silent fail — never block valid tool calls due to hook errors
       // (malformed payload, etc.). This is distinct from resolveIsolationState's
       // internal error handling, which DOES deny — this outer catch only
       // covers payload parsing before applicability could even be determined.
-      process.exit(0);
+      // ON_CRASH is declared ALLOW at module top: this preserves today's
+      // exit(0) fail-open behavior exactly (#3911).
+      crash(ON_CRASH, undefined);
     }
   });
 }

package/hooks/dist/gsd-config-reload.js

@@ -20,11 +20,17 @@
 
 const fs = require('fs');
 const path = require('path');
+const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+
+// This hook only injects an advisory config-reload summary; a crash mid-parse
+// must not block the session or the FileChanged event that triggered it — the
+// agent simply keeps using the config context it already had (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 let input = '';
 // Timeout guard: if stdin does not close within 8s exit silently rather than
 // hanging until Claude Code kills the process and reports "hook error".
-const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+const stdinTimeout = setTimeout(() => allow(undefined), 8000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
@@ -42,24 +48,23 @@ process.stdin.on('end', () => {
     // inject spurious additionalContext.
     const basename = path.basename(filePath);
     if (basename !== 'config.json') {
-      process.exit(0);
+      allow(undefined);
     }
     const expectedPath = path.resolve(cwd, '.planning', 'config.json');
     if (path.resolve(filePath) !== expectedPath) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // On unlink (deletion) emit a brief notice and exit
     if (event === 'unlink') {
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was deleted. ' +
             'Falling back to built-in defaults for this session.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Read the updated config file
@@ -68,17 +73,16 @@ process.stdin.on('end', () => {
       const raw = fs.readFileSync(filePath, 'utf8');
       config = JSON.parse(raw);
     } catch (e) {
-      if (e && e.code === 'ENOENT') process.exit(0);
+      if (e && e.code === 'ENOENT') allow(undefined);
       // Malformed JSON — inform the agent without crashing
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was modified but could not be parsed. ' +
             'Check the file for JSON syntax errors.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Build a concise summary of key config fields the agent cares about
@@ -127,7 +131,9 @@ process.stdin.on('end', () => {
       },
     }));
   } catch (e) {
-    // Silent fail — never block the session on a config reload error
-    process.exit(0);
+    // Silent fail — never block the session on a config reload error.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/dist/gsd-context-monitor.js

@@ -22,6 +22,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
+const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+
+// This hook only injects an advisory context-usage warning; it never blocks
+// the tool call it rides in on. A crash here (e.g. a malformed bridge file)
+// must not turn a PostToolUse advisory into a blocked tool call — losing a
+// context warning is far cheaper than stalling the agent's work (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
 const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
@@ -33,7 +40,7 @@ let input = '';
 // Windows/Git Bash, or slow Claude Code piping during large outputs),
 // exit silently instead of hanging until Claude Code kills the process
 // and reports "hook error". See #775, #1162.
-const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+const stdinTimeout = setTimeout(() => allow(undefined), 10000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
@@ -43,14 +50,14 @@ process.stdin.on('end', () => {
     const sessionId = data.session_id;
 
     if (!sessionId) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Reject session IDs that contain path traversal sequences or path separators.
     // session_id is used to construct file paths in /tmp — an unsanitized value
     // could escape the temp directory and read or write arbitrary files.
     if (/[/\\]|\.\./.test(sessionId)) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check if context warnings are disabled via config.
@@ -61,7 +68,7 @@ process.stdin.on('end', () => {
       const configPath = path.join(cwd, '.planning', 'config.json');
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       if (config.hooks?.context_warnings === false) {
-        process.exit(0);
+        allow(undefined);
       }
     } catch (e) {
       // Missing or unparseable config → proceed with defaults (context warnings enabled)
@@ -77,7 +84,7 @@ process.stdin.on('end', () => {
     try {
       metricsRaw = fs.readFileSync(metricsPath, 'utf8');
     } catch (e) {
-      if (e && e.code === 'ENOENT') process.exit(0);
+      if (e && e.code === 'ENOENT') allow(undefined);
       throw e;
     }
     const metrics = JSON.parse(metricsRaw);
@@ -85,7 +92,7 @@ process.stdin.on('end', () => {
 
     // Ignore stale metrics
     if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
-      process.exit(0);
+      allow(undefined);
     }
 
     const remaining = metrics.remaining_percentage;
@@ -93,7 +100,7 @@ process.stdin.on('end', () => {
 
     // No warning needed
     if (remaining > WARNING_THRESHOLD) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Debounce: check if we warned recently
@@ -121,7 +128,7 @@ process.stdin.on('end', () => {
     if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
       // Update counter and exit without warning
       fs.writeFileSync(warnPath, JSON.stringify(warnData));
-      process.exit(0);
+      allow(undefined);
     }
 
     // Reset debounce counter
@@ -208,7 +215,9 @@ process.stdin.on('end', () => {
       process.stdout.write(JSON.stringify(output));
     }
   } catch (e) {
-    // Silent fail -- never block tool execution
-    process.exit(0);
+    // Silent fail -- never block tool execution.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/dist/gsd-cursor-post-tool.js

@@ -22,6 +22,8 @@
 
 'use strict';
 
+const { allow } = require('./lib/hook-exit.js');
+
 const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
 const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
 const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
@@ -29,7 +31,7 @@ const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
 let raw = '';
 const stdinTimeout = setTimeout(() => {
   // Timeout guard: exit silently rather than hanging.
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

package/hooks/dist/gsd-cursor-pre-tool.js

@@ -22,13 +22,15 @@
 
 'use strict';
 
+const { allow } = require('./lib/hook-exit.js');
+
 const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
 const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
 const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
 
 let raw = '';
 const stdinTimeout = setTimeout(() => {
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

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

@@ -23,6 +23,7 @@
 'use strict';
 
 const fs = require('fs');
+const { allow } = require('./lib/hook-exit.js');
 
 const MSG_PRESENT =
   'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
@@ -37,7 +38,7 @@ const { resolveStatePath } = require('./lib/cursor-workspace.js');
 let raw = '';
 const stdinTimeout = setTimeout(() => {
   // Timeout guard: exit silently rather than hanging.
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

package/hooks/dist/gsd-cursor-stop.js

@@ -21,6 +21,7 @@
 'use strict';
 
 const fs = require('fs');
+const { allow } = require('./lib/hook-exit.js');
 
 // Workspace resolution is shared across the Cursor hooks (#2587) — see
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
@@ -29,7 +30,7 @@ const { resolveStatePath } = require('./lib/cursor-workspace.js');
 
 let raw = '';
 const stdinTimeout = setTimeout(() => {
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');