@opengsd/gsd-core 1.13.0 → 1.15.0

package/hooks/dist/gsd-validate-commit.sh

@@ -16,6 +16,21 @@ set -euo pipefail
 # Idempotent and failure-proof by construction: unset vars expand to "" (a
 # no-op rm -f target), and `|| true` guarantees the trap itself never changes
 # the script's exit status.
+# Subprocess exit statuses, pre-initialised so they can never be inherited from
+# the ambient environment. Each is captured as `... || VAR=$?`, which assigns
+# ONLY on the failure branch; on success the variable keeps whatever it already
+# held, and `${VAR:-0}` defaults only when unset or empty. So an EXPORTED
+# CONFIG_STATUS / CMD_STATUS / CLASSIFY_STATUS — from a CI wrapper, a .envrc, or
+# another hook — survived into the success path and was read as "the subprocess
+# failed". Measured: `CLASSIFY_STATUS=3 git commit -m "nope: bad"` printed
+# "validator disabled for this call" and exited 0, silently accepting a
+# non-conforming commit. Same for CONFIG_STATUS and CMD_STATUS. Found by the
+# security review of #4429; the gate is fail-open by design on a genuine
+# subprocess failure (#3838), which is exactly what made this bypass quiet.
+CONFIG_STATUS=0
+CMD_STATUS=0
+CLASSIFY_STATUS=0
+
 ENABLED_ERR=""
 CMD_ERR=""
 CLASSIFY_ERR=""
@@ -61,6 +76,12 @@ if [ -f .planning/config.json ]; then
       process.exit(3);
     }
   " 2>"$ENABLED_ERR") || CONFIG_STATUS=$?
+  # Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+  # assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+  # already held — and an EXPORTED variable of this name is inherited from the
+  # ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+  # `CONFIG_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+  # silently accepting a non-conforming commit. Found by review of #4429.
   CONFIG_STATUS=${CONFIG_STATUS:-0}
   if [ "$CONFIG_STATUS" != "0" ]; then
     # Could not determine the opt-in flag at all (node missing, JSON parse
@@ -69,7 +90,11 @@ if [ -f .planning/config.json ]; then
     echo "gsd-validate-commit.sh: could not read .planning/config.json (opt-in check) — validator disabled for this call. $(cat "$ENABLED_ERR")" >&2
     exit 0
   fi
-  ENABLED=$(printf '%s\n' "$CONFIG_OUT" | head -1)
+  # Pure parameter expansion, not `printf ... | head -1`: same SIGPIPE race
+  # class as the SUBJECT extraction below (`echo "$MSG" | head -1`) — CONFIG_OUT
+  # is multi-line whenever extra commit types are configured, and `head -1`
+  # closing early can SIGPIPE `printf` under `set -euo pipefail`.
+  ENABLED="${CONFIG_OUT%%$'\n'*}"
   if [ "$ENABLED" != "1" ]; then exit 0; fi
   # Remaining lines (if any) are the sanitized, deduped configured commit
   # types beyond the 10 built-ins (#3811). Read into a bash-3.2-safe array —
@@ -99,6 +124,12 @@ CMD=$(echo "$INPUT" | node -e "
     }
   });
 " 2>"$CMD_ERR") || CMD_STATUS=$?
+# Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+# assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+# already held — and an EXPORTED variable of this name is inherited from the
+# ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+# `CMD_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+# silently accepting a non-conforming commit. Found by review of #4429.
 CMD_STATUS=${CMD_STATUS:-0}
 if [ "$CMD_STATUS" != "0" ]; then
   # Could not extract tool_input.command at all (node missing, malformed
@@ -123,6 +154,12 @@ GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
     process.exit(3);
   }
 " "$CMD" 2>"$CLASSIFY_ERR" || CLASSIFY_STATUS=$?
+# Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+# assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+# already held — and an EXPORTED variable of this name is inherited from the
+# ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+# `CLASSIFY_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+# silently accepting a non-conforming commit. Found by review of #4429.
 CLASSIFY_STATUS=${CLASSIFY_STATUS:-0}
 if [ "$CLASSIFY_STATUS" != "0" ] && [ "$CLASSIFY_STATUS" != "1" ]; then
   # 0 = is a git commit (validate below); 1 = genuinely not a git commit
