session-orchestrator 5.1.0 → 5.3.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -230,6 +230,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 /** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
 /** @type {typeof import('../scripts/lib/io.mjs').writeJsonAtomicSync} */ let writeJsonAtomicSync;
 /** @type {typeof import('../scripts/lib/file-lock.mjs').withFileLock} */ let withFileLock;
+/** @type {typeof import('../scripts/lib/scope-echo.mjs').scopeDigest} */ let scopeDigest;
 let findScopeCollisions;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
@@ -287,6 +288,48 @@ const SHAPE_NONE = 'none';
 /** The per-dispatch observability record (#1092) — see § Observability. */
 const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
 
+/**
+ * The worktree-base observability record (#1413).
+ *
+ * Same `wave_dispatch` domain and same `_checked` verb as `SCOPE_EVENT`, and
+ * written for EVERY `isolation: "worktree"` dispatch rather than only the
+ * alarming one. That is HR-105 applied at the source: a numerator-only stream
+ * cannot tell "genuinely rare" from "silently broken", and the firing rate this
+ * warning must stay under is then unfalsifiable. With every outcome in one
+ * stream the rate is `stale:true / all records of this name`.
+ *
+ * #1424 widened "every outcome" from two to three: the `stale: true|false`
+ * split was already covered, but each NON-measurement (peer STATE.md, no
+ * STATE.md, no `session-start-ref`, a git failure) returned early and emitted
+ * nothing — so the gate in front of the split reproduced exactly the
+ * zero-records ambiguity the split had removed. Those now carry
+ * `stale: null` plus a `skipped` reason, and only `isolation !== "worktree"`
+ * stays silent (HR-101: it is ~90% of all dispatches).
+ */
+const WORKTREE_BASE_EVENT = 'orchestrator.wave_dispatch.worktree_base_checked';
+
+/** State-dir candidates, in the same order `waveKeyOf()` probes them. */
+const STATE_DIR_CANDIDATES = ['.pi', '.cursor', '.codex', '.claude'];
+
+/**
+ * The receive-side instruction line `renderScopeEchoInstruction()` renders and
+ * the coordinator appends immediately after the fenced block
+ * (`wave-loop-dispatch.md` § Pre-Dispatch: File-Scope Injection).
+ *
+ * Matching it HERE, in the same prompt, is what makes the agent-A-block-with-
+ * agent-B-line mix-up catchable without a single filesystem read: the block and
+ * the line must come from the same `$AGENT_FILESCOPE_JSON`, so their digests
+ * must agree (`digest_consistent`). The marker half stays case-sensitive for the
+ * same reason `scope-echo.mjs` keeps it so — a lowercase lookalike is not the
+ * line; the HEX half is read case-insensitively and normalised to lowercase.
+ * Non-global on purpose: a `g` regex carries `lastIndex` between calls.
+ */
+const ECHO_INSTRUCTION_RE =
+  /End your final report with the line:[ \t]*`{0,3}SCOPE-DIGEST:[ \t]*`{0,3}([0-9a-fA-F]{8})(?![0-9a-fA-F])/;
+
+/** Shape of a well-formed digest, used to reject anything a broken digest fn returns. */
+const DIGEST_RE = /^[0-9a-f]{8}$/;
+
 /**
  * Clamp for the one free-form string the event carries (`agent_id`, built from
  * the coordinator's own `description`). A dispatch description is a label, but
@@ -358,6 +401,14 @@ async function bootstrap() {
       io: { specifier: lib('io.mjs') },
       scopeGate: { specifier: lib('scope-gate.mjs') },
       fileLock: { specifier: lib('file-lock.mjs') },
+      // ONE normalization for the digest, shared with the receive side (#1092):
+      // `scope-echo.mjs` is pure (stdlib + `crypto-digest-utils.mjs`) and its
+      // `scopeDigest` is what `--verify` joins the two halves on. A second
+      // implementation here would let the halves disagree while both looked
+      // right — the class `guard-design.md` § "zero-import predicate module"
+      // names. Late-bound like every other repo module so a load failure
+      // banners instead of disarming the guard silently (#993).
+      scopeEcho: { specifier: lib('scope-echo.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -370,6 +421,7 @@ async function bootstrap() {
   ({ readStdin, emitAllow, emitDeny, emitWarn, writeJsonAtomicSync } = modules.io);
   ({ findScopeCollisions } = modules.scopeGate);
   ({ withFileLock } = modules.fileLock);
+  ({ scopeDigest } = modules.scopeEcho);
 }
 
 // ---------------------------------------------------------------------------
@@ -407,8 +459,51 @@ const SCOPE_TERMS = 'DATEI[- ]SCOPE|FILE[- ]SCOPE|FILE SCOPE|DEIN SCOPE|SCOPE \\
  * hit in a region as one is the recorded failure of `parseEpicRef` (#1112).
  *
  * The real miss class is a different SHAPE, handled by {@link INLINE_SCOPE_DECL}.
+ *
+ * ## The marker vocabulary is CASE-SENSITIVE, and that is a measurement (#1092)
+ *
+ * Until 2026-09-16 both shapes carried the `i` flag, so the term `FILE SCOPE`
+ * also matched ordinary lowercase prose. The Learnings-Index header this repo
+ * injects into every agent prompt —
+ * `## Learnings Index (selected for your file scope) — …` — therefore matched
+ * the marker at column ~38 of a line-leading window, and the FIRST fenced block
+ * anywhere after it (a verification command, a report template) decided the
+ * class: no path survived, so the dispatch was recorded `unparseable`, i.e.
+ * matrix row 6 — "a declaration is present but the parser gave up".
+ *
+ * MEASURED in this session's own wave 1 (`.orchestrator/wave-dispatch-scopes.json`,
+ * waveKey `5de6560c-…|w1|Discovery`): `unparseable: 5, extracted: 0` for FIVE
+ * Discovery dispatches that carried no `FILE-SCOPE` block at all. Host-wide the
+ * same confusion accounts for the 52 historical `unparseable` records.
+ *
+ * Every DOCUMENTED marker is upper-case (`wave-loop-dispatch.md` § Pre-Dispatch:
+ * File-Scope Injection writes `FILE-SCOPE — exactly these:`), while every
+ * measured false positive is prose in sentence case — so dropping `i` separates
+ * them without narrowing the search window, which the § above showed recovers
+ * nothing.
+ *
+ * ## What dropping `i` costs, stated honestly (corrected 2026-09-16)
+ *
+ * The first cut of this note claimed the change "moves a CLASSIFICATION and
+ * never a decision", on the grounds that `marker-absent` and `unparseable` both
+ * resolve to ALLOW. That is only true for a declaration the parser would have
+ * given up on anyway. A MIXED-CASE declaration that WOULD have yielded paths
+ * (`File-Scope:` followed by a fenced path list) now matches nothing, so
+ * `extractScopeFromPrompt` returns `[]`, `findScopeCollisions` never runs, and
+ * the dispatch is ALLOWED unconditionally — a lost DENY capability for that
+ * spelling, i.e. a decision change, not a reclassification.
+ *
+ * It is safe today because every LIVE injector writes the upper-case canonical
+ * marker: `skills/wave-executor/references/wave-loop-dispatch.md`
+ * § Pre-Dispatch: File-Scope Injection documents `FILE-SCOPE — exactly these:`,
+ * and the repo-wide census (2026-09-16) finds the mixed-case spellings only in
+ * prose, never in an injected block. That is a property of the injectors, not of
+ * this regex, so it is PINNED rather than assumed:
+ * `tests/skills/wave-loop-scope-marker.test.mjs` asserts the documented marker
+ * line is upper-case and matches {@link SCOPE_MARKER}, so a future template edit
+ * to `File-Scope:` goes red instead of silently disarming the guard.
  */
-const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'im');
+export const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'm');
 
 /**
  * SHAPE 2 (lower precedence) — the measured miss class: a declaration written
@@ -436,7 +531,7 @@ const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'im');
  * one false extraction (`[".filter"]`) is a prose fragment, which is why the
  * fenced shape keeps precedence and this one runs only when that found nothing.
  */
-const INLINE_SCOPE_DECL = new RegExp(`(${SCOPE_TERMS})`, 'ig');
+const INLINE_SCOPE_DECL = new RegExp(`(${SCOPE_TERMS})`, 'g');
 const INLINE_DECL_OPERATOR = /^[^\n(:—–]{0,2}(\([^)\n]{0,80}\))?\s*(?:[—–][^\n:]{0,30})?\s*(:|—|–)/;
 
 /** Separators a coordinator uses between paths in an inline declaration. */
@@ -909,6 +1004,163 @@ export function listTrackedFiles(cwd) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Stale worktree base (#1413) — a WARNING, never a decision
+//
+// `isolation: "worktree"` makes the HARNESS create `<repo>/.claude/worktrees/
+// agent-<hex>`; no code in this repo creates it and the `Agent` payload carries
+// no base-ref field (the 147-dispatch key census in the module docblock). The
+// base is the SESSION-START commit, and it does not follow a mid-session commit:
+// measured 2026-09-19 (session s18), worktrees created 25 minutes AFTER commit
+// `240efda6` still stood on its parent `8f15f77b`. A fix agent then silently
+// edits the OLD code, and its test run is structurally red on top — `validate-
+// plugin` is vitest's globalSetup and `check-guard-requires-parity.mjs` compares
+// against `git show HEAD:` inside the stale worktree.
+//
+// We have no lever on the base, so the only available fix is to be LOUD. This
+// never touches the verdict: the two functions below are TOTAL (every failure
+// resolves to silence), and the caller ignores their result for the decision.
+// ---------------------------------------------------------------------------
+
+/**
+ * Facts for the worktree-base check, as a DISCRIMINATED record with three
+ * outcomes rather than two (#1424):
+ *
+ *   - `{stale: true|false, head, session_start_ref, subagent_type?}` — measured.
+ *   - `{stale: null, skipped: <reason>}` — the dispatch WAS on the `worktree`
+ *     branch, but the question could not be answered honestly. Still emitted,
+ *     because HR-105 needs the denominator: while every such case returned bare
+ *     `null` and the caller emitted nothing, "the check never had anything to
+ *     say" and "the check was silently disarmed" both read as zero records —
+ *     precisely the shape this event exists to close.
+ *   - `null` — `isolation !== 'worktree'`. SILENT by construction, and the one
+ *     outcome that must stay so: `isolation` appeared in 14 of 147 measured
+ *     dispatches, so recording the other ~90% would put the denominator on the
+ *     whole hot dispatch path (HR-101).
+ *
+ * IDENTITY GATE (`.claude/rules/identity-and-locks.md`): `session-start-ref`
+ * lives in STATE.md, a SHARED working-copy artefact that routinely belongs to a
+ * peer session. It is read only when STATE.md's own `session-id` equals this
+ * process's raw id (hook payload `session_id`, else `CLAUDE_CODE_SESSION_ID`) —
+ * a process-local witness REPLACES the shared one, never unions with it. On
+ * mismatch, absence or any read failure this reports `stale: null`: a confident
+ * warning about somebody else's session is worse than no warning at all. The
+ * test runs PER CANDIDATE (`continue`, not `break`) — see the loop below.
+ *
+ * `parseStateMd` is imported DYNAMICALLY and only on the rare `worktree` branch
+ * (14 of 147 measured dispatches carried `isolation` at all): it is a leaf module
+ * with zero imports and already inside the committed hook-import closure, so
+ * reuse costs no new edge, and binding it late keeps a load failure catchable
+ * instead of disarming the guard at ESM link time (§ #993 late-bound deps).
+ *
+ * @param {{tool_input?: unknown}} input — the raw hook payload
+ * @param {string} projectDir
+ * @param {string} sessionId — `input.session_id`, or `'no-session'`
+ * @returns {Promise<{head: string, session_start_ref: string, stale: boolean,
+ *   subagent_type?: string}|{stale: null, skipped: string}|null>}
+ */
+async function worktreeBaseFacts(input, projectDir, sessionId) {
+  // The applicability gate sits OUTSIDE the try on purpose: everything below it
+  // resolves to a `skipped` RECORD, so a throw here must not be able to mint one
+  // for a dispatch that was never on the `worktree` branch at all.
+  const toolInput = input?.tool_input;
+  if (toolInput === null || typeof toolInput !== 'object') return null;
+  if (toolInput.isolation !== 'worktree') return null;
+
+  try {
+    const ownId = sessionId && sessionId !== 'no-session'
+      ? sessionId
+      : (process.env.CLAUDE_CODE_SESSION_ID || '');
+    if (!ownId) return { stale: null, skipped: 'no-own-id' };
+
+    const { parseStateMd } = await import(
+      pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'state-md', 'yaml-parser.mjs')).href
+    );
+
+    // #1424: the identity test lives INSIDE the loop. Breaking at the first
+    // PARSEABLE STATE.md and testing `session-id` afterwards meant a single
+    // left-over `.pi/STATE.md` — `.pi` sorts before `.claude` in
+    // STATE_DIR_CANDIDATES — disarmed the check for a session whose own
+    // `.claude/STATE.md` sat right there, readable and matching. `sawStateMd`
+    // keeps the two silences apart afterwards: "nothing to read" is a different
+    // fact from "read, and none of it was mine".
+    let frontmatter = null;
+    let sawStateMd = false;
+    for (const dir of STATE_DIR_CANDIDATES) {
+      try {
+        const parsed = parseStateMd(readFileSync(path.join(projectDir, dir, 'STATE.md'), 'utf8'));
+        if (!parsed?.frontmatter) continue;
+        sawStateMd = true;
+        if (parsed.frontmatter['session-id'] !== ownId) continue;
+        frontmatter = parsed.frontmatter;
+        break;
+      } catch { /* try the next state dir */ }
+    }
+    if (frontmatter === null) {
+      return { stale: null, skipped: sawStateMd ? 'identity-mismatch' : 'no-state-md' };
+    }
+
+    const startRef = typeof frontmatter['session-start-ref'] === 'string'
+      ? frontmatter['session-start-ref'].trim()
+      : '';
+    if (startRef === '') return { stale: null, skipped: 'no-start-ref' };
+
+    let head = '';
+    try {
+      head = execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: projectDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      return { stale: null, skipped: 'git-error' };
+    }
+    if (head === '') return { stale: null, skipped: 'git-error' };
+
+    const facts = { head, session_start_ref: startRef, stale: head !== startRef };
+    if (typeof toolInput.subagent_type === 'string' && toolInput.subagent_type !== '') {
+      facts.subagent_type = toolInput.subagent_type;
+    }
+    return facts;
+  } catch {
+    // Total by construction: no parser, an unreadable state dir, anything else.
+    // Still a RECORD rather than silence — the dispatch WAS on the `worktree`
+    // branch, and a broken probe that emits nothing is indistinguishable from a
+    // probe that had nothing to report (#1424 / HR-105).
+    return { stale: null, skipped: 'probe-error' };
+  }
+}
+
+/**
+ * The operator-facing warning. It names the ACTION, not just the condition —
+ * a warning the coordinator cannot act on is noise (HR-106).
+ *
+ * NO `⚠ ` PREFIX HERE: this text is handed to `emitWarn`, which prefixes it on
+ * both channels it writes (stderr and the `systemMessage` payload). Prefixing
+ * here too produced `⚠ ⚠ …`.
+ *
+ * @param {{head: string, session_start_ref: string}} facts
+ * @returns {string}
+ */
+function staleWorktreeWarning(facts) {
+  const head = facts.head.slice(0, 12);
+  const base = facts.session_start_ref.slice(0, 12);
+  return [
+    `${HOOK_NAME}: STALE WORKTREE BASE (#1413) — this dispatch uses `
+      + `isolation: "worktree", but HEAD (${head}) has moved past this session's `
+      + `session-start-ref (${base}).`,
+    '  The harness bases a new agent worktree on the SESSION-START commit and offers',
+    '  no base-ref field, so the agent will silently get the OLDER code — and its test',
+    '  run is structurally red on top (check-guard-requires-parity compares against',
+    '  `git show HEAD:`, and validate-plugin is vitest\'s globalSetup).',
+    '  DO ONE OF: dispatch this wave IN-PLACE (omit `isolation`) — or verify the base',
+    '  before trusting the agent\'s result:',
+    '    git worktree list --porcelain | awk -v h="$(git rev-parse HEAD)" '
+      + '\'/^worktree /{w=$2} /^HEAD /{if (w ~ /\\.claude\\/worktrees\\/agent-/ && $2 != h) '
+      + 'print "STALE " substr($2,1,12) " " w}\'',
+  ].join('\n');
+}
+
 /**
  * Clip a path for the deny reason without losing the discriminating tail.
  *
@@ -980,6 +1232,69 @@ export function bumpSignalCounter(ledger, waveKey, status) {
   return next;
 }
 
+/**
+ * The digest half of the per-dispatch record (#1092) — the field set that makes
+ * the SEND side joinable to the RECEIVE side.
+ *
+ * Four facts, all derived from the PROMPT alone, none of them a path:
+ *
+ *   `scope_digest`            — `scopeDigest()` over the paths extracted FROM THE
+ *                               PROMPT. This is the join key `scope-echo --verify`
+ *                               uses; `agent_id` cannot be one, because the two
+ *                               halves spell it differently (measured 2026-09-16:
+ *                               609 send-side vs 51 receive-side records, agent-id
+ *                               overlap ZERO — send writes
+ *                               `"i-3 #1353 … (session-orchestrator:code-implementer)"`,
+ *                               receive writes `"i-3"`).
+ *   `echo_instruction_present`— the coordinator appended the echo line at all.
+ *   `instructed_digest`       — the digest THAT LINE names.
+ *   `digest_consistent`       — the two agree. `false` is agent A's fenced block
+ *                               beside agent B's echo line, caught at dispatch
+ *                               time with no filesystem read.
+ *
+ * ABSENT IS NOT ZERO, in both directions (`docs/events-schema.md`):
+ * `scope_digest` is OMITTED for an empty scope — never the digest of the empty
+ * string, which is a real 8-hex value and would join marker-absent Discovery
+ * dispatches to each other. `instructed_digest` is omitted when no line was
+ * found, and `digest_consistent` unless BOTH are present.
+ *
+ * TOTAL by construction: every branch is wrapped, because this runs on the
+ * decision path of a deny-capable hook. A throwing digest function must cost the
+ * FIELD, never the verdict — same discipline as the awaited-and-caught emit.
+ *
+ * @param {string[]} files      paths extracted from the prompt
+ * @param {unknown} prompt      the dispatch prompt
+ * @param {((paths: string[]) => string)} [digestFn] injectable for tests; defaults
+ *   to the late-bound `scopeDigest` (undefined when `bootstrap()` has not run,
+ *   which this function treats exactly like a throwing one — the field is omitted)
+ * @returns {{scope_digest?: string, echo_instruction_present: boolean,
+ *            instructed_digest?: string, digest_consistent?: boolean}}
+ */
+export function scopeDigestFields(files, prompt, digestFn) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  try {
+    const fn = typeof digestFn === 'function' ? digestFn : scopeDigest;
+    if (typeof fn === 'function' && Array.isArray(files) && files.length > 0) {
+      const digest = fn(files);
+      if (typeof digest === 'string' && DIGEST_RE.test(digest)) out.scope_digest = digest;
+    }
+  } catch { /* a broken digest costs the field, never the decision */ }
+
+  let instructed = null;
+  try {
+    const match = typeof prompt === 'string' ? ECHO_INSTRUCTION_RE.exec(prompt) : null;
+    if (match !== null) instructed = match[1].toLowerCase();
+  } catch { instructed = null; }
+
+  out.echo_instruction_present = instructed !== null;
+  if (instructed !== null) out.instructed_digest = instructed;
+  if (typeof out.scope_digest === 'string' && instructed !== null) {
+    out.digest_consistent = out.scope_digest === instructed;
+  }
+  return /** @type {any} */ (out);
+}
+
 /**
  * @typedef {{action: 'allow'|'deny'|'warn', reason?: string, suggestion?: string,
  *            ledger?: object|null, note?: string, telemetry?: object}} Verdict
@@ -997,9 +1312,11 @@ export function bumpSignalCounter(ledger, waveKey, status) {
  * @param {Function} params.collide           `findScopeCollisions` (injected for testability)
  * @param {(entry: object) => boolean} [params.isFinished] liveness probe (§ Liveness)
  * @param {string} [params.nowIso]            dispatch timestamp recorded on the entry
+ * @param {(paths: string[]) => string} [params.digestFn] scope-digest function
+ *   (injected for testability; defaults to the late-bound `scopeDigest`)
  * @returns {Verdict}
  */
-export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso }) {
+export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn }) {
   const toolName = input?.tool_name;
   // Row 4: not our tool.
   if (toolName !== DISPATCH_TOOL) return { action: 'allow' };
@@ -1023,13 +1340,19 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   // agent id, never a path, never a byte of the prompt (issue #1092 acceptance
   // criterion 3). `wave` is omitted rather than zeroed when unknown.
   const wave = waveNumberOf(waveKey);
+  const digestFields = scopeDigestFields(files, toolInput.prompt, digestFn);
   const telemetryFor = (ledgerResult, collisionCount = 0) => ({
     ...(wave === null ? {} : { wave }),
     agent_id: id.slice(0, MAX_AGENT_ID_CHARS),
     declared_path_count: files.length,
     injected: files.length > 0,
+    // `marker_found` is NOT a second spelling of `injected`: a fenced block whose
+    // lines are prose is `marker_found: true, injected: false` (matrix row 6),
+    // which is the row-5-vs-row-6 split expressed as a boolean a query can group by.
+    marker_found: signal.status !== SIGNAL_MARKER_ABSENT,
     shape: signal.shape,
     signal: signal.status,
+    ...digestFields,
     ledger_result: ledgerResult,
     collision_count: collisionCount,
   });
@@ -1297,8 +1620,59 @@ async function main() {
     } catch { /* observability is best-effort — it never blocks the decision */ }
   }
 
-  if (verdict.action === 'deny') return emitDeny(verdict.reason, verdict.suggestion);
-  if (verdict.action === 'warn') return emitWarn(verdict.note);
+  // #1413 — the stale-worktree-base warning, also awaited BEFORE the terminal
+  // emit for the same process.exit() reason as the block above. It reads
+  // `verdict` not at all: it can never turn an allow into a deny, and a git or
+  // STATE.md failure resolves to silence rather than to a wrong accusation.
+  //
+  // ROUTED TO THE OPERATOR, not to stderr alone (w3-5): under the exit-0
+  // PreToolUse protocol stderr goes nowhere — `io.mjs:545` calls it the "Debug
+  // channel … Invisible under exit 0" — so the first cut of this check announced
+  // the s18 incident class to a log and to nobody. The visible channel is the
+  // top-level `systemMessage`, i.e. `emitWarn`, which carries NO
+  // `permissionDecision` and therefore still means ALLOW (io.mjs § "which is
+  // precisely what keeps warn non-blocking").
+  //
+  // The note is CARRIED to the single terminal emit below rather than emitted
+  // here, because `emitWarn` calls `process.exit(0)` and never returns — warning
+  // inline would terminate the process before a collision DENY could be emitted,
+  // flipping a block into an allow (§ stdout discipline, the same reason
+  // `decide()` is pure).
+  //
+  // `null` here means "not a worktree dispatch" and stays silent; ANY other
+  // shape is emitted, including the `{stale: null, skipped: …}` non-measurements
+  // (#1424). The warning still fires on `stale === true` alone — a skipped probe
+  // accuses nobody.
+  const worktreeBase = await worktreeBaseFacts(input, projectDir, sessionId);
+  let staleNote = null;
+  if (worktreeBase !== null) {
+    if (worktreeBase.stale === true) staleNote = staleWorktreeWarning(worktreeBase);
+    try {
+      const { emitEvent, sessionAttribution } = await import(
+        pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'events.mjs')).href
+      );
+      await emitEvent(
+        WORKTREE_BASE_EVENT,
+        { hook: HOOK_NAME, ...worktreeBase, ...sessionAttribution(projectDir) },
+        { repoRoot: projectDir }
+      );
+    } catch { /* observability is best-effort — it never blocks the decision */ }
+  }
+
+  // ONE terminal emit, with the #1413 note folded in where a visible channel is
+  // free. On DENY the dispatch does not happen and `systemMessage` already
+  // carries the ⛔ headline, so the note stays on the debug channel — a stale
+  // base is moot for a dispatch that was just blocked.
+  if (verdict.action === 'deny') {
+    if (staleNote !== null) {
+      try { console.error(`⚠ ${staleNote}`); } catch { /* stderr may be closed */ }
+    }
+    return emitDeny(verdict.reason, verdict.suggestion);
+  }
+  if (verdict.action === 'warn') {
+    return emitWarn(staleNote === null ? verdict.note : `${verdict.note}\n\n${staleNote}`);
+  }
+  if (staleNote !== null) return emitWarn(staleNote);
   return emitAllow();
 }
 
@@ -1309,6 +1683,12 @@ async function main() {
 // symlinked plugin install) while `import.meta.url` is realpath-resolved by
 // node's default loader, so BOTH sides are realpath'd — the same comparison
 // `hooks/post-bash-write-verify.mjs` documents (#938 MED-2).
+//
+// NAMED CEILING (BV-004): kept inline rather than imported — hooks avoid
+// importing `scripts/lib` on the hot path, where every added module is paid on
+// every dispatch. The canonical predicate is `scripts/lib/is-main-module.mjs`;
+// revisit if this hook ever imports that tree for another reason, at which
+// point the copy costs more than the import saves.
 // ---------------------------------------------------------------------------
 function invokedAsScript() {
   const entry = process.argv[1];

package/hooks/skill-invocation-telemetry.mjs

@@ -37,6 +37,7 @@ import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
 import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -209,7 +210,7 @@ async function main() {
 // Self-execution guard — run only when invoked directly (not when imported).
 // ---------------------------------------------------------------------------
 
-const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
   if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);

package/hooks/subagent-telemetry.mjs

@@ -105,14 +105,14 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('subagent-telemetry')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
+import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -593,25 +593,18 @@ function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
  * @returns {number|null} epoch-ms of the matching start, or null
  */
 function findStartTimestampMs(filePath, agentId) {
-  let fd;
   try {
     if (typeof agentId !== 'string' || !agentId.trim()) return null;
     if (!fs.existsSync(filePath)) return null;
 
-    const { size } = fs.statSync(filePath);
-    if (size === 0) return null;
+    const window = readTailWindow(filePath, START_JOIN_TAIL_BYTES);
+    if (window.size === 0) return null;
 
-    const readLen = Math.min(size, START_JOIN_TAIL_BYTES);
-    const from = size - readLen;
-    const buf = Buffer.allocUnsafe(readLen);
-    fd = fs.openSync(filePath, 'r');
-    fs.readSync(fd, buf, 0, readLen, from);
-
-    const lines = buf.toString('utf8').split('\n');
+    const lines = window.text.split('\n');
     // When the window does not cover the whole file, the first element is a
     // record sliced mid-line (possibly mid-UTF-8-sequence). Drop it rather than
     // feed a corrupt fragment to JSON.parse.
-    if (from > 0) lines.shift();
+    if (window.cut) lines.shift();
 
     for (let i = lines.length - 1; i >= 0; i--) {
       const line = lines[i].trim();
@@ -631,10 +624,6 @@ function findStartTimestampMs(filePath, agentId) {
     return null;
   } catch {
     return null;
-  } finally {
-    if (fd !== undefined) {
-      try { fs.closeSync(fd); } catch { /* ignore */ }
-    }
   }
 }
 
@@ -815,5 +804,12 @@ async function main() {
   await appendSubagent(jsonlPath(), record);
 }
 
-// Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('subagent-telemetry')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude.
+  main().catch(() => {}).finally(() => process.exit(0));
+}