session-orchestrator 5.0.0 → 5.2.0

package/hooks/on-stop.mjs

@@ -551,6 +551,39 @@ async function handleSubagentStop(input) {
     } catch { /* probe failed — omit rather than assert `false` */ }
 
     try {
+      // `sidecar_missing` — the DENOMINATOR for every meta-derived field below
+      // (#1289 Befund 2). `agent_type_meta` and `tool_use_id` come from the same
+      // read, so they co-occur perfectly (measured 2026-09-16 over
+      // `.orchestrator/metrics/events.jsonl`: 15.291 `orchestrator.agent.stopped`
+      // records, 542 with `agent_type_meta`, 542 with `tool_use_id`,
+      // both/only-meta/only-tool = 542/0/0). That made the low presence rate look
+      // like a producer defect in the KEY, when 1000/1000 sidecars on this host
+      // carry `agentType`. This flag makes "no sidecar found" visible in the
+      // record instead of indistinguishable from "sidecar found, field absent".
+      //
+      // WHAT THIS KEY IS NOT: a sidecar-LOOKUP failure rate. Re-measured
+      // 2026-09-16 over 15.457 `orchestrator.agent.stopped` records (5086
+      // `transcript_found:false` vs 553 `true`), the false mass is the #939/#949
+      // PHANTOM-STOP class — no subagent ever existed, so there is nothing for
+      // the lookup to find:
+      //   - 0 of 5077 distinct false `agent_id`s have a sidecar ANYWHERE on this
+      //     host (`find ~/.claude/projects -path '*/subagents/agent-*.jsonl'` →
+      //     8626 ids), and 0 have a `SubagentStart` record (2176 starts in
+      //     `.orchestrator/metrics/subagents.jsonl`);
+      //   - 0 records carrying a valid `agent_id` got a null resolver result;
+      //   - the two classes are perfectly bimodal on the type field:
+      //     `false` + no `agent` 5086, `true` + typed 553, off-diagonal 0.
+      // `agent` (the harness `agent_type`) is therefore the ready-made
+      // discriminator — no further key is needed. Do NOT "repair" the derivation
+      // in hooks/_lib/subagent-paths.mjs to chase this rate: it already resolves
+      // 553/553 of the real stops, and a widened one would only start resolving
+      // onto a FOREIGN agent's sidecar. This misreading has now cost three
+      // investigations (#939, the 2026-08-11 ledger re-run, #1289 Befund 2).
+      //
+      // Present ONLY when true, like every other optional key in this payload;
+      // its own probe is inside this try, so a failed `existsSync` omits it and
+      // nothing else (a telemetry fault must never change a decision).
+      if (!existsSync(metaPath)) payload.sidecar_missing = true;
       // One small read, one parse, two fields. `description` is operator prose
       // and is deliberately NOT carried: this payload also travels over the
       // optional Clank webhook unredacted.
@@ -565,7 +598,16 @@ async function handleSubagentStop(input) {
         payload.tool_use_id = meta.toolUseId.trim();
       }
       // A SECOND witness for the type — never merged into `agent`, so the
-      // empty-`agent_type` rate stays measurable.
+      // empty-`agent_type` rate stays measurable. NO FALLBACK MERGE, deliberately:
+      // `payload.agent` already carries the harness's `input.agent_type`, and
+      // filling one from the other would erase exactly the signal this pair
+      // exists to produce.
+      //
+      // REPORTING RULE: the presence rate of this key is only meaningful against
+      // the events whose SIDECAR WAS FOUND — "present on N of M events without
+      // `sidecar_missing`", never N of all `orchestrator.agent.stopped` records.
+      // Measured against all events the rate reads as a producer defect in this
+      // block; against its real denominator it is a lookup-failure rate.
       if (typeof meta?.agentType === 'string' && AGENT_TYPE_META_RE.test(meta.agentType.trim())) {
         payload.agent_type_meta = meta.agentType.trim();
       }

package/hooks/post-bash-write-verify.mjs

@@ -1120,6 +1120,9 @@ async function main() {
 // string compare then reads false and silently no-ops the whole scope-detector
 // under a symlinked `$CLAUDE_PLUGIN_ROOT`. realpath'ing both sides also survives
 // `--preserve-symlinks` (where import.meta.url stays symlinked instead).
+// BV-004 ceiling: kept inline — hooks avoid importing scripts/lib on the hot
+// path; the canonical predicate is scripts/lib/is-main-module.mjs. Revisit if the
+// hook-import-set (hooks/_lib/hook-import-set.json) ever admits scripts/lib here.
 function invokedAsScript() {
   const entry = process.argv[1];
   if (!entry) return false;

package/hooks/pre-auq-clarity.mjs

@@ -778,6 +778,9 @@ async function main() {
 // under a symlinked plugin install) while `import.meta.url` is realpath-resolved
 // by node's default loader, so BOTH sides are realpath'd.
 // ---------------------------------------------------------------------------
+// BV-004 ceiling: kept inline — hooks avoid importing scripts/lib on the hot
+// path; the canonical predicate is scripts/lib/is-main-module.mjs. Revisit if the
+// hook-import-set (hooks/_lib/hook-import-set.json) ever admits scripts/lib here.
 function invokedAsScript() {
   const entry = process.argv[1];
   if (!entry) return false;

package/hooks/pre-bash-issue-budget.mjs

@@ -53,7 +53,7 @@
 import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
-import { findIssueCreateStatements, isLoopedIssueCreate } from './_lib/vcs-create-matcher.mjs';
+import { findIssueCreateStatements, findLoopedIssueCreates } from './_lib/vcs-create-matcher.mjs';
 import {
   loadIssueBudgetConfig,
   resolveIssueBudgetSessionId,
@@ -187,15 +187,39 @@ function resolveToolCallId(input) {
  * entry #N … nothing is lost", which would be false here — an uncountable bulk
  * request is not parked, it is handed back whole.
  *
+ * ## Why the lane is a parameter (#1379)
+ *
+ * Until 2026-09-17 this text said "sits inside a shell loop body (`do … done`)"
+ * on BOTH lanes, so the `xargs` deny (`echo b | xargs -I% glab issue create
+ * --title junk%` — no loop anywhere) sent the operator looking for a loop the
+ * command does not have. Only the lane SENTENCE varies; every other line is
+ * byte-identical across lanes, and tests pin them.
+ *
  * @param {{ "max-per-session": number }} config
+ * @param {{ lane?: "loop"|"xargs"|"mixed" }} [opts]
  * @returns {string}
  */
-function formatLoopDenyReason(config) {
+function formatLoopDenyReason(config, { lane = 'loop' } = {}) {
+  const LANE_SENTENCES = {
+    loop: [
+      'The `issue create` call sits inside a shell loop body (`do … done`), so the cap cannot',
+      'charge it honestly: the word list is expanded by the shell AFTER this hook runs, so',
+      '`for i in $(seq 1 50)` would file 50 issues against a count of 1.',
+    ],
+    xargs: [
+      'The `issue create` call is driven by `xargs`, so the cap cannot charge it honestly: the',
+      'word list arrives on stdin AFTER this hook runs, so `seq 1 50 | xargs` would file 50',
+      'issues against a count of 1.',
+    ],
+    mixed: [
+      'The `issue create` calls are driven by a shell loop body (`do … done`) AND by `xargs`,',
+      'so the cap cannot charge them honestly: both word lists are produced AFTER this hook',
+      'runs, so `seq 1 50 | xargs` would file 50 issues against a count of 1.',
+    ],
+  };
   return [
     'issue-budget: this command creates an UNKNOWN number of issues — refusing to guess.',
-    'The `issue create` call sits inside a shell loop body (`do … done`), so the cap cannot',
-    'charge it honestly: the word list is expanded by the shell AFTER this hook runs, so',
-    '`for i in $(seq 1 50)` would file 50 issues against a count of 1.',
+    ...(LANE_SENTENCES[lane] ?? LANE_SENTENCES.loop),
     '',
     'Nothing was parked as overflow, because nothing is lost: re-issue the create calls as',
     'SEPARATE commands and each one is counted normally against the cap',
@@ -302,18 +326,59 @@ async function main() {
   const config = loadIssueBudgetConfig(projectDir);
   if (config.mode === 'off') return emitAllow();
 
-  // G3b — bulk creation whose multiplicity is not computable (#1145). The
-  // exemption is asked FIRST, through the same classifier chargeIssueBudget
-  // uses, so a looped carryover sweep keeps its unconditional pass. It is asked
-  // on the FIRST issue-create statement's text, which is the very statement
-  // `isLoopedIssueCreate` judges — classifying it on the whole command would
-  // let an exempt NEIGHBOUR statement lift the loop deny.
-  const uncountableBulk =
-    isLoopedIssueCreate(command) && !classifyExemption(statements[0].text).exempt;
+  // G3b — bulk creation whose multiplicity is not computable (#1145). Two
+  // sources, one policy: a LOOP BODY (#1145) and an `xargs`-driven create
+  // (#1289), where the word list arrives on stdin. Both file N issues for one
+  // statement, so both are denied rather than charged 1 — the fix had to land
+  // here and not only in `isLoopedIssueCreate`, because G3 above short-circuits
+  // on `statements.length === 0` and an xargs create used to produce zero
+  // statements, so no loop-side fix could ever run.
+  //
+  // THE INVARIANT (rewritten 2026-09-16): the exemption is classified on the
+  // statement that CAUSED the bulk classification — never on `statements[0]`,
+  // and never on the whole command. A `[Carryover]` create standing NEXT TO an
+  // uncountable one is an unrelated neighbour and must not lift the deny; a
+  // `[Carryover]` create that IS the bulk statement keeps its documented
+  // unconditional pass (session-end's "those are never deferred" promise, which
+  // holds inside a loop too). Measured 2026-09-16 against the previous
+  // `statements[0]` binding, both lanes ALLOW where they must DENY:
+  //   glab issue create --title "[Carryover] real"; echo X | xargs -I% glab issue create --title %
+  //   glab issue create --title "[Carryover] real"; for i in 1 2 3; do glab issue create --title junk$i; done
+  // Same class as the bypass-scoping regression on `matchesBypass` — a matcher
+  // widened per statement while its exemption stayed whole-command
+  // (`.claude/rules/guard-design.md` § "Widening a matcher without narrowing
+  // its bypass", #1106).
+  //
+  // Fail-CLOSED when a command carries SEVERAL bulk statements and only some are
+  // exempt: `some()` over the non-exempt ones denies, because the command as a
+  // whole still files an uncountable number of untemplated issues.
+  //
+  // EVERY loop, not the first (#1379): the loop lane used to contribute at most
+  // ONE entry here, so an exempt FIRST loop was the only loop classified and
+  // every later loop went unjudged. Reproduced 2026-09-17 @ `9e8146b4`:
+  //   for i in 1 2 3; do glab issue create --label carryover --title x$i; done;
+  //   for j in 1 2 3; do glab issue create --title junk$j; done  → ALLOW (count=1)
+  const bulkEntries = [
+    ...findLoopedIssueCreates(command).map((tokens) => ({
+      lane: 'loop',
+      text: tokens.map((t) => t.text).join(' '),
+    })),
+    ...statements.filter((s) => s.bulk).map((s) => ({ lane: 'xargs', text: s.text })),
+  ];
+  const uncountableEntries = bulkEntries.filter((e) => !classifyExemption(e.text).exempt);
+  const uncountableBulk = uncountableEntries.length > 0;
+  // ONE lane resolution for BOTH reports (#1379 follow-up). The deny already
+  // named the lane it fired on; the `warn` undercount notice at the bottom of
+  // main() said "inside a loop body" unconditionally, so the xargs lane — where
+  // no loop exists anywhere in the command — sent the operator looking for one.
+  // Resolved here rather than twice, so the two reports can never disagree.
+  const uncountableLanes = new Set(uncountableEntries.map((e) => e.lane));
+  const uncountableLane =
+    uncountableLanes.size > 1 ? 'mixed' : ([...uncountableLanes][0] ?? 'loop');
   if (uncountableBulk && config.mode === 'strict') {
     // Nothing is charged and nothing is parked — the command is handed back
     // whole, which is what makes unrolling it the correct next action.
-    return emitDeny(formatLoopDenyReason(config));
+    return emitDeny(formatLoopDenyReason(config, { lane: uncountableLane }));
   }
 
   const sessionId = await resolveSessionId(input, projectDir);
@@ -401,11 +466,32 @@ async function main() {
   // to name the undercount out loud — a silent 1-for-N is the exact failure the
   // deny above exists to prevent, and `warn` must not reintroduce it quietly.
   // emitWarn, not stderr: under exit 0 stderr reaches only the debug log (#916).
-  if (uncountableBulk && verdict.decision === 'allow') {
+  //
+  // GATED ON THE BULK STATEMENTS, NEVER ON THE LAST VERDICT (2026-09-17). The
+  // condition used to read `verdict.decision === 'allow'`, i.e. the verdict of
+  // the LAST statement of the chain — so one exempt statement written AFTER an
+  // uncountable one silenced the notice the two paragraphs above declare
+  // mandatory. Reproduced through this hook binary in `mode: warn`:
+  //   for i in 1 2; do glab issue create --title j$i; done; \
+  //     glab issue create --title "[Carryover] z"
+  //   → stdout EMPTY, ledger count=1 exempt=1 (the trailing exempt statement is
+  //     an unrelated neighbour, exactly as in G3b's own invariant); without it,
+  //     the identical loop reported the UNDERCOUNT.
+  // Reaching this point already means no statement blocked and none warned
+  // (both branches above return), so the uncountable bulk statement — non-exempt
+  // by construction of `uncountableEntries` — was charged as 1. The two negated
+  // conditions are kept explicit so a future reordering of those branches cannot
+  // turn this back into a report about the wrong statement.
+  if (uncountableBulk && !blocked && !verdicts.some((v) => v.decision === 'warn')) {
+    const LANE_PHRASES = {
+      loop: 'inside a loop body',
+      xargs: 'driven by `xargs`',
+      mixed: 'inside a loop body and by `xargs`',
+    };
     return emitWarn(
-      `pre-bash-issue-budget: bulk create inside a loop body charged as 1 ` +
+      `pre-bash-issue-budget: bulk create ${LANE_PHRASES[uncountableLane]} charged as 1 ` +
         `(${verdict.count}/${verdict.max}) — the real number of issues this files is not ` +
-        `knowable before the shell expands the word list, so the count is an UNDERCOUNT. ` +
+        `knowable before the word list is expanded, so the count is an UNDERCOUNT. ` +
         `Set \`issue-budget.mode: strict\` to deny this shape instead.`,
     );
   }

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,25 @@ const SHAPE_NONE = 'none';
 /** The per-dispatch observability record (#1092) — see § Observability. */
 const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
 
+/**
+ * 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 +378,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 +398,7 @@ async function bootstrap() {
   ({ readStdin, emitAllow, emitDeny, emitWarn, writeJsonAtomicSync } = modules.io);
   ({ findScopeCollisions } = modules.scopeGate);
   ({ withFileLock } = modules.fileLock);
+  ({ scopeDigest } = modules.scopeEcho);
 }
 
 // ---------------------------------------------------------------------------
@@ -407,8 +436,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 +508,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. */
@@ -980,6 +1052,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 +1132,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 +1160,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,
   });
@@ -1309,6 +1452,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.0.0",
-  "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+  "version": "5.2.0",
+  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
   "keywords": [
@@ -57,6 +57,7 @@
     "test": "node scripts/check-package-manager.mjs && vitest --run",
     "test:coverage": "node scripts/check-package-manager.mjs && vitest --run --coverage",
     "test:watch": "node scripts/check-package-manager.mjs && vitest",
+    "test:pack": "node scripts/check-package-manager.mjs && SO_PACK_TEST=1 vitest --run tests/scripts/pack-install-lifecycle.test.mjs",
     "quality-gate": "node scripts/run-quality-gate.mjs --variant full-gate",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/pi/prompts/autopilot.md

@@ -1,12 +1,12 @@
 ---
-description: Autonomous session-orchestration loop with kill-switches (Phase C-1.b — all 10 kill-switches shipped)
+description: "Use this skill when running an autonomous session-orchestration loop. Chains session-start → session-plan → wave-executor → session-end for N iterations with all 10 kill-switches (SPIRAL, FAILED wave, carryover > 50%, max-hours, max-sessions, resource-overload, token-budget, stall-timeout, sub-threshold confidence, user-abort). Reads Mode-Selector output (Phase B) to decide auto-execute vs. fallback. Writes one autopilot.jsonl record per loop run. Phase C scaffold (issue #277); implementation lives in scripts/lib/autopilot.mjs (Phase C-1 follow-up)."
 argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
 ---
 
 # /autopilot
 
-Use the Session Orchestrator command definition at `commands/autopilot.md`.
+Use the Session Orchestrator skill definition at `skills/autopilot/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/bootstrap.md

@@ -1,12 +1,12 @@
 ---
-description: Scaffold the minimum repo structure required by session-orchestrator
+description: "Use this skill when scaffolding the minimum repository structure required by session-orchestrator. Invoked automatically by the Bootstrap Gate when CLAUDE.md, Session Config, or bootstrap.lock is missing. Also available as /bootstrap for manual invocation. Three intensity tiers: fast (demos/spikes), standard (MVPs), deep (production/team)."
 argument-hint: "[--upgrade <tier>]"
 ---
 
 # /bootstrap
 
-Use the Session Orchestrator command definition at `commands/bootstrap.md`.
+Use the Session Orchestrator skill definition at `skills/bootstrap/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/brainstorm.md

@@ -1,12 +1,12 @@
 ---
-description: Run a lightweight Socratic design dialogue (3-5 AUQ rounds) and write a spec markdown file before any implementation work. Use BEFORE /plan feature when scope/UX is ambiguous.
+description: "Use when you have a feature idea but the scope or UX is still ambiguous — runs a lightweight Socratic design dialogue (3-5 AUQ rounds) and writes a spec markdown file. Use BEFORE /plan feature when product intent needs validation; skip to /plan feature when scope is already clear. HARD-GATE prevents any code work until the design is user-approved."
 argument-hint: "[topic-or-feature-slug]"
 ---
 
 # /brainstorm
 
-Use the Session Orchestrator command definition at `commands/brainstorm.md`.
+Use the Session Orchestrator skill definition at `skills/brainstorm/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/close.md

@@ -4,8 +4,8 @@ description: End session with verification, commits, and documentation
 
 # /close
 
-Use the Session Orchestrator command definition at `commands/close.md`.
+Use the Session Orchestrator skill definition at `skills/close/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/convergence-monitoring.md

@@ -0,0 +1,11 @@
+---
+description: "Monitor iterative improvement loops for convergence. Three signals — shrinking diff, pass-rate plateau, velocity — drive a Stop/Continue/Investigate decision at each inter-wave checkpoint. Distinct from /evolve (retrospective) and session-reviewer (wave output review): convergence-monitoring answers \"are we making progress?\" not \"was the last wave correct?\". Primary consumer: /autoresearch loops and wave-executor inter-wave checkpoints."
+---
+
+# /convergence-monitoring
+
+Use the Session Orchestrator skill definition at `skills/convergence-monitoring/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/debug.md

@@ -1,12 +1,12 @@
 ---
-description: Run a 4-phase systematic debugging investigation before proposing any fix. Iron Law — NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
+description: "Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference."
 argument-hint: "[bug-description-or-issue-ref]"
 ---
 
 # /debug
 
-Use the Session Orchestrator command definition at `commands/debug.md`.
+Use the Session Orchestrator skill definition at `skills/debug/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/discovery.md

@@ -1,12 +1,12 @@
 ---
-description: Systematic quality discovery and issue detection
+description: "Use this skill when running systematic quality discovery and issue detection. Runs modular probes adapted to the project's tech stack, presents findings interactively for user triage, and creates VCS issues for confirmed problems. Invoked standalone via /discovery or embedded in session-end."
 argument-hint: "[all|code|infra|ui|arch|session|audit|vault|feature] [--since <git-ref>] [--full]"
 ---
 
 # /discovery
 
-Use the Session Orchestrator command definition at `commands/discovery.md`.
+Use the Session Orchestrator skill definition at `skills/discovery/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.