@@ -214,7 +251,24 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       # the message — the window a guard must use when the token it scans for
       # is also legal English inside a commit message, but may legally appear
       # on EITHER side of the message on the command line.
-      MSG_SUFFIX="${CMD#*"$MSG_MATCH"}"
+      # Indexed, not searched (#4492). `${CMD#*"$MSG_MATCH"}` is quadratic in
+      # the message: bash walks every prefix length and compares the whole
+      # matched literal at each one, and MSG_MATCH is BASH_REMATCH[0] — the
+      # entire `-m "..."` — so the cost grows with the thing being scanned.
+      # Measured on the path EVERY commit takes (conforming and non-conforming
+      # cost the same): 10.0 s at a 64 KB message, 22.0 s at 96 KB, 30.2 s at
+      # 112 KB. Sizes stop there deliberately — a single argument above Linux's
+      # MAX_ARG_STRLEN (131072 on a 4 KB-page kernel) never reaches this code
+      # at all, because execve fails and the hook fails open, so a larger
+      # "measurement" would be timing the wrong thing.
+      #
+      # MSG_PREFIX above has already located the match, so the suffix is
+      # arithmetic rather than a search: skip the prefix and the match. This
+      # removes the quadratic SEARCH; the expansion still counts characters and
+      # materialises a substring, so it is linear in the command, not O(1).
+      # Same first-occurrence assumption both expansions here always made —
+      # MSG_MATCH is a literal substring of CMD by construction.
+      MSG_SUFFIX="${CMD:$(( ${#MSG_PREFIX} + ${#MSG_MATCH} ))}"
       # LINE CONTINUATIONS ARE NOT SEPARATORS (review of #3816, rounds 8 and 9).
       # `git commit \` newline `  -m "$(cat <<'EOF' …` is an ordinary way to
       # spread an invocation over lines, and every guard below reads a newline in
@@ -521,13 +575,22 @@ 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=$(echo "$MSG" | head -1)
+      " 2>/dev/null) || SUBJECT="${MSG%%$'\n'*}"
     else
-      SUBJECT=$(echo "$MSG" | head -1)
+      # Pure parameter expansion, 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
+      # `head -1` for single-line, multi-line, and trailing-newline input.
+      SUBJECT="${MSG%%$'\n'*}"
     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
-    # regex alternation and the human-readable error text below are derived
+    # membership test and the human-readable error text below are derived
     # from this ONE array — no hand-synced second copy.
     #
     # The `"${EXTRA_COMMIT_TYPES[@]+"${EXTRA_COMMIT_TYPES[@]}"}"` form (not
@@ -538,7 +601,6 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
     # /bin/bash 3.2.57 on macOS. The `${arr[@]+word}` form is the
     # nounset-safe idiom for "expand if set, empty otherwise" on empty arrays.
     COMMIT_TYPES=("${BUILTIN_COMMIT_TYPES[@]}" "${EXTRA_COMMIT_TYPES[@]+"${EXTRA_COMMIT_TYPES[@]}"}")
-    COMMIT_TYPE_ALT=$(IFS='|'; echo "${COMMIT_TYPES[*]}")
     COMMIT_TYPE_LIST=$(printf '%s, ' "${COMMIT_TYPES[@]}")
     COMMIT_TYPE_LIST="${COMMIT_TYPE_LIST%, }"
     # Typed `valid_types` array (#3811 review finding): CONTRIBUTING.md bans
@@ -550,8 +612,35 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
     # or `\`.
     COMMIT_TYPES_JSON=$(printf '"%s",' "${COMMIT_TYPES[@]}")
     COMMIT_TYPES_JSON="[${COMMIT_TYPES_JSON%,}]"
-    # Validate Conventional Commits format
-    if ! [[ "$SUBJECT" =~ ^($COMMIT_TYPE_ALT)(\(.+\))?:[[:space:]].+ ]]; then
+    # Validate Conventional Commits format.
+    #
+    # #4429: do NOT build `^(type1|type2|...)` out of COMMIT_TYPES. That
+    # alternation grows with the CONFIGURED list, and how large a pattern can be
+    # compiled is a property of the platform's regex engine. bash 3.2.57 / BSD
+    # libc (macOS, this file's stated target) caps it at 64 KiB - bisected: a
+    # 65504-byte alternation compiles, 65515 fails. bash 5.2 / glibc has no
+    # reachable cap, so this half never bit Linux. Past a cap `[[ =~ ]]`
+    # returns 2, and `if !` cannot tell a COMPILE ERROR from "the subject does
+    # not conform" - so a valid `feat(auth): ...` was blocked with
+    # CONVENTIONAL_COMMITS_VIOLATION while `feat` sat in its own valid_types.
+    #
+    # Match the SHAPE with a fixed-size pattern, then test membership against
+    # the array. The regex no longer depends on how many types are configured,
+    # and the loop adds no subprocess or pipe (the #4429 hazard this file
+    # already avoids elsewhere). The character class is exactly the safe-token
+    # filter `^[a-z][a-z0-9-]*$` applied above, so it captures every type that
+    # can legally reach COMMIT_TYPES and no token that cannot.
+    SUBJECT_TYPE=''
+    if [[ "$SUBJECT" =~ ^([a-z][a-z0-9-]*)(\(.+\))?:[[:space:]].+ ]]; then
+      SUBJECT_TYPE="${BASH_REMATCH[1]}"
+    fi
+    COMMIT_TYPE_OK=0
+    if [ -n "$SUBJECT_TYPE" ]; then
+      for _known_type in "${COMMIT_TYPES[@]}"; do
+        if [ "$_known_type" = "$SUBJECT_TYPE" ]; then COMMIT_TYPE_OK=1; break; fi
+      done
+    fi
+    if [ "$COMMIT_TYPE_OK" -ne 1 ]; then
       # Emit typed `code` and `valid_types` fields alongside `reason` (#2974,
       # #3811). Tests assert on the stable code string and the typed array;
       # the reason is the human-readable copy, never grepped by tests.

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

@@ -163,17 +163,37 @@ process.stdin.on('end', () => {
     // returns a path containing .git/worktrees/ as a component.
     // In the main repo or a submodule it returns .git (or a path without /worktrees/).
     // This approach works even when cwd is a subdirectory of the worktree.
-    const gitDirResult = git(['rev-parse', '--git-dir'], cwd);
+    // Combined into one spawn — git rev-parse accepts multiple query flags in
+    // one invocation and prints one line of output per flag, in the exact
+    // order given, reducing this guard's worst-case subprocess count under
+    // CI/load contention (three spawns collapse into one). `--abbrev-ref HEAD`
+    // is used instead of `symbolic-ref --short HEAD` because it is combinable
+    // (a single `rev-parse` call) and behaviorally equivalent for this guard's
+    // branch-acceptance check, including on detached HEAD: `--abbrev-ref`
+    // returns the literal string `HEAD` there (exit 0), which the acceptance
+    // regex below also rejects — the same guard outcome as symbolic-ref's
+    // exit-128/empty-stdout failure. Do not change any timeout value as part
+    // of this change, only the spawn count.
+    const combinedResult = git(['rev-parse', '--git-dir', '--abbrev-ref', 'HEAD', '--show-toplevel'], cwd);
     // #3911: a timeout/spawn-failure result is indistinguishable from a clean
     // "not a git repo" answer by status/stdout alone — reportIfUndetermined
     // is a no-op on a genuine negative and only fires the diagnostic when the
     // probe itself could not run. The allow() below is UNCHANGED either way.
-    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --git-dir', gitDirResult);
-    if (gitDirResult.status !== 0 || !gitDirResult.stdout) {
+    reportIfUndetermined(
+      'gsd-worktree-path-guard',
+      'git rev-parse --git-dir --abbrev-ref HEAD --show-toplevel',
+      combinedResult
+    );
+    if (combinedResult.status !== 0 || !combinedResult.stdout) {
       allow(undefined); // not a git repo — pass through
     }
 
-    const gitDir = gitDirResult.stdout.trim();
+    const combinedLines = combinedResult.stdout.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+    if (combinedLines.length < 3) {
+      allow(undefined); // malformed/short output — can't determine root, fail open
+    }
+    const [gitDir, branch, wtTopRaw] = combinedLines;
+
     // A linked worktree's --git-dir contains .git/worktrees/ as a path component
     const isLinkedWorktree = /[/\\]\.git[/\\]worktrees[/\\]/.test(gitDir);
     if (!isLinkedWorktree) {
@@ -186,23 +206,14 @@ process.stdin.on('end', () => {
     // created linked worktree (plain non-GSD work, e.g. Claude Code plan-mode) is
     // on the user's own branch, so the guard must be a no-op there. Detached HEAD
     // / error → not GSD-managed → no-op.
-    const branchResult = git(['symbolic-ref', '--short', 'HEAD'], cwd);
-    reportIfUndetermined('gsd-worktree-path-guard', 'git symbolic-ref --short HEAD', branchResult);
-    const branch = branchResult.status === 0 && branchResult.stdout ? branchResult.stdout.trim() : '';
     // #3021: accept worktree-wf_<runid>-<n> branches (Workflow backend's naming).
     if (!/^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/.test(branch)) {
       allow(undefined); // not a GSD-managed executor worktree — no-op
     }
 
-    // Get the raw --show-toplevel output for the worktree (cwd).
+    // wtTopRaw: the raw --show-toplevel output for the worktree (cwd).
     // We keep it raw (not path.resolve'd) to compare directly with the
     // file's toplevel — same git binary, same format, no normalization needed.
-    const wtTopResult = git(['rev-parse', '--show-toplevel'], cwd);
-    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --show-toplevel (worktree cwd)', wtTopResult);
-    if (wtTopResult.status !== 0 || !wtTopResult.stdout) {
-      allow(undefined); // can't determine root — fail open
-    }
-    const wtTopRaw = wtTopResult.stdout.trim();
 
     // #2595 (review Major 3): read the field TYPED. `?.file_path || ''` let a
     // non-string through — `[]` and `{}` are truthy, so they survived the

package/hooks/dist/gsd-write-guard.js

@@ -105,10 +105,37 @@ const FLOOR_LINES = 40;
 // default to, a differently-cased path is the SAME real file — a Write to
 // '.planning/roadmap.md' clobbers ROADMAP.md while a case-sensitive match
 // waves it through.
+// #4455: workstream-scoped (and optionally project-scoped) variants —
+// planningDir(cwd) (src/planning-workspace.cts) resolves to
+// `.planning/[<project>/]workstreams/<ws>/...` whenever GSD_WORKSTREAM is
+// set. Before this, none of these three root-only patterns matched a
+// workstream-scoped target at all, so the ENTIRE guard (not just the
+// sentinel step — the shrink-ratio check too) silently never engaged for a
+// workstream-scoped ROADMAP.md/STATE.md/milestone-archive Write: exactly
+// the catastrophic-shrink scenario this file exists to stop, unguarded
+// under an active workstream. consumeSentinelFor's own `.planning`
+// derivation below is unaffected by this addition — it locates the single
+// outer `.planning` segment regardless of what's nested inside it, which is
+// also where the workflow's sentinel `printf` already writes, so no change
+// was needed there.
+//
+// Same gap exists one level up: planningDir(cwd) ALSO resolves to
+// `.planning/<project>/...` when GSD_PROJECT is set with NO GSD_WORKSTREAM
+// (project-only mode — the two env vars are independent; see planningDir's
+// own body). None of the patterns above cover that shape either. Found
+// during #4455's own review pass (same root cause, one more path variant)
+// — fixed in the same change rather than deferred, since it is the
+// identical defect class this PR already exists to close.
 const CURATED_PATTERNS = [
   /(?:^|\/)\.planning\/ROADMAP\.md$/i,
   /(?:^|\/)\.planning\/STATE\.md$/i,
   /(?:^|\/)\.planning\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
 ];
 
 // Count logical lines, ignoring a single trailing newline so that
@@ -156,7 +183,25 @@ function consumeSentinelFor(filePath, normalized) {
     // Path-bound: the token names exactly one file, resolved against the
     // .planning/ dir's parent (repo root) — same case-insensitive stance as
     // the curated match itself.
-    const namedNorm = path.resolve(path.join(planningDir, '..'), token).replace(/\\/g, '/').toLowerCase();
+    let namedPath = path.resolve(path.join(planningDir, '..'), token);
+    // Symmetry with the caller's own resolution (#4455 CI finding, macOS
+    // full-test shard): `filePath`/`normalized` were already realpath-resolved
+    // before this function was called (round 9 Minor 1's symlink-before-match
+    // fix), but `token` — typically an already-absolute path composed by the
+    // workflow's own init.* fields — was compared WITHOUT that same
+    // resolution. Wherever cwd sits under a symlink (macOS's /var ->
+    // /private/var is the common case, since that's exactly what os.tmpdir()
+    // resolves through, but any symlinked project/worktree checkout hits the
+    // same asymmetry), the token names the lexical path while `normalized`
+    // names the realpath — a validly-armed sentinel then never matches, and a
+    // legitimate milestone-reset Write stays incorrectly blocked. The named
+    // file is already known to exist (the caller only reaches this function
+    // after successfully reading it), so realpath is expected to succeed;
+    // keep the lexical path on failure, matching the caller's own fallback.
+    try {
+      namedPath = fs.realpathSync(namedPath);
+    } catch { /* keep the lexical path */ }
+    const namedNorm = namedPath.replace(/\\/g, '/').toLowerCase();
     if (namedNorm !== normalized.toLowerCase()) {
       return false; // armed for a different file — leave it for that write
     }

package/hooks/dist/lib/dispatch-identity.js

@@ -0,0 +1,187 @@
+'use strict';
+// hooks/lib/dispatch-identity.js — the ONE canonical owner of the
+// `[gsd:dispatch phase="…" plan="…"]` marker format and its prose fallback
+// (#4594, epic #4630 Phase 1). See
+// `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md` for the full
+// rationale (behavior table, negative space, rejected alternatives).
+//
+// COLD-LOAD CONSTRAINT (load-bearing, not a style choice): this module MUST
+// require NOTHING — no `fs`, no `path`, and above all nothing under
+// `gsd-core/bin/lib/` or `ensure-runtime-build`. The guard hooks that consume
+// this module must load on a raw plugin-marketplace install where the
+// compiled lib is absent and the self-healing build seam has not run — a
+// hook that dies at module load is worse than one carrying a mirror. See
+// `tests/dispatch-identity.test.cjs`'s "cold tree load" test, which asserts
+// this by monkeypatching `Module._load` to throw on exactly those paths.
+
+// DISPATCH_PHASE_TOKEN_SOURCE is a DELIBERATE MIRROR of
+// `CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE` in `src/phase-id.cts`
+// (ADR-2121 owns the phase-token grammar; `gsd-core/bin/lib/phase-id.cjs` is
+// its compiled form). It cannot be an `require()`-based import: importing the
+// compiled lib here would violate the cold-load constraint above (either a
+// direct dependency on `gsd-core/bin/lib/` or a forced self-heal via
+// `ensure-runtime-build`), which is exactly the failure mode this module
+// exists to avoid for the guard hooks that consume it.
+//
+// Because this is a hand-copied mirror and not a shared reference, a
+// hand-edited grammar change on one side that is not mirrored on the other
+// does NOT fail loudly — both sides remain independently valid regex
+// sources, so the failure mode is a silent, invisible non-match (a dispatch
+// whose phase token the two owners now parse differently), never a thrown
+// error. `tests/dispatch-identity.test.cjs`'s "templates: prose token source
+// matches the case-flexible phase-id grammar" test pins this string equal to
+// the compiled source at test time specifically to turn that silent drift
+// into a loud, in-CI failure.
+const DISPATCH_PHASE_TOKEN_SOURCE = '\\d+[A-Za-z]?(?:\\.\\d+)*';
+
+// Bounded marker grammar: `[gsd:dispatch key="value" key2="value2"]`.
+// - Key names bounded to {1,31} — no key we emit or expect is anywhere near
+//   that long; this is purely a backstop against pathological input.
+// - Values bounded to {0,200} and forbidden from containing `"`, `]`, or any
+//   control character that could either close the marker early or forge a
+//   sibling key — enforced structurally by the negated character class, not
+//   by a separate validation pass.
+// Global flag so `findMarker` can scan forward through a large prompt.
+const MARKER_RE = /\[gsd:dispatch((?:\s+[A-Za-z][A-Za-z0-9_-]{0,31}="[^"\]\r\n]{0,200}")*)\s*\]/g;
+const MARKER_KV_RE = /([A-Za-z][A-Za-z0-9_-]{0,31})="([^"\]\r\n]{0,200})"/g;
+
+// Prose fallback frame: `execute plan <token> of phase <PHASE TOKEN>`.
+// - Case-insensitive, `\s+` throughout so CRLF (and any run of whitespace)
+//   parses identically to LF.
+// - The plan token is bounded (`\S{1,80}`) but its VALUE is deliberately
+//   discarded by the caller (see `parseDispatchIdentity` below) — captured
+//   only so the phase token can be anchored correctly after it.
+// - The phase token is bounded by `DISPATCH_PHASE_TOKEN_SOURCE`, replacing
+//   the old greedy `(\S+)`, so a directory-name suffix (`-auth`) or a
+//   sentence-terminating period is never swept into the token.
+const PROSE_RE = new RegExp(
+  `execute\\s+plan\\s+(\\S{1,80})\\s+of\\s+phase\\s+(${DISPATCH_PHASE_TOKEN_SOURCE})`,
+  'i',
+);
+
+/**
+ * Render the `[gsd:dispatch phase="…" plan="…"]` marker for a producer to
+ * embed verbatim in a dispatch description/prompt. Never throws.
+ *
+ * Emits only keys whose value is a non-empty string not containing `"`, `]`,
+ * `\r`, or `\n` — such a value is UNUSABLE and that key is omitted entirely,
+ * because embedding it could close the marker early and forge a second,
+ * attacker-controlled field. Key order is always `phase` then `plan`.
+ * Returns `''` when neither key is usable (nothing worth emitting).
+ */
+function renderDispatchIdentityMarker(input) {
+  const value = input && typeof input === 'object' ? input : {};
+  const parts = [];
+  for (const key of ['phase', 'plan']) {
+    const v = value[key];
+    if (typeof v === 'string' && v.length > 0 && !/["\]\r\n]/.test(v)) {
+      parts.push(`${key}="${v}"`);
+    }
+  }
+  if (parts.length === 0) return '';
+  return `[gsd:dispatch ${parts.join(' ')}]`;
+}
+
+function emptyResult() {
+  return { phase: null, plan: null, source: null };
+}
+
+/**
+ * Scan `texts` in order for the first well-formed marker that yields at
+ * least one recognized key (`phase` and/or `plan`). Returns `{ phase, plan }`
+ * (one of the two possibly null, never both) or `null` if no QUALIFYING
+ * marker was found in any text. Unrecognized keys inside a marker are
+ * ignored (forward compatibility — a later `run=`/`wave=` key must not break
+ * a deployed parser).
+ *
+ * #4594 F1 fix: a marker that matches `MARKER_RE` but carries neither
+ * `phase=` nor `plan=` (e.g. only unrecognized keys, or an empty kv block)
+ * is NOT treated as "found" — it is skipped and scanning continues (later
+ * markers in the same text, then subsequent texts), falling through to the
+ * prose fallback if nothing qualifying turns up. Without this, prompt text
+ * that merely CONTAINS the literal marker syntax with no usable identifiers
+ * silently suppressed the prose fallback entirely, since the old
+ * implementation returned on the first syntactic match regardless of
+ * content.
+ */
+function findMarker(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    MARKER_RE.lastIndex = 0;
+    let match;
+    while ((match = MARKER_RE.exec(text)) !== null) {
+      const kvBlock = match[1] || '';
+      let phase = null;
+      let plan = null;
+      MARKER_KV_RE.lastIndex = 0;
+      let kv;
+      while ((kv = MARKER_KV_RE.exec(kvBlock)) !== null) {
+        const [, key, val] = kv;
+        if (key === 'phase' && phase === null) phase = val;
+        else if (key === 'plan' && plan === null) plan = val;
+      }
+      if (phase === null && plan === null) continue;
+      return { phase, plan };
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan `texts` in order for the first `execute plan <token> of phase
+ * <PHASE TOKEN>` frame. Returns `{ phase }` or `null`.
+ *
+ * The prose fallback returns `plan: null` DELIBERATELY (enforced by the
+ * caller, not here): the prose plan token (e.g. `02`) is a bare in-phase
+ * plan number, a different namespace from the sentinel's `plan_id` (e.g.
+ * `03-02-hardening`, which is phase-prefixed AND slugged). Reporting the
+ * prose plan token as the parsed `plan` is exactly the false-mismatch bug
+ * this module exists to fix — an absent value is honestly "cannot compare",
+ * while a wrong value silently forges a mismatch on every dispatch. Do not
+ * "fix" this by threading the plan token through — that was the bug.
+ */
+function findProse(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    const match = PROSE_RE.exec(text);
+    if (match) {
+      return { phase: match[2] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse dispatch identity out of one or more texts (a short description, a
+ * full prompt body, etc). Never throws for any input type; non-string
+ * entries are skipped.
+ *
+ * Pass 1: scan all texts in order for a well-formed marker; the first one
+ * wins outright (marker beats prose even if prose appears earlier in the
+ * same text — see the design doc's row 8).
+ * Pass 2 (only if no marker was found anywhere): scan all texts in order for
+ * the prose frame; the first match wins. `plan` is always `null` from this
+ * path (see `findProse`'s doc comment).
+ *
+ * Returns `{ phase, plan, source }` where `source` is `'marker' | 'prose' |
+ * null`.
+ */
+function parseDispatchIdentity(...texts) {
+  const marker = findMarker(texts);
+  if (marker) {
+    return { phase: marker.phase, plan: marker.plan, source: 'marker' };
+  }
+
+  const prose = findProse(texts);
+  if (prose) {
+    return { phase: prose.phase, plan: null, source: 'prose' };
+  }
+
+  return emptyResult();
+}
+
+module.exports = {
+  DISPATCH_PHASE_TOKEN_SOURCE,
+  renderDispatchIdentityMarker,
+  parseDispatchIdentity,
+};

package/hooks/dist/lib/filename-classification.js

@@ -0,0 +1,64 @@
+'use strict';
+// hooks/lib/filename-classification.js — hand-written, NOT generated. One
+// tiny, deliberately-named filename slicer.
+//
+// WHY this exists: issue #4580 was caused by comparing "everything after the
+// `.env.` prefix" — a multi-segment token like `local.example` — against a
+// set whose members are FINAL EXTENSIONS (`example`). `.env.local.example`
+// was classified by its full `local.example` tail, which is not in a set
+// built from bare extensions, so the comparison silently failed. This module
+// deliberately exposes ONLY the final-extension answer so the wrong token
+// can't be picked by accident at a call site. The "everything after the
+// first dot" form is intentionally NOT exported: no caller needs it, and an
+// unused export is dead code.
+
+/**
+ * The segment after the LAST dot in `name`. A string with no dot IS its own
+ * final extension. Inert on non-strings/empty input: never throws, returns
+ * ''.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function finalExtension(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  const i = name.lastIndexOf('.');
+  return i === -1 ? name : name.slice(i + 1);
+}
+
+/**
+ * Strips ALL trailing dots and spaces from `name`, repeatedly, from the end
+ * of the basename.
+ *
+ * WHY: Win32 strips trailing dots and trailing spaces from each path
+ * component when resolving a filesystem path — `.env.`, `.env..`, `.env `,
+ * and `.env. ` all resolve to the same on-disk file as `.env` on Windows.
+ * These are therefore ALIASES for the protected name, not distinct names,
+ * and a guard that classifies the literal string without normalizing first
+ * can be bypassed by any of them. This is not cosmetic tidying — it closes
+ * that Windows path-alias bypass.
+ *
+ * This runs UNCONDITIONALLY on every host platform (macOS, Linux, Windows),
+ * not only when actually running on Windows: the guard must behave
+ * identically everywhere, and a name is judged by what Win32 would resolve
+ * it to, regardless of what OS the hook happens to run on.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function normalizeWindowsBasename(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  let end = name.length;
+  while (end > 0 && (name[end - 1] === '.' || name[end - 1] === ' ')) end--;
+  return name.slice(0, end);
+}
+
+// Last `/`- or `\`-separated segment, ignoring trailing separators. A string
+// with no separator IS its own last segment.
+function lastSegment(tok) {
+  const s = tok.replace(/[\\/]+$/, '');
+  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
+  return i === -1 ? s : s.slice(i + 1);
+}
+
+module.exports = { finalExtension, normalizeWindowsBasename, lastSegment };

package/hooks/dist/lib/isolation-deny-reason.js

@@ -36,4 +36,56 @@ const REASON_CODE = Object.freeze({
   NOT_ISOLATED_WORKTREE: 'not_isolated_worktree',
 });
 
-module.exports = { REASON_CODE };
+// #4594 row 15 / F2: values interpolated into a deny reason (sentinel/dispatch
+// phase and plan) come from a sentinel file on disk and, transitively, from
+// model-authored prompt text, neither of which is trusted — bound length and
+// strip control characters/newlines so a crafted value cannot forge extra
+// lines or otherwise inject content into the guard's stdout/stderr message
+// (same discipline as escaping an untrusted token before embedding it in a
+// message, e.g. phase-plan-index's `depends_on` warning).
+//
+// Originally duplicated byte-for-byte in hooks/gsd-agent-isolation-guard.js
+// and hooks/gsd-cursor-subagent-start.js (#4594 F2 review finding) — both
+// hooks already require this dependency-free module, so there is no
+// cold-load justification for the duplication the way there is for
+// hooks/lib/dispatch-identity.js's grammar mirror. Moved here as the single
+// owner; both hooks now import it.
+const REASON_INTERPOLATION_MAX_LEN = 64;
+
+// F6: also strip Unicode line/paragraph separators (U+2028/U+2029) and the
+// bidi-override/isolate control characters (U+202A-U+202E, U+2066-U+2069) —
+// none of these are in `[\x00-\x1f\x7f]`, so a crafted sentinel or dispatch
+// value carrying them could still visually reflow the deny message onto a
+// new line or reverse/hide part of it despite the ASCII control-char strip.
+const REASON_UNSAFE_CHARS_RE = new RegExp(
+  // eslint-disable-next-line no-control-regex -- deliberately stripping control chars/newlines
+  '[\\x00-\\x1f\\x7f\\u2028\\u2029\\u202a-\\u202e\\u2066-\\u2069]',
+  'g',
+);
+
+function sanitizeForReason(value) {
+  if (typeof value !== 'string' || value.length === 0) return '(none)';
+  const stripped = value.replace(REASON_UNSAFE_CHARS_RE, '');
+  return stripped.length > REASON_INTERPOLATION_MAX_LEN
+    ? `${stripped.slice(0, REASON_INTERPOLATION_MAX_LEN)}…`
+    : stripped;
+}
+
+function describeSentinelDiscard(sentinelDiscarded) {
+  const sentinelPhase = sanitizeForReason(sentinelDiscarded.sentinel.phase);
+  const sentinelPlan = sanitizeForReason(sentinelDiscarded.sentinel.plan);
+  const dispatchPhase = sanitizeForReason(sentinelDiscarded.dispatch.phase);
+  const dispatchPlan = sanitizeForReason(sentinelDiscarded.dispatch.plan);
+  return (
+    ` A fresh dispatch-isolation sentinel was present but did not apply to this dispatch ` +
+    `(sentinel phase="${sentinelPhase}" plan="${sentinelPlan}"; dispatch phase="${dispatchPhase}" ` +
+    `plan="${dispatchPlan}"), so it was not consulted.`
+  );
+}
+
+module.exports = {
+  REASON_CODE,
+  REASON_INTERPOLATION_MAX_LEN,
+  sanitizeForReason,
+  describeSentinelDiscard,
+};