session-orchestrator 3.16.0 → 3.19.0

package/hooks/_lib/guard-source-loader.mjs

@@ -0,0 +1,467 @@
+/**
+ * guard-source-loader.mjs — degradation-VISIBLE module loading for deny-capable hooks.
+ *
+ * ## The defect this closes (#992)
+ *
+ * `hooks/hooks.json` runs `sh run-node.sh <hook>.mjs`, which `exec node "$@"`.
+ * A deny-capable hook that STATICALLY imports a repo module inherits that
+ * module's parse failure at ESM LINK time — before the first statement of the
+ * hook body runs. Consequences, all measured:
+ *
+ *   - the hook's own `main().catch(...)` handler is structurally unreachable
+ *     (it only covers runtime errors inside `main()`),
+ *   - node terminates with EXIT 1, **stdout 0 bytes**, stderr = a SyntaxError
+ *     stack trace.
+ *
+ * Under the exit-0 PreToolUse protocol (#906) the exit code no longer carries a
+ * decision: ALLOW is `exit 0` + empty stdout, DENY is `exit 0` + exactly one
+ * `hookSpecificOutput` line. A crashed hook produces 0 bytes on stdout and is
+ * therefore, ON THE ONLY DECISION-BEARING CHANNEL, indistinguishable from an
+ * explicit `emitAllow()`. `git reset --hard` runs through. One broken
+ * `scripts/lib/command-blocker.mjs` silently disarms 4 of the 7 deny-capable
+ * hooks at once (destructive-guard, enforce-scope, enforce-commands,
+ * sessions-ledger-guard) — Bash *and* Edit/Write enforcement.
+ *
+ * ## The two parts, and why the banner is the base
+ *
+ * 1. **Loud once-per-session banner on EVERY load failure.** The damage was not
+ *    "no fallback", it was an *invisible* outage: an ambiguous harness error
+ *    line that wave agents read as a crash rather than a policy block, and
+ *    began routing around. The banner therefore names the CONSEQUENCE ("guard
+ *    INACTIVE" / "running against HEAD, not your working tree"), not just a
+ *    file path.
+ * 2. **`git show HEAD:<path>` fallback — for `command-blocker.mjs` ONLY.** That
+ *    module is dependency-free (its single import is `node:path`) and hence
+ *    `data:`-URL loadable. Deliberately NOT generalised to the guard's other 6
+ *    repo imports: those were never audited for RELATIVE imports, which a
+ *    `data:` URL cannot resolve — that would need its own recursive resolver.
+ *    For those modules part 1 (banner) stands alone.
+ *
+ * **The coupling is mandatory: the fallback must never fire silently.** A
+ * successful HEAD fallback banners too ("running against HEAD, not the working
+ * tree"), otherwise a visible hole is traded for an invisible semantic drift.
+ *
+ * **The HEAD fallback presupposes a git checkout.** It shells out to
+ * `git show HEAD:<path>` in the PLUGIN ROOT (not the project dir). For an
+ * npm-installed plugin — or any tarball/vendored copy without a `.git` — that
+ * command fails by construction, so half of this module is structurally
+ * unavailable there: EVERY load failure degrades straight to the GUARD INACTIVE
+ * banner below. That is the designed fail-loud direction, not a regression, but
+ * it means the banner is the ONLY protection npm consumers get.
+ *
+ * ## Why the marker is not a mute switch (post-#992 hardening)
+ *
+ * The once-per-session throttle used to key on the mere EXISTENCE of a
+ * predictably-named tmp file, and it gated BOTH banner classes. Measured: an
+ * agent could `touch` that path (not a destructive command), then append a
+ * syntax error to a `scripts/lib/` module (not on any redirect denylist) and the
+ * total-outage banner went silent while the decision channel said ALLOW —
+ * strictly worse than the pre-#992 crash, which at least printed a stack trace.
+ * Two changes close it:
+ *
+ *   - **The `inactive` (total-outage) banner is NOT throttled at all.** Once per
+ *     call, every call. Throttling is for the *degraded* case (guard armed,
+ *     evaluating HEAD); a guard that is OFF must keep saying so. Noise there is
+ *     strictly cheaper than a silent disarm.
+ *   - **Where the marker remains (`head-fallback`), CONTENT decides, not
+ *     existence**: a scoped payload (magic + kind + banner key + projectDir
+ *     digest + boot epoch) that an empty `touch` cannot forge, opened
+ *     `O_CREAT|O_EXCL|O_NOFOLLOW` for write and `O_NOFOLLOW` for read — so the
+ *     marker path can no longer be aimed at an arbitrary file via a symlink,
+ *     and a foreign or stale file makes the banner REPEAT rather than vanish.
+ *
+ * Honest residual: an attacker who runs as the same uid and reproduces the
+ * payload format can still suppress the `head-fallback` banner. That is why the
+ * class that actually means "unprotected" no longer depends on the marker.
+ *
+ * Measured cost: `git show` median 4.2 ms (n=21) against a hook allow-path
+ * median of 61 ms (n=15) — +11 ms, and only in the defect case. Zero in normal
+ * operation: nothing here runs unless an import already threw.
+ *
+ * ## Hard constraint on this file
+ *
+ * Everything below runs on the error path of a module-loading failure, so it
+ * MUST NOT import any repo module that could itself be the broken one —
+ * `node:*` builtins only. Keep it that way. An on-disk source cache under
+ * `.orchestrator/runtime/` was considered and REJECTED: its cold-start failure
+ * mode is exactly the target scenario (a fresh worktree mid-merge), and it
+ * creates a deletable trust anchor inside the writable repo.
+ *
+ * Known, accepted gap: a COMMITTED conflict marker breaks the HEAD copy too —
+ * then only the banner fires. That is why the banner is the base and the
+ * fallback the topping.
+ *
+ * Issue: #992.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+/** TTL for the session-id-less marker fallback, mirroring `run-node.sh` (6h). */
+const BANNER_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Marker payload discriminator — an empty `touch` matches none of it. */
+const MARKER_MAGIC = 'session-orchestrator/guard-banner';
+const MARKER_VERSION = 1;
+
+/** Bucket width for the boot-epoch field (seconds), and its accepted drift. */
+const BOOT_BUCKET_S = 10;
+
+/** Repo-relative path of the one module that gets the HEAD fallback. */
+const COMMAND_BLOCKER_REL = 'scripts/lib/command-blocker.mjs';
+
+/**
+ * The FULL export set `pre-bash-destructive-guard.mjs` needs from
+ * `command-blocker.mjs` — the single source of truth for the shape check.
+ *
+ * It lives here, and ONLY here, on purpose. The hook no longer destructures the
+ * module (it holds the namespace object and calls through it), so there is no
+ * second list to drift out of sync: a seventh export is added once, right here,
+ * and both the working-tree and the HEAD copy are validated against it.
+ *
+ * Why the check must cover all of them: it used to assert 2 of the 6, so a HEAD
+ * copy OLDER than the working tree — the normal case when a newly added export
+ * is the very thing that broke, i.e. the #982/#983/#988 history — passed as
+ * "DEGRADED, enforcement IS still armed" and then allowed every command with an
+ * `⚠ internal error — <fn> is not a function` line. A fallback that cannot
+ * enforce must banner as a TOTAL failure, never as "still armed".
+ */
+const COMMAND_BLOCKER_EXPORTS = [
+  'tokenizeCommand',
+  'commandMatchesBlocked',
+  'extractRedirectTargets',
+  'redirectRuleMatches',
+  'resolveSegmentVerb',
+  'splitChainSegments',
+];
+
+/**
+ * Resolve the once-per-session banner key.
+ *
+ * At ESM link-time failure stdin has NOT been read yet, so the payload's
+ * `session_id` is unavailable — and `readStdin` lives in `io.mjs`, which may
+ * itself be the broken module. So the id is read with `node:fs` alone from
+ * `.orchestrator/session.lock`; when that fails we fall back to a time-TTL
+ * marker exactly like `run-node.sh` does.
+ *
+ * @param {string} projectDir
+ * @returns {{key: string, ttl: boolean}} `ttl: true` means "key is not
+ *   session-scoped — apply the 6h time TTL instead of pure existence".
+ */
+function resolveBannerKey(projectDir) {
+  try {
+    const raw = fs.readFileSync(path.join(projectDir, '.orchestrator', 'session.lock'), 'utf8');
+    const id = JSON.parse(raw)?.session_id;
+    if (typeof id === 'string' && id.length > 0) {
+      return { key: id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64), ttl: false };
+    }
+  } catch {
+    /* no lock, unreadable, or malformed — fall through to the time TTL */
+  }
+  return { key: 'ttl', ttl: true };
+}
+
+/** Per-project marker scope — the digest half of the marker file name. */
+function markerScope(projectDir) {
+  return crypto.createHash('sha256').update(projectDir).digest('hex').slice(0, 12);
+}
+
+/**
+ * Coarse boot epoch (unix seconds, bucketed), used to invalidate markers left
+ * behind by a previous boot in a persistent `/tmp`. Bucketing absorbs the
+ * sub-second jitter between two `os.uptime()` reads; the reader additionally
+ * accepts ±1 bucket, so a call straddling a bucket edge is not a false miss.
+ */
+function bootEpochBucket() {
+  return Math.round((Date.now() / 1000 - os.uptime()) / BOOT_BUCKET_S);
+}
+
+/**
+ * Absolute path of the marker file that makes the banner once-per-session.
+ *
+ * Lives in the OS temp dir, NOT in the repo: the error path must not presuppose
+ * repo write access, and a marker inside the repo would be another deletable
+ * trust anchor. Built with `path.join(os.tmpdir(), …)` rather than string
+ * concatenation on `$TMPDIR` — that env var carries a trailing slash on macOS
+ * and is unset on a Linux container.
+ *
+ * The path is intentionally still derivable (it must be, across processes) —
+ * which is exactly why the path alone no longer decides anything: see
+ * `readMarker` for the payload the file has to carry.
+ *
+ * @param {string} scope - `markerScope(projectDir)`, so parallel repos (and
+ *   per-test fixture dirs) never share a marker.
+ * @param {string} kind - banner class (`head-fallback`).
+ * @param {string} key
+ * @returns {string}
+ */
+function bannerMarkerPath(scope, kind, key) {
+  return path.join(os.tmpdir(), `session-orchestrator-guard-${kind}-${scope}-${key}`);
+}
+
+/**
+ * Read + VALIDATE a marker. Returns its write time, or `null` for "no marker of
+ * ours here" — which makes the banner fire.
+ *
+ * Every rejection path is deliberately the fail-LOUD one. A file that exists but
+ * does not carry this exact payload (an empty `touch`, a foreign file, a marker
+ * from another project, kind, session, or boot) is NOT a suppression signal.
+ *
+ * `O_NOFOLLOW` matters on both halves of the marker lifecycle: without it the
+ * predictable path is an arbitrary-file-write primitive (aim a symlink at any
+ * file the session can write, and the marker write truncates it) and an
+ * arbitrary-file-READ oracle.
+ *
+ * @param {string} marker
+ * @param {{kind: string, key: string, scope: string}} expected
+ * @returns {{at: number}|null}
+ */
+function readMarker(marker, expected) {
+  let fd;
+  try {
+    fd = fs.openSync(marker, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const st = fs.fstatSync(fd);
+    // Regular file, single link, owned by us. A hard link or a foreign-uid file
+    // means somebody else controls this path — never honour it.
+    if (!st.isFile() || st.nlink !== 1) return null;
+    if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return null;
+
+    const raw = fs.readFileSync(fd, 'utf8');
+    const rec = JSON.parse(raw);
+    if (rec?.magic !== MARKER_MAGIC || rec?.v !== MARKER_VERSION) return null;
+    if (rec.kind !== expected.kind || rec.key !== expected.key || rec.scope !== expected.scope) {
+      return null;
+    }
+    if (Math.abs(Number(rec.boot) - bootEpochBucket()) > 1) return null;
+
+    const at = Date.parse(rec.at);
+    if (!Number.isFinite(at) || at > Date.now() + 60_000) return null; // no future stamps
+    return { at };
+  } catch {
+    return null; // absent, symlinked (ELOOP), unreadable, or malformed
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* nothing to do on the error path */ }
+    }
+  }
+}
+
+/**
+ * Create the marker exclusively. Never overwrites: `O_EXCL` fails when anything
+ * already sits at the path, and a pre-planted file is therefore left alone —
+ * the banner then simply repeats on every call, which is the safe direction.
+ *
+ * @param {string} marker
+ * @param {{kind: string, key: string, scope: string}} fields
+ */
+function writeMarker(marker, fields) {
+  let fd;
+  try {
+    fd = fs.openSync(
+      marker,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0),
+      0o600
+    );
+    fs.writeSync(
+      fd,
+      `${JSON.stringify({
+        magic: MARKER_MAGIC,
+        v: MARKER_VERSION,
+        ...fields,
+        boot: bootEpochBucket(),
+        at: new Date().toISOString(),
+      })}\n`
+    );
+  } catch {
+    /* unwritable tmp / already present: emit anyway, repeatedly if need be */
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* nothing to do on the error path */ }
+    }
+  }
+}
+
+/**
+ * Write stderr unconditionally. stdout is NEVER an option here: stdout is the
+ * decision channel and an allow REQUIRES an empty stdout (see
+ * `tests/_helpers/hook-decision.mjs`) — a banner there would corrupt every
+ * decision this hook makes.
+ *
+ * @param {string} message
+ */
+function writeBanner(message) {
+  process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+}
+
+/**
+ * Write a guard-DEGRADATION banner to stderr, at most once per session.
+ *
+ * Throttling is confined to the degraded class on purpose: there the guard is
+ * still armed, so a per-call banner is pure noise an operator learns to ignore.
+ * The total-outage banner does NOT come through here — see
+ * `emitGuardInactiveBanner`.
+ *
+ * @param {{projectDir: string, kind: string, message: string}} opts
+ * @returns {boolean} whether the banner was emitted this call.
+ */
+function emitGuardBannerOnce({ projectDir, kind, message }) {
+  const { key, ttl } = resolveBannerKey(projectDir);
+  const scope = markerScope(projectDir);
+  const marker = bannerMarkerPath(scope, kind, key);
+  const fields = { kind, key, scope };
+
+  const existing = readMarker(marker, fields);
+  if (existing) {
+    if (!ttl) return false; // session-keyed: already bannered this session
+    if (Date.now() - existing.at < BANNER_TTL_MS) return false;
+    // Session-id-less TTL expiry: our own marker, verified above — refresh it.
+    try { fs.unlinkSync(marker); } catch { /* keep going; the write may still fail */ }
+  }
+
+  writeMarker(marker, fields);
+  writeBanner(message);
+  return true;
+}
+
+/**
+ * Read a repo file's committed content via `git show HEAD:<relPath>`.
+ *
+ * @param {string} repoRoot
+ * @param {string} relPath - POSIX, repo-relative.
+ * @returns {string} file content at HEAD.
+ * @throws when git is absent, the dir is not a repo, or the path is not at HEAD.
+ */
+function readFromHead(repoRoot, relPath) {
+  return execFileSync('git', ['-C', repoRoot, 'show', `HEAD:${relPath}`], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 8 * 1024 * 1024,
+  });
+}
+
+/**
+ * Import an ESM module from an in-memory source string.
+ *
+ * Only sound for a DEPENDENCY-FREE module (or one importing `node:*` only): a
+ * `data:` URL has no base for relative specifier resolution. `command-blocker.mjs`
+ * qualifies — its single import is `node:path`.
+ *
+ * @param {string} source
+ * @returns {Promise<object>} the module namespace.
+ */
+function importFromSource(source) {
+  const b64 = Buffer.from(source, 'utf8').toString('base64');
+  return import(`data:text/javascript;base64,${b64}`);
+}
+
+/**
+ * Assert a loaded `command-blocker.mjs` namespace carries the COMPLETE API the
+ * guard calls through. A partial namespace is not a degraded guard — it is a
+ * guard that throws on the first command and fails open with an `internal
+ * error` line, so it must be treated as a load failure here, at the one place
+ * that can still fall back or banner.
+ *
+ * @param {object} mod
+ * @param {string} origin - human label for the banner ("working-tree copy" | "HEAD copy")
+ * @throws {Error} naming every missing export.
+ */
+function assertBlockerShape(mod, origin) {
+  const missing = COMMAND_BLOCKER_EXPORTS.filter((name) => typeof mod?.[name] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `${origin} of ${COMMAND_BLOCKER_REL} is missing required export(s): ${missing.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Load `command-blocker.mjs`, falling back to its HEAD version, never silently.
+ *
+ * @param {{specifier: string, repoRoot: string, projectDir: string}} opts
+ *   `specifier` is the import URL/path used in normal operation; `repoRoot` is
+ *   where `git show` runs; `projectDir` keys the banner marker.
+ * @returns {Promise<{module: object, degraded: 'head'|null}>}
+ * @throws the ORIGINAL working-tree error when the HEAD fallback also fails, so
+ *   the caller's catch can banner "guard INACTIVE" with the real cause.
+ */
+export async function loadCommandBlocker({ specifier, repoRoot, projectDir }) {
+  try {
+    const module = await import(specifier);
+    // The shape check runs on BOTH paths. A working-tree copy that parses but
+    // lost an export is the same defect class as a stale HEAD copy: without
+    // this it would arm "successfully" and then fail open per command.
+    assertBlockerShape(module, 'working-tree copy');
+    return { module, degraded: null };
+  } catch (workingTreeError) {
+    let mod;
+    try {
+      mod = await importFromSource(readFromHead(repoRoot, COMMAND_BLOCKER_REL));
+      // A HEAD copy that parses but lost part of the API is NOT a usable
+      // fallback — treat it as a total failure rather than half-arming.
+      assertBlockerShape(mod, 'HEAD copy');
+    } catch (headError) {
+      workingTreeError.headFallbackError = headError;
+      throw workingTreeError;
+    }
+
+    emitGuardBannerOnce({
+      projectDir,
+      kind: 'head-fallback',
+      message: [
+        '',
+        '⚠️  pre-bash-destructive-guard: DEGRADED — running against HEAD, not your working tree.',
+        `    ${COMMAND_BLOCKER_REL} failed to load from the working tree:`,
+        `      ${String(workingTreeError?.message || workingTreeError).split('\n')[0]}`,
+        '    Consequence: destructive-command enforcement IS still armed, but it is evaluating the',
+        '    COMMITTED (HEAD) command lexer — any uncommitted change to that file is NOT in effect.',
+        `    Fix: repair ${COMMAND_BLOCKER_REL} (conflict markers? partial edit?) and re-run.`,
+        '    See: issue #992.',
+        '',
+      ].join('\n'),
+    });
+
+    return { module: mod, degraded: 'head' };
+  }
+}
+
+/**
+ * Banner for the total-failure case: no usable module, guard NOT armed.
+ *
+ * **Deliberately NOT throttled** — this is the one message that must survive
+ * every attempt to quiet it. Its predecessor went through the once-per-session
+ * marker, and because that marker was suppressible by a bare `touch` on a
+ * derivable path, the loudest signal in the system had the weakest lock on it:
+ * plant the file, break a module, and an unarmed guard said nothing at all
+ * while the decision channel said ALLOW. There is nothing to key on here
+ * anyway — every call after the first is equally unprotected, so every call
+ * has equal right to say so. Repetition is the point.
+ *
+ * `projectDir` is retained for signature symmetry with the degraded banner and
+ * for future scoping; it deliberately does not gate anything.
+ *
+ * @param {{projectDir?: string, error: unknown}} opts
+ */
+export function emitGuardInactiveBanner({ error }) {
+  const primary = String(error?.message || error).split('\n')[0];
+  const secondary = error?.headFallbackError
+    ? String(error.headFallbackError.message || error.headFallbackError).split('\n')[0]
+    : null;
+
+  writeBanner(
+    [
+      '',
+      '🚨 pre-bash-destructive-guard: GUARD INACTIVE — this session is NOT protected.',
+      `    Module load failed: ${primary}`,
+      ...(secondary ? [`    HEAD fallback also failed: ${secondary}`] : []),
+      '    Consequence: destructive Bash commands (git reset --hard, rm -rf, git push --force,',
+      '    git stash, redirect-truncate of protected artefacts) are NOT being blocked. This is a',
+      '    BROKEN GUARD, not a policy decision — do not route around it, repair it.',
+      '    Fix: repair the failing module under scripts/lib/, then re-run.',
+      '    See: issue #992, .claude/rules/parallel-sessions.md (PSA-003).',
+      '',
+    ].join('\n')
+  );
+}

package/hooks/_lib/lock-bootstrap.mjs

@@ -187,6 +187,27 @@ export async function bootstrapLock({
     }
   }
 
+  // Step 2b (#987 Part 1): persist the durable ownership proof at lock
+  // genesis. `enriched` is byte-identical to the on-disk lock at this point
+  // (the v2 overlay never touches pid/host/started_at), so the proof written
+  // here will verify via isLockOwnedByProof() against any later re-read.
+  // This single call covers BOTH the plain-acquire and the forceAcquire
+  // branch — both flow through the enriched write above. Best-effort like
+  // the surrounding breadcrumb writes: writeOwnerProof() is no-throw by
+  // contract and a failure never bails the bootstrap — but it is no longer
+  // SILENT (#987 Part 2 review finding): a failed proof write means this
+  // session's /close will degrade to the weaker proof-less release path, so
+  // a one-line stderr WARN gives the operator the only signal there is.
+  try {
+    const { writeOwnerProof } = await import('../../scripts/lib/session-lock.mjs');
+    const proofResult = writeOwnerProof({ repoRoot, lock: enriched });
+    if (proofResult && !proofResult.ok) {
+      process.stderr.write(
+        `⚠ lock-bootstrap: owner-proof write failed (${proofResult.reason ?? 'unknown'}) — /close degrades to proof-less release behaviour\n`,
+      );
+    }
+  } catch { /* best-effort — a missing proof never breaks session-start */ }
+
   // Step 3: best-effort observability breadcrumb. Failures are swallowed
   // so a missing events module never breaks the hook.
   try {

package/hooks/_lib/vcs-create-matcher.mjs

@@ -0,0 +1,119 @@
+/**
+ * vcs-create-matcher.mjs — shared `gh` / `glab` create-command matcher for
+ * PreToolUse Bash hooks.
+ *
+ * Extracted from `hooks/pre-bash-templates-first.mjs` (#519) so the
+ * issue-budget hook (`hooks/pre-bash-issue-budget.mjs`) reuses the SAME
+ * regex + argument-boundary semantics instead of maintaining a second,
+ * silently-diverging copy. Both hooks share the PreToolUse Bash matcher and
+ * run sequentially, so a divergence here would mean one hook gates a command
+ * the other waves through.
+ *
+ * ZERO IMPORTS by design — a clean leaf so any hook can adopt it without
+ * pulling the scripts/lib layer in.
+ *
+ * LOAD-BEARING semantics (contract, mirrors the pre-#-extraction behaviour):
+ *   MATCH:    `gh|glab` + `pr|mr|issue` + `create|new`, anchored at start with
+ *             optional leading whitespace, word-boundary on the trailing edge
+ *             (so `created` / `news` do NOT match).
+ *   NO MATCH: edit operations (`gh pr edit`, `glab mr edit`) — deliberately
+ *             out of scope per the #519 PRD § 2 Out-of-Scope.
+ */
+
+/**
+ * Matches the canonical `gh` / `glab` issue/PR/MR creation invocations.
+ * Anchored at start (^) with optional leading whitespace to catch indented
+ * shell snippets. Word-boundary at the end avoids false positives on tokens
+ * like `created` or `news`.
+ */
+export const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
+
+/**
+ * Parse a shell command into its VCS-create shape.
+ *
+ * @param {string} command
+ * @returns {{ host: 'github'|'gitlab', kind: 'pr'|'mr'|'issue', verb: 'create'|'new' } | null}
+ *   `null` when the command is not a `gh`/`glab` create/new invocation.
+ */
+export function matchVcsCreate(command) {
+  if (typeof command !== 'string' || command.length === 0) return null;
+  const m = command.match(CREATE_REGEX);
+  if (!m) return null;
+  return {
+    host: m[1] === 'gh' ? 'github' : 'gitlab',
+    kind: /** @type {'pr'|'mr'|'issue'} */ (m[2]),
+    verb: /** @type {'create'|'new'} */ (m[3]),
+  };
+}
+
+/**
+ * Determine which host the command targets. `gh` → "github", `glab` → "gitlab".
+ * Thin wrapper kept for call-site readability in pre-bash-templates-first.mjs.
+ *
+ * @param {string} command
+ * @returns {"github"|"gitlab"|null}
+ */
+export function resolveHost(command) {
+  return matchVcsCreate(command)?.host ?? null;
+}
+
+/**
+ * True when the command creates an ISSUE specifically (not a PR/MR).
+ * The issue-budget cap counts issues only — PR/MR creation is not the
+ * runaway-volume problem the cap exists to bound.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isIssueCreate(command) {
+  return matchVcsCreate(command)?.kind === 'issue';
+}
+
+/**
+ * True when the command starts with any of the bypass patterns. Bypass match
+ * is a prefix check with a word/EOL boundary on the trailing edge — this
+ * prevents trivial bypass via prefix-inclusion (e.g. a policy entry
+ * "gh issue create --label bot" must not match "gh issue create --label botanical").
+ *
+ * @param {string} command
+ * @param {string[]} bypassPatterns
+ * @returns {boolean}
+ */
+export function matchesBypass(command, bypassPatterns) {
+  if (typeof command !== 'string') return false;
+  if (!Array.isArray(bypassPatterns) || bypassPatterns.length === 0) {
+    return false;
+  }
+  const stripped = command.replace(/^\s+/, '');
+  for (const pat of bypassPatterns) {
+    if (typeof pat !== 'string' || pat.length === 0) continue;
+    const patStripped = pat.replace(/^\s+/, '');
+    if (!stripped.startsWith(patStripped)) continue;
+    // Boundary check: next character must be whitespace, EOL, or absent.
+    const nextChar = stripped.charAt(patStripped.length);
+    if (nextChar === '' || /\s/.test(nextChar)) return true;
+  }
+  return false;
+}
+
+/**
+ * Best-effort extraction of the `--title` value from a create command, for
+ * human-readable overflow bookkeeping. Handles `--title "x"`, `--title 'x'`,
+ * `--title=x` and the bare unquoted form. Returns `null` when no title flag
+ * is present.
+ *
+ * Deliberately NOT a shell parser: the value is only ever used as a display
+ * label in an overflow record, never re-executed.
+ *
+ * @param {string} command
+ * @returns {string|null}
+ */
+export function extractTitle(command) {
+  if (typeof command !== 'string' || command.length === 0) return null;
+  const m =
+    command.match(/--title[=\s]+"((?:[^"\\]|\\.)*)"/) ??
+    command.match(/--title[=\s]+'([^']*)'/) ??
+    command.match(/--title[=\s]+(\S+)/);
+  if (!m) return null;
+  return m[1].replace(/\\(["\\])/g, '$1').trim() || null;
+}

package/hooks/enforce-commands.mjs

@@ -13,10 +13,18 @@
  *   G5 enforcement != "off"
  *   G6 blocked pattern match against .blockedCommands[], or
  *      fallback safety list when .blockedCommands is empty
- *   G7 strict → deny (exit 2); warn → stderr + allow (exit 0); otherwise allow
+ *   G7 strict → deny; warn → stderr + allow; otherwise allow
+ *
+ * DECISION CHANNEL (post-#906): a deny is signalled by the single nested
+ *   PreToolUse JSON envelope emitDeny() writes to stdout, with exit **0** —
+ *   NOT by exit 2. The docs forbid the mixed form ("Exit 2 … Claude Code
+ *   ignores stdout and any JSON in it"), which silently discarded the reason
+ *   and surfaced to the operator as a crash. Do not reintroduce `exit 2` here.
+ *   Corollary: exit 0 alone no longer distinguishes allow from deny — the
+ *   envelope's presence does, and a malformed envelope fails OPEN.
  *
  * SECURITY-REQ-01: try/catch on main(). emitDeny on any unhandled error —
- *   exit 2, never exit 1. Null-guard readStdin() return.
+ *   fail-closed, never a bare exit 1. Null-guard readStdin() return.
  * SECURITY-REQ-07: FALLBACK_BLOCKED includes 'git push -f' and 'drop table'
  *   (short form + case variant gaps in the original Bash fallback list).
  * SECURITY-REQ-08: scope file read exactly once per invocation.

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.19.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks-cursor.json

@@ -2,14 +2,23 @@
   "_comment": "Cursor IDE hook mapping reference. Configure hooks in Cursor Settings > Hooks.",
   "_note": "Cursor hooks fire at different lifecycle points than Claude Code. See docs/cursor-setup.md for details.",
   "_limitation": "SessionStart greeting (session-start skill) is NOT available on Cursor. Cursor has no conversation-start lifecycle event equivalent to Claude Code's UserPromptSubmit hook. Session initialisation must be triggered manually.",
+  "_enforcement": "reference-only",
+  "_enforcement_note": "MACHINE-READABLE STATUS (#919): every entry below is an intended mapping, NOT live enforcement. No Cursor payload adapter exists (Pi has scripts/lib/pi-hook-bridge.mjs; Cursor has nothing), so each handler short-circuits on a Cursor-shaped payload and writes 0 bytes with exit 0. Operator decision 2026-07-31: gap registered, not closed. The machine-readable counterpart of this key is DOCUMENTED_ASYMMETRIES.handlerAsymmetries.cursor in scripts/lib/validate/check-hooks-symmetry.mjs, which Check 6 counts per event; the projection that makes that comparison non-vacuous is DOCUMENTED_ASYMMETRIES.cursorEventMap.",
+  "_issues": ["#919", "#946"],
   "hooks": {
     "afterFileEdit": {
       "script": "hooks/enforce-scope.mjs",
-      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before). Cannot prevent out-of-scope edits, only warn."
+      "enforcement": "none",
+      "issue": "#919",
+      "mapsToClaudeEvent": "PostToolUse",
+      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before), so this maps onto PostToolUse, never PreToolUse. Cannot prevent out-of-scope edits, only warn — and today not even that: on a Cursor afterFileEdit payload enforce-scope.mjs writes 0 bytes to stdout AND stderr with exit 0 (measured 2026-07-31), because it reads Claude Code's PreToolUse field names."
     },
     "beforeShellExecution": {
       "script": "hooks/enforce-commands.mjs",
-      "note": "Blocks dangerous commands before shell execution. Direct equivalent of Claude Code's PreToolUse Bash hook."
+      "enforcement": "none",
+      "issue": "#919",
+      "mapsToClaudeEvent": "PreToolUse",
+      "note": "NOT WIRED (#919) — silent no-op on a Cursor payload, NOT a block. The handler reads Claude Code's PreToolUse field names (tool_name === 'Bash', tool_input.command) and emits a Claude Code PreToolUse envelope (hookSpecificOutput.permissionDecision). Fed a Cursor beforeShellExecution payload it short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with exit 0 — the harness sees no decision, so the command runs. Cursor needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none exists. Treat this entry as the intended mapping, not as live enforcement."
     }
   }
 }