session-orchestrator 4.2.0 → 5.0.0

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-09T06:39:55.000Z",
-  "head": "9ce6b296e95ce0bc274b887544f0fe885f814427",
+  "generated_at": "2026-09-13T09:10:50.839Z",
+  "head": "ff1ed19177795b743186eebfc387319de0e90c31",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -46,6 +46,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -68,6 +69,7 @@
     {
       "file": "hooks/_lib/subagent-paths.mjs",
       "reachable_from": [
+        "enforce-scope.mjs",
         "on-stop.mjs",
         "post-subagent-discovery-validator.mjs",
         "subagent-telemetry.mjs"
@@ -88,6 +90,7 @@
     {
       "file": "hooks/_lib/vcs-create-matcher.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "pre-bash-issue-budget.mjs",
         "pre-bash-templates-first.mjs"
       ]
@@ -146,6 +149,12 @@
         "operator-steer.mjs"
       ]
     },
+    {
+      "file": "hooks/post-bash-issue-budget-refund.mjs",
+      "reachable_from": [
+        "post-bash-issue-budget-refund.mjs"
+      ]
+    },
     {
       "file": "hooks/post-bash-write-verify.mjs",
       "reachable_from": [
@@ -291,6 +300,7 @@
     {
       "file": "scripts/lib/command-blocker.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-validate.mjs",
         "post-tool-batch-wave-signal.mjs",
@@ -305,6 +315,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "post-subagent-discovery-validator.mjs",
         "pre-bash-issue-budget.mjs",
@@ -337,6 +348,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -359,6 +371,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -384,6 +397,7 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "pre-bash-issue-budget.mjs"
       ]
@@ -550,6 +564,7 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "pre-bash-issue-budget.mjs"
       ]
@@ -594,6 +609,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -634,6 +650,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -672,6 +689,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -766,6 +784,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -811,6 +830,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -831,6 +851,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -851,6 +872,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -881,6 +903,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -924,6 +947,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -948,6 +972,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -968,6 +993,7 @@
     {
       "file": "scripts/lib/issue-budget.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "pre-bash-issue-budget.mjs"
       ]
     },
@@ -988,6 +1014,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1010,6 +1037,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1032,6 +1060,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1089,6 +1118,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1118,6 +1148,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1205,6 +1236,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1225,6 +1257,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1247,6 +1280,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1387,6 +1421,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1417,6 +1452,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1503,6 +1539,12 @@
         "on-session-start.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/wave-transcript-tail.mjs",
+      "reachable_from": [
+        "enforce-scope.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/worktree/listing.mjs",
       "reachable_from": [

package/hooks/_lib/lock-bootstrap.mjs

@@ -38,6 +38,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
 
+/**
+ * Native SessionStart `source` values that are a RE-ENTRY into the same logical
+ * session rather than a new one (#1091).
+ *
+ * SSOT for both consumers — the SessionStart hook's high-water-mark
+ * preservation and the force-refresh gate below — so a later widening
+ * ("`fork` is a re-entry too") can never reach one side only. It lives HERE,
+ * in the leaf module, because the hook already imports this file while the
+ * reverse direction would pull the whole hook's closure into a helper.
+ *
+ * `startup` is deliberately absent: a fresh process start must never inherit a
+ * predecessor's markers or take over its lock.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SAME_LOGICAL_SESSION_SOURCES = new Set(['resume', 'clear', 'compact']);
+
 /**
  * Bootstrap the session.lock for this hook invocation.
  *
@@ -55,6 +72,16 @@ import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
  *   field is populated by mirroring sessionId for backward-compatible display only.
  * @param {string} opts.mode — session mode (e.g. "deep", "feature").
  * @param {number} [opts.ttlHours=4] — lock TTL in hours.
+ * @param {string|null} [opts.nativeSource=null] — the native SessionStart
+ *   `source` (`startup`|`resume`|`clear`|`compact`), when the harness sent one.
+ *   Only consulted for the same-logical-session force-refresh below; every
+ *   existing caller that omits it keeps its pre-#1091 behaviour exactly.
+ * @param {string|null} [opts.predecessorSessionId=null] — the raw `session_id`
+ *   recorded in `.orchestrator/current-session.json` by our OWN previous run of
+ *   this hook. It is the third, load-bearing conjunct of the re-entry
+ *   force-refresh below: without it a same-host semantic-label collision (#1066)
+ *   lets one session take over a live peer's lock. Omitting it (the default)
+ *   disables the re-entry force-refresh entirely — fail-closed.
  * @param {Function} [opts._acquireImpl] — DI for tests (defaults to importing acquire from session-lock.mjs).
  * @param {Function} [opts._forceAcquireImpl] — DI for tests (defaults to importing forceAcquire from session-lock.mjs).
  * @param {Function} [opts._emitEventImpl] — DI for tests (defaults to importing emitEvent from events.mjs).
@@ -66,6 +93,8 @@ export async function bootstrapLock({
   semanticSessionId,
   mode,
   ttlHours = 4,
+  nativeSource = null,
+  predecessorSessionId = null,
   _acquireImpl,
   _forceAcquireImpl,
   _emitEventImpl,
@@ -106,6 +135,53 @@ export async function bootstrapLock({
 
   if (!acquireResult || typeof acquireResult !== 'object') return null;
 
+  // #1091 F2 — a same-logical-session re-entry whose RAW id the harness did not
+  // preserve. `resume` entered the SessionStart matcher in #1091, so this hook
+  // now runs on re-entry: if Claude Code mints a fresh raw `session_id` there,
+  // `acquire()` returns `reason:'active'` with THIS SESSION'S OWN predecessor
+  // lock as `existingLock` (its heartbeat is fresh, so it is live by
+  // definition), `shouldForce` is false, and the hook bails — leaving the
+  // session running for up to the 4 h TTL without owning its own lock, while
+  // `recordConflictSignal()` below names the session's own former self as a
+  // foreign conflict.
+  //
+  // THREE conjuncts gate the force, and all three are load-bearing:
+  //   (a) `SAME_LOGICAL_SESSION_SOURCES.has(nativeSource)` — the harness itself
+  //       says this is a re-entry rather than a fresh start;
+  //   (b) `existingLock.semantic_session_id === semanticSessionId` — the lock's
+  //       label is written by this same bootstrap, so an equal label means the
+  //       predecessor was minted from the same (branch, date, mode, n) tuple;
+  //   (c) `existingLock.session_id === predecessorSessionId` — the RAW id our
+  //       own previous hook run recorded in current-session.json is the raw id
+  //       the live lock carries.
+  //
+  // (a)+(b) alone are NOT enough (security review, #1066): semantic labels are
+  // measurably collidable on one host — two sessions minted the SAME label when
+  // the host-wide registry contributed nothing to the n-increment — so a
+  // `/clear` in session B would take over session A's LIVE lock. (c) is the only
+  // conjunct tied to a witness WE wrote about OURSELVES; it is deliberately not
+  // `resumeLinkage === 'raw-id'`, which is true exactly when the raw id was
+  // PRESERVED — the complement of the fresh-raw-id case this branch exists for.
+  //
+  // NOT gated on process liveness, deliberately: `pid` on a session.lock is the
+  // ephemeral hook subprocess that WROTE it, so `isPidAliveOnHost(lock.pid)`
+  // reports "dead" for essentially every lock including live heartbeating ones
+  // (7/7 measured, #1137) — a vacuous predicate that would widen this branch to
+  // every source, not narrow it. `isLockLive()` is no help either: under
+  // `reason:'active'` acquire() has already established it is true
+  // (session-lock.mjs `classifyExisting`).
+  //
+  // Ceiling (BV-004), named rather than claimed closed: the residual is a peer
+  // that wrote `current-session.json` LAST with our semantic label — that peer's
+  // raw id is what we read as `predecessorSessionId`, so if it also owns the
+  // live lock, conjunct (c) holds for the wrong session. `current-session.json`
+  // carries no session field of its own (see
+  // `.claude/rules/identity-and-locks.md` § shared repo artefacts), which is
+  // exactly why this is a ceiling and not a proof. Revisit when the lock or
+  // current-session.json carries a durable logical-session id of its own.
+  const isSameLogicalReentry =
+    typeof nativeSource === 'string' && SAME_LOGICAL_SESSION_SOURCES.has(nativeSource);
+
   const shouldForce =
     acquireResult.ok !== true && (
       // #1137: 'stale-heartbeat' replaced the former 'stale-pid-dead' /
@@ -115,7 +191,14 @@ export async function bootstrapLock({
       acquireResult.reason === 'stale-heartbeat' ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
-        acquireResult.existingLock.session_id === sessionId)
+        (acquireResult.existingLock.session_id === sessionId ||
+          (isSameLogicalReentry &&
+            typeof semanticSessionId === 'string' &&
+            semanticSessionId.length > 0 &&
+            acquireResult.existingLock.semantic_session_id === semanticSessionId &&
+            typeof predecessorSessionId === 'string' &&
+            predecessorSessionId.length > 0 &&
+            acquireResult.existingLock.session_id === predecessorSessionId)))
     );
 
   if (!acquireResult.ok && shouldForce) {

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

@@ -434,6 +434,126 @@ function titleFromTokens(tokens) {
   return null;
 }
 
+/**
+ * Per-host CLI flag names for the non-title fields of an issue-create
+ * statement (#1314). Verified against the CLIs' own `--help` (2026-09-12):
+ *   glab issue create: `-t --title`, `-d --description`, `--description-file`, `-R --repo`
+ *   gh issue create:   `-t, --title`, `-b, --body`, `-F, --body-file`, `-R, --repo`
+ * Read only on the subcommand route — on the api route `-F` is a field flag.
+ */
+const CLI_FLAGS = {
+  gitlab: { description: ['-d', '--description'], descriptionFile: ['--description-file'], repo: ['-R', '--repo'] },
+  github: { description: ['-b', '--body'], descriptionFile: ['-F', '--body-file'], repo: ['-R', '--repo'] },
+};
+
+/** `$(cat <path>)` as ONE value — the only command substitution resolved. */
+const CAT_SUBST_RE = /^\$\(cat\s+(\S+)\)$/;
+
+/**
+ * Read the value of a flag in `names` (`--x v`, `--x=v`, `-x v`). When the flag
+ * repeats, the LAST value wins — the pflag semantics `gh`/`glab` apply.
+ * An UNQUOTED `$(cat p)` is split by the lexer into `$(cat` + `p)`; that pair is
+ * rejoined so the substitution survives, in both the `--x $(cat p)` and the
+ * `--x=$(cat p)` spelling.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} tokens
+ * @param {string[]} names
+ * @returns {string|null}
+ */
+function flagValue(tokens, names) {
+  let found = null;
+  for (let i = 0; i < tokens.length; i++) {
+    const text = tokens[i].text;
+    for (const name of names) {
+      let value;
+      if (text === name) {
+        value = tokens[i + 1]?.text;
+        if (typeof value !== 'string') return found;
+        i += 1;
+      } else if (name.startsWith('--') && text.startsWith(`${name}=`)) {
+        value = text.slice(name.length + 1);
+      } else {
+        continue;
+      }
+      if (value === '$(cat' && typeof tokens[i + 1]?.text === 'string') {
+        value = `$(cat ${tokens[i + 1].text}`;
+        i += 1;
+      }
+      found = value;
+      break;
+    }
+  }
+  return found;
+}
+
+/**
+ * The paths of every `$(cat <path>)` that sits inside SINGLE quotes in the RAW
+ * command. The lexer marks single- and double-quoted tokens alike, but only
+ * the double-quoted (or bare) form is expanded by the shell — inside single
+ * quotes `gh`/`glab` receive the literal text, so reading that file would park
+ * content the CLI never saw (`-d '$(cat .env)'`).
+ *
+ * @param {string} command — the raw command, quotes intact
+ * @returns {Set<string>}
+ */
+function singleQuotedCatPaths(command) {
+  const out = new Set();
+  let quote = null;
+  let span = '';
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote === "'") {
+      if (c === "'") {
+        for (const m of span.matchAll(/\$\(cat\s+(\S+)\)/g)) out.add(m[1]);
+        quote = null;
+        span = '';
+      } else {
+        span += c;
+      }
+    } else if (c === '\\') {
+      i += 1; // an escaped char opens no quote
+    } else if (quote === '"') {
+      if (c === '"') quote = null;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+    }
+  }
+  return out;
+}
+
+/**
+ * Title, description, description file and target repo of ONE create
+ * statement (#1314) — what a parked overflow record needs to be re-filed.
+ * Additive to {@link titleFromTokens}: its `--title` / `-f title=` reading is
+ * kept verbatim; `-t` is added on the subcommand route only.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} tokens
+ * @param {{ host: string, via: string }} shape
+ * @param {Set<string>} literalCatPaths — from {@link singleQuotedCatPaths}
+ * @returns {{ title: string|null, description: string|null,
+ *             descriptionFile: string|null, repo: string|null }}
+ */
+function fieldsFromTokens(tokens, shape, literalCatPaths) {
+  let title = titleFromTokens(tokens);
+  const flags = shape.via === 'cli' ? CLI_FLAGS[shape.host] : undefined;
+  if (!flags) return { title, description: null, descriptionFile: null, repo: null };
+  if (title === null) title = flagValue(tokens, ['-t'])?.trim() || null;
+  let description = flagValue(tokens, flags.description);
+  let descriptionFile = flagValue(tokens, flags.descriptionFile);
+  // `-` means stdin (or an editor for glab -d) — nothing a later read can reach.
+  if (descriptionFile === '-') descriptionFile = null;
+  if (description === '-') description = null;
+  // A single-quoted `$(cat p)` stays the literal text the CLI files.
+  const subst = typeof description === 'string' ? CAT_SUBST_RE.exec(description) : null;
+  if (subst && !literalCatPaths.has(subst[1])) {
+    description = null;
+    descriptionFile ??= subst[1];
+  }
+  const fileSubst = typeof descriptionFile === 'string' ? CAT_SUBST_RE.exec(descriptionFile) : null;
+  if (fileSubst) descriptionFile = literalCatPaths.has(fileSubst[1]) ? null : fileSubst[1];
+  return { title, description, descriptionFile, repo: flagValue(tokens, flags.repo) };
+}
+
 /**
  * EVERY issue-create statement in the command chain, in source order (#1163
  * BUG-1).
@@ -458,27 +578,94 @@ function titleFromTokens(tokens) {
  * the lexer, arguments joined by single spaces). It is a CLASSIFICATION INPUT
  * for `classifyExemption`, never something to re-execute.
  *
+ * `cwdChanged` is true when an EARLIER statement of the same chain is a
+ * `cd`/`pushd`/`popd`: a relative description-file path is then relative to a
+ * directory this hook cannot know, so `buildOverflowRecord` must not resolve it.
+ *
  * @param {string} command
  * @returns {Array<{ shape: { host: string, kind: string, verb: string, via: string },
  *                   tokens: Array<{ text: string, quoted: boolean }>,
  *                   text: string,
- *                   title: string|null }>}
+ *                   title: string|null,
+ *                   description: string|null,
+ *                   descriptionFile: string|null,
+ *                   repo: string|null,
+ *                   cwdChanged: boolean }>}
  */
 export function findIssueCreateStatements(command) {
   const out = [];
+  let literalCatPaths = null;
+  let cwdChanged = false;
   for (const tokens of statementsOf(command)) {
     const shape = matchStatement(tokens);
-    if (!shape || shape.kind !== 'issue') continue;
+    if (!shape || shape.kind !== 'issue') {
+      if (!cwdChanged && tokens.length > 0) {
+        try {
+          cwdChanged = CWD_VERBS.has(resolveSegmentVerb(tokens).verb);
+        } catch {
+          cwdChanged = true; // unknown → do not trust a relative path
+        }
+      }
+      continue;
+    }
+    literalCatPaths ??= singleQuotedCatPaths(command);
     out.push({
       shape,
       tokens,
       text: tokens.map((t) => t.text).join(' '),
-      title: titleFromTokens(tokens),
+      ...fieldsFromTokens(tokens, shape, literalCatPaths),
+      cwdChanged,
     });
   }
   return out;
 }
 
+/**
+ * Do the issue-create statements account for the WHOLE command? (#1347)
+ *
+ * ## Why a refund needs this and a charge does not
+ *
+ * The charge is per statement and runs BEFORE the command, so it never has to
+ * ask what else is in the chain. The refund runs AFTER, and the harness reports
+ * ONE exit code for the whole Bash call — so a failure signal on
+ * `glab issue create --title X && false` says nothing about the create. Measured
+ * 2026-09-13 against the first cut of `hooks/post-bash-issue-budget-refund.mjs`:
+ * that exact command CREATES the issue, exits 1, and one slot was handed back.
+ * Refunding a create whose failure is not attributable to it is a cap drain, so
+ * the refund hook asks this question first and no-ops when the answer is false.
+ *
+ * True only when the command has at least one issue-create statement and EVERY
+ * statement of the chain is one. A chain that mixes a create with anything else
+ * — including a benign-looking `cd`, `echo`, or `true` — is not attributable
+ * here, which is the fail-CLOSED direction: the slot stays spent.
+ *
+ * NAMED CEILING (BV-004): the most common agent shape `cd <repo> && glab issue
+ * create …` is therefore NOT refundable, even though a failing `cd` provably
+ * means the create never ran. Admitting a prefix class would also admit a
+ * TRAILING one under the same argument, and a trailing statement's failure is
+ * exactly the drain above. Revisit if the refund rate measured over
+ * `.orchestrator/runtime/issue-budget/<hash>.json` charges shows the `cd` shape
+ * dominating; the safe widening is a LEADING-only allowance for `CWD_VERBS`,
+ * never a general one.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function statementsCoverWholeCommand(command) {
+  const all = statementsOf(command);
+  if (all.length === 0) return false;
+  let creates = 0;
+  for (const tokens of all) {
+    const shape = matchStatement(tokens);
+    if (!shape || shape.kind !== 'issue') return false;
+    creates += 1;
+  }
+  return creates > 0;
+}
+
+/** Builtins that move the shell's working directory for later statements. */
+const CWD_VERBS = new Set(['cd', 'pushd', 'popd']);
+
 /**
  * Determine which host the command targets. `gh` → "github", `glab` → "gitlab".
  * Thin wrapper kept for call-site readability in pre-bash-templates-first.mjs.