@opengsd/gsd-core 1.13.0 → 1.14.0

package/hooks/gsd-validate-commit.sh

@@ -69,7 +69,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 —
@@ -214,7 +218,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,9 +542,18 @@ 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

package/hooks/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/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/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/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/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,
+};

package/hooks/lib/isolation-sentinel.js

@@ -56,6 +56,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { parseDispatchIdentity } = require('./dispatch-identity.js');
 
 // Isolation modes ADR-1239 declares (mirrors gsd-tools.cjs
 // routeDispatchIsolation / routeRecordDispatchIsolation).
@@ -223,26 +224,40 @@ function readSentinel(cwd, { clock = Date } = {}) {
 }
 
 /**
- * #3045 SECURITY F2: extract the `{plan, phase}` a specific Agent()/Task()
- * dispatch is FOR, from the one place that data is reliably embedded today —
- * the dispatch prompt/description text (`execute-phase.md`'s Agent() block
- * uses the literal shape `description="Execute plan {plan_number} of phase
- * {phase_number}"`, and the prompt body's `<objective>` repeats "Execute plan
- * {plan_number} of phase {phase_number}-{phase_name}." verbatim — the SAME
- * text the orchestrator-worktree EXECUTOR_PROMPT template and Cursor's `task`
- * field carry, since Cursor dispatches the same prompt content). There is no
- * structured per-dispatch kwarg carrying plan/phase identifiers today (#3045
- * would need a larger dispatch-protocol change to add one) — this is
- * therefore a best-effort, NOT a guaranteed, extraction: a dispatch whose
- * text doesn't match the expected shape returns `{ plan: null, phase: null }`
- * and the caller must NOT treat that as a mismatch (see
- * `sentinelAppliesToDispatch`).
+ * #3045 SECURITY F2 / #4594: extract the `{plan, phase}` a specific
+ * Agent()/Task() dispatch is FOR. Variadic — accepts any number of text
+ * sources (short description, full prompt body, etc) and delegates to
+ * `hooks/lib/dispatch-identity.js::parseDispatchIdentity`, the one canonical
+ * owner of both the `[gsd:dispatch phase="…" plan="…"]` marker format and its
+ * prose fallback (see `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md`).
+ *
+ * MARKER-FIRST CONTRACT: producers embed a structured marker carrying the
+ * exact shell values the sentinel itself records (`$PHASE_NUMBER`,
+ * `$plan_id`), so producer and consumer agree by construction, independent
+ * of how the prose reads or whether a model paraphrases the dispatch
+ * sentence. Only when no marker is found anywhere in the supplied texts does
+ * this fall back to scanning for the prose frame "execute plan <token> of
+ * phase <PHASE TOKEN>".
+ *
+ * The prose fallback is now CORRECT-OR-ABSENT rather than possibly-wrong:
+ * the phase token is bounded by the same grammar `src/phase-id.cts` owns
+ * (ADR-2121), so a directory-name slug or trailing punctuation can no longer
+ * leak into the phase value, and the prose plan token is never reported at
+ * all (it lives in a different namespace than the sentinel's phase-prefixed,
+ * slugged `plan_id` — reporting it was the #4594 false-mismatch bug).
+ *
+ * This is still a best-effort, NOT a guaranteed, extraction: a dispatch that
+ * carries neither a marker nor a matching prose frame in ANY supplied text
+ * returns `{ plan: null, phase: null }`, and the caller MUST NEVER treat
+ * that as a mismatch — see `sentinelAppliesToDispatch`, whose whole
+ * contract depends on "missing" and "wrong" being distinguishable.
+ *
+ * Returns only the two-field `{ plan, phase }` shape existing callers
+ * depend on — `parseDispatchIdentity`'s `source` field is discarded here.
  */
-function extractDispatchIdentifiers(text) {
-  if (typeof text !== 'string' || text.length === 0) return { plan: null, phase: null };
-  const m = /execute\s+plan\s+(\S+)\s+of\s+phase\s+(\S+)/i.exec(text);
-  if (!m) return { plan: null, phase: null };
-  return { plan: m[1], phase: m[2] };
+function extractDispatchIdentifiers(...texts) {
+  const { phase, plan } = parseDispatchIdentity(...texts);
+  return { plan, phase };
 }
 
 /**
@@ -265,6 +280,29 @@ function sentinelAppliesToDispatch(sentinel, dispatchIds) {
   return true;
 }
 
+/**
+ * #4594 F3: build the structured "a fresh sentinel was present but did not
+ * apply to this dispatch" descriptor, mirroring the exact comparison
+ * `sentinelAppliesToDispatch` performs. Returns `null` when the sentinel is
+ * absent, stale, malformed, or DOES apply — i.e. exactly when there is
+ * nothing to report as discarded. Otherwise returns the nested
+ * `{ sentinel: {phase, plan}, dispatch: {phase, plan} }` shape, reusing the
+ * `{phase, plan}` pair already flowing through this module end to end rather
+ * than renaming its fields into an ad hoc `sentinelPhase`/`dispatchPlan` bag
+ * (previously rebuilt identically at two call sites in the guard hooks).
+ */
+function buildSentinelDiscard(sentinel, dispatchIds) {
+  if (!sentinel || !sentinel.present || sentinel.stale) return null;
+  if (sentinelAppliesToDispatch(sentinel, dispatchIds)) return null;
+  return {
+    sentinel: { phase: sentinel.phase ?? null, plan: sentinel.plan ?? null },
+    dispatch: {
+      phase: dispatchIds ? (dispatchIds.phase ?? null) : null,
+      plan: dispatchIds ? (dispatchIds.plan ?? null) : null,
+    },
+  };
+}
+
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
@@ -274,4 +312,5 @@ module.exports = {
   readSentinel,
   extractDispatchIdentifiers,
   sentinelAppliesToDispatch,
+  buildSentinelDiscard,
 };