session-orchestrator 4.2.0 → 5.0.0

package/scripts/lib/reconcile/writer.mjs

@@ -11,6 +11,9 @@
  * Responsibilities:
  *  - Acquire a per-write file lock (`.orchestrator/rules.lock`) to serialise
  *    concurrent writers — mirrors PSA-005 (withStateMdLock) pattern.
+ *  - Before any write: project the instruction budget after the batch and
+ *    refuse the WHOLE batch (nothing written, nothing stamped) when it would
+ *    breach a ceiling — see `budgetPreflight`.
  *  - For each approved proposal: path-safety guard → STRUCTURAL content gate
  *    (#1015, see {@link frontmatterRefusalReason}) → mkdirSync → atomic
  *    tmp+rename write → stamp the idempotency sidecar terminal via
@@ -54,8 +57,20 @@
  * @module reconcile/writer
  */
 
-import { mkdirSync, writeFileSync, renameSync, appendFileSync, realpathSync, statSync } from 'node:fs';
+import {
+  mkdirSync,
+  mkdtempSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  appendFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
 import { randomBytes } from 'node:crypto';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { withFileLock } from '../file-lock.mjs';
@@ -490,6 +505,228 @@ function isOperatorRejection(item) {
   return typeof item.content === 'string' && item.content.length > 0;
 }
 
+// ---------------------------------------------------------------------------
+// Instruction-budget pre-flight (#1316 follow-up)
+// ---------------------------------------------------------------------------
+
+/** Refusal reason returned when the projected corpus would breach a ceiling. */
+export const BUDGET_REFUSAL_REASON = 'instruction-budget-exceeded';
+
+const BUDGET_HINT =
+  'absorb the approved rule(s) into an existing thematic file under .claude/rules/ ' +
+  '(N provenance pairs in ONE file, globs:/paths: mirrored — docs/rule-authoring.md § Consolidated rules) ' +
+  'and re-run; never raise the ceiling';
+
+/**
+ * @typedef {Object} BudgetRefusal
+ * @property {string} reason    - always {@link BUDGET_REFUSAL_REASON}.
+ * @property {'path-scoped-bytes'|'generated-bytes'|'always-on-bytes'|'directives'} axis
+ * @property {number} current   - the axis value before the write.
+ * @property {number} projected - the axis value after the write.
+ * @property {number} ceiling   - the ceiling the projection breaches.
+ * @property {string} hint
+ */
+
+/**
+ * Project the instruction budget AFTER the pending repo-local writes and refuse
+ * the whole batch if the projection would breach a ceiling.
+ *
+ * WHY A PROJECTION AND NOT WRITE-THEN-ROLLBACK: a rollback has to undo rule
+ * files AND sidecar stamps, and a half-failed rollback is worse than the breach.
+ * Refusing before the first byte lands keeps the failure clean.
+ *
+ * HOW: the guard's own `computeInstructionBudget` runs twice — on the live rules
+ * directory, and on a throwaway overlay (a copy of that directory with the
+ * pending contents written over it). Re-running the guard's code rather than
+ * re-deriving its byte count means the projection cannot disagree with the
+ * verdict: same frontmatter stripping, same `globs:`/provenance predicates,
+ * all four axes, and an update of an existing file lands as its delta by
+ * construction. Ceilings follow `checkInstructionBudget`'s precedence
+ * (Session Config `instruction-budget.*` > module default), and
+ * `enabled: false` / `mode: off` skips the pre-flight — the operator opted out
+ * of the guard.
+ *
+ * REFUSE ONLY WHAT THIS WRITE WORSENS: an axis blocks the batch only when it is
+ * over in the projection AND the write grows it. A corpus that is already over
+ * therefore still accepts a shrinking consolidation — the remedy must never be
+ * blocked by the breach it repairs — and an unrelated pre-existing breach (say,
+ * the hand-authored always-on directive count) does not freeze reconcile.
+ *
+ * CEILING (BV-004): this is a projection of THIS batch against the corpus as it
+ * stands inside the rules lock. It does not cover rule edits made by hand or by
+ * any writer that does not take `.orchestrator/rules.lock`, and it projects
+ * with the Session Config ceilings while `tests/rules/receiving-review.test.mjs`
+ * asserts against the module defaults — so a repo that RAISES its ceiling in
+ * config can pass here and still go red there; that live test stays the second
+ * safety net. It also fails OPEN (one `errors[]` warning, then the write
+ * proceeds) when the guard cannot load or the overlay cannot be built,
+ * because blocking every reconcile write on a broken measurement is the larger
+ * harm. Revisit if a second writer of `.claude/rules/` appears, or if a repo
+ * ever carries a config ceiling above the module default.
+ *
+ * @param {Object} ctx
+ * @param {WriterApprovedItem[]} ctx.approvedItems
+ * @param {PreparedTarget|undefined} ctx.prep - the prepared `repo-local` target.
+ * @param {{repoRoot?: string, baselineRoot?: string}} ctx.roots
+ * @param {string} ctx.repoRoot
+ * @param {string[]} ctx.errors - receives fail-open warnings.
+ * @returns {Promise<BudgetRefusal|null>} null ⇒ proceed with the writes.
+ */
+async function budgetPreflight({ approvedItems, prep, roots, repoRoot, errors }) {
+  if (!prep || !prep.ok) return null;
+
+  // Only what the write loop below would actually put on disk counts: the same
+  // content-type check, structural gate and destination resolution. Errors from
+  // this dry resolution go to a throwaway sink — the write loop reports them.
+  /** @type {Array<{rel: string, content: string}>} */
+  const pending = [];
+  for (const item of approvedItems) {
+    if (!item || typeof item.content !== 'string') continue;
+    if (frontmatterRefusalReason(item.content) !== null) continue;
+    const dest = resolveDest(item, 'repo-local', prep, roots, []);
+    if (dest === null) continue;
+    pending.push({ rel: path.relative(prep.dir, dest), content: item.content });
+  }
+  if (pending.length === 0) return null;
+
+  let overlay = null;
+  try {
+    // Dynamic import keeps the guard out of this module's static graph.
+    const guard = await import('../instruction-budget-guard.mjs');
+    const cfg = guard.loadInstructionBudgetConfig(repoRoot);
+    if (!cfg.enabled || cfg.mode === 'off') return null;
+    // computeInstructionBudget falls back to its module default for any
+    // non-number, so an absent optional key needs no special case here.
+    const ceilings = {
+      ceiling: cfg.ceiling,
+      byteCeiling: cfg['byte-ceiling'],
+      generatedByteCeiling: cfg['generated-byte-ceiling'],
+      pathScopedByteCeiling: cfg['path-scoped-byte-ceiling'],
+    };
+
+    const current = guard.computeInstructionBudget({ repoRoot, rulesDir: prep.dir, ...ceilings });
+
+    overlay = mkdtempSync(path.join(tmpdir(), 'reconcile-budget-'));
+    // The guard reads the rules directory flat (`readdirSync`, `.md` only).
+    for (const name of readdirSync(prep.dir)) {
+      if (!name.endsWith('.md')) continue;
+      try {
+        writeFileSync(path.join(overlay, name), readFileSync(path.join(prep.dir, name), 'utf8'), 'utf8');
+      } catch {
+        /* unreadable or a directory — the guard skips it too */
+      }
+    }
+    for (const { rel, content } of pending) {
+      const dest = path.join(overlay, rel);
+      mkdirSync(path.dirname(dest), { recursive: true });
+      writeFileSync(dest, content, 'utf8');
+    }
+
+    const projected = guard.computeInstructionBudget({ repoRoot, rulesDir: overlay, ...ceilings });
+
+    const axes = [
+      ['path-scoped-bytes', current.bySurface.pathScoped.bytes, projected.bySurface.pathScoped.bytes, projected.pathScopedByteCeiling, projected.overPathScopedBudget],
+      ['generated-bytes', current.bySurface.generated.bytes, projected.bySurface.generated.bytes, projected.generatedByteCeiling, projected.overGeneratedBudget],
+      ['always-on-bytes', current.totalBytes, projected.totalBytes, projected.byteCeiling, projected.overByteBudget],
+      ['directives', current.totalDirectives, projected.totalDirectives, projected.ceiling, projected.overDirectiveBudget],
+    ];
+    for (const [axis, cur, proj, ceiling, over] of axes) {
+      if (over && proj > cur) {
+        return { reason: BUDGET_REFUSAL_REASON, axis, current: cur, projected: proj, ceiling, hint: BUDGET_HINT };
+      }
+    }
+    return null;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    errors.push(`instruction-budget pre-flight could not run (${msg}) — writes proceed unchecked (fail-open)`);
+    return null;
+  } finally {
+    if (overlay !== null) {
+      try {
+        rmSync(overlay, { recursive: true, force: true });
+      } catch {
+        /* a leftover tmp dir is harmless */
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Telemetry (#1307)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ledger name of the rule-write event (issue #1307).
+ *
+ * WHY A SECOND EVENT AND NOT A FIELD ON `orchestrator.reconcile.completed`:
+ * that event is emitted by the `runReconcile` wrapper — BEFORE the operator
+ * approval AUQ and before this module runs at all. A `dry_run: false` record
+ * therefore proves only that the engine ran and merged the candidate store; an
+ * operator who declined every proposal emits a byte-identical record to one who
+ * approved five. The emitter has to sit where the thing it proves happens, and
+ * that is here: after the write pass, in the one module that writes rule files.
+ *
+ * Emitting is NOT writing — the #693 FA2/FA3 brandmauer is untouched. This
+ * module remains the only writer of `.claude/rules/`, and every write it makes
+ * is still an operator-approved item handed in via `approved`.
+ */
+export const RULES_WRITTEN_EVENT = 'orchestrator.reconcile.rules_written';
+
+/**
+ * Record ONE rule-write pass in the repo's event ledger — best-effort.
+ *
+ * ZERO-WRITE IS EMITTED, DELIBERATELY. The alternative (emit only on a
+ * successful write) makes the maintenance loop unable to separate three
+ * materially different outcomes that would all produce NO record: the operator
+ * declined every proposal, every write was REFUSED by a guard (path-safety,
+ * the #1015 content gate, a missing baseline root), and the writer was never
+ * reached at all. `.claude/rules/host-resources.md` § HR-105 is explicit that a
+ * rule whose firing you cannot falsify is not a rule, and the sibling event's
+ * own docs row states the same convention in one line: *"`dry_run` is the
+ * discriminator, not the event's absence"*. So the discriminator here is a
+ * FIELD — `rules_written` against `approved_proposals` — never the absence of a
+ * record. The one case that emits nothing is the caller's true no-op (neither
+ * an approved nor a rejected item), which returns before the lock is taken.
+ *
+ * NEVER THROWS, and never propagates: `emitEvent` throws `EventValidationError`
+ * on a malformed record, and `writeApprovedRules`'s never-throws contract is
+ * older and more load-bearing than this telemetry. A failed emit degrades to a
+ * stderr WARN and the write result is returned unchanged.
+ *
+ * @param {WriteApprovedRulesResult} result
+ * @param {{repoRoot?: string, targets: string[], approvedCount: number}} ctx
+ * @returns {Promise<void>}
+ */
+async function emitRulesWritten(result, ctx) {
+  const { repoRoot } = ctx;
+  // Same refusal as `emitReconcileCompleted` (#1119): with no repoRoot the
+  // ambient `SO_PROJECT_DIR` would receive synthetic records on every test run.
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') return;
+
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    rules_written: result.written,
+    approved_proposals: ctx.approvedCount,
+    rejected_archived: result.archived,
+    write_errors: result.errors.length,
+  };
+  // Allowlisted to the CLOSED {@link TARGET_DIRS} key set before entering the
+  // ledger — `targets` originates in operator-authored Session Config and is
+  // unbounded there, so an unknown value is untrusted text, never a
+  // measurement. Same treatment as `buildReconcilePayload`'s `targets`.
+  const known = Object.keys(TARGET_DIRS);
+  const targets = ctx.targets.filter((t) => known.includes(t));
+  if (targets.length > 0) payload.targets = targets;
+
+  try {
+    const { emitEvent } = await import('../events.mjs');
+    await emitEvent(RULES_WRITTEN_EVENT, payload, { repoRoot });
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`reconcile-writer: ${RULES_WRITTEN_EVENT} emit failed (non-fatal): ${msg}\n`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -532,6 +769,12 @@ function isOperatorRejection(item) {
  * @property {number}   written   - number of rule files successfully written.
  * @property {number}   archived  - number of rejected records appended to the log.
  * @property {string[]} errors    - per-item error strings (never fatal).
+ *
+ * On an instruction-budget refusal (see `budgetPreflight`) the same object also
+ * carries `ok: false` plus every {@link BudgetRefusal} field, `written` and
+ * `archived` are 0, and `errors[]` holds one line naming the axis and the hint —
+ * so a caller that only surfaces `errors[]` still shows the refusal. The success
+ * shape carries no `ok` key.
  */
 
 /**
@@ -618,6 +861,24 @@ export async function writeApprovedRules({
         }
       }
 
+      // Instruction-budget pre-flight — before the first write, inside the
+      // lock so no concurrent reconcile writer moves the corpus between the
+      // projection and the write. A refusal writes NOTHING: no rule file, no
+      // rejected-log line, no sidecar stamp (approved or rejected).
+      const budgetRefusal = await budgetPreflight({
+        approvedItems,
+        prep: prepared.get('repo-local'),
+        roots,
+        repoRoot,
+        errors,
+      });
+      if (budgetRefusal !== null) {
+        errors.push(
+          `${budgetRefusal.reason}: ${budgetRefusal.axis} would go ${budgetRefusal.current} → ${budgetRefusal.projected} (ceiling ${budgetRefusal.ceiling}) — nothing written, no candidate marked processed; ${budgetRefusal.hint}`,
+        );
+        return { written: 0, archived: 0, errors, ok: false, ...budgetRefusal };
+      }
+
       // ── Step 1: write approved rule files ──────────────────────────────────
       for (const item of approvedItems) {
         // Item-level guards run ONCE, before any target loop: content is a
@@ -765,15 +1026,21 @@ export async function writeApprovedRules({
     { timeoutMs: 10000 },
   );
 
-  // If lock acquisition failed, return a zeroed result with the lock error.
-  if (lockResult.ok === false) {
-    return {
-      written: 0,
-      archived: 0,
-      errors: [`lock-${lockResult.reason ?? 'unknown'}`],
-    };
-  }
+  // One emit for BOTH return points (#1307). A lock-acquisition failure is a
+  // zero-write pass like any other and is recorded as one — its `write_errors: 1`
+  // plus a non-zero `approved_proposals` is exactly the shape an operator needs
+  // to see, and an emit placed on the success path alone would drop it silently.
+  const result =
+    lockResult.ok === false
+      ? { written: 0, archived: 0, errors: [`lock-${lockResult.reason ?? 'unknown'}`] }
+      : // Unwrap the result returned from inside the lock body.
+        lockResult.value;
+
+  await emitRulesWritten(result, {
+    repoRoot,
+    targets: effectiveTargets,
+    approvedCount: approvedItems.length,
+  });
 
-  // Unwrap the result returned from inside the lock body.
-  return lockResult.value;
+  return result;
 }

package/scripts/lib/scope-echo.mjs

@@ -0,0 +1,346 @@
+/**
+ * scope-echo.mjs — the RECEIVE-side half of the FILE-SCOPE observability chain (#1092).
+ *
+ * `hooks/pre-task-scope-disjoint.mjs` observes the SEND side: it emits
+ * `orchestrator.wave_dispatch.scope_checked` describing what the guard saw in the
+ * prompt the coordinator handed to the dispatch tool. Nothing in this repo can
+ * observe the other half — whether the `FILE-SCOPE` block reached the agent's
+ * assembled context — because no platform boundary exposes the final prompt
+ * (`docs/scope-collision-guard.md` § 4.2).
+ *
+ * What IS feasible is a self-reported echo: the coordinator appends one
+ * instruction line naming the expected digest of the agent's own scope file, and
+ * the agent ends its report with `SCOPE-DIGEST: <8-hex>`. Post-wave, the
+ * coordinator compares the two and emits
+ * `orchestrator.wave_dispatch.scope_echo_checked`.
+ *
+ * CEILING (BV-004, named deliberately): this is a SOFT signal. The digest is
+ * handed to the agent in the prompt, so an agent that never read the scope block
+ * can still copy the line — it proves the report carried the digest the
+ * coordinator handed it, never that the model read or obeyed the scope. Revisit
+ * when the platform exposes a stable prompt-assembly boundary; at that point the
+ * digest can be computed against the real assembled prompt instead of echoed.
+ *
+ * Pure + stdlib only. Nothing here throws on malformed input — a broken echo
+ * check must never change a wave's outcome.
+ *
+ * Exports:
+ *   scopeDigest(paths)                       → 8-hex string (deterministic, never throws)
+ *   renderScopeEchoInstruction(paths)        → the ONE prompt line to append
+ *   extractScopeEcho(reportText)             → { echoed, digest }
+ *   checkScopeEcho({ scopeFilePath, reportText }) → { echoed, match, expected, actual, reason? }
+ *
+ * CLI:
+ *   node scripts/lib/scope-echo.mjs --scope-file <path> --instruction
+ *   node scripts/lib/scope-echo.mjs --scope-file <path> --report-file <path> \
+ *        [--wave N --agent-id ID --emit]
+ *   node scripts/lib/scope-echo.mjs --help
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { digestSha256Short } from './crypto-digest-utils.mjs';
+
+/** Marker the agent must emit. Case-sensitive by design — a lowercase lookalike is not an echo. */
+export const SCOPE_ECHO_MARKER = 'SCOPE-DIGEST:';
+
+/** Event name for the post-wave verdict. */
+export const SCOPE_ECHO_EVENT = 'orchestrator.wave_dispatch.scope_echo_checked';
+
+/** Max characters retained for `agent_id` in the payload (same clamp as the send-side hook). */
+const AGENT_ID_MAX = 120;
+
+/**
+ * The LAST `SCOPE-DIGEST: <8 hex>` occurrence wins. Optional surrounding backticks
+ * (agents like to fence the line) and trailing whitespace are tolerated. The
+ * negative lookahead is load-bearing: without it `SCOPE-DIGEST: 123456789` would
+ * match its first eight characters and report a false echo.
+ */
+const ECHO_RE = /SCOPE-DIGEST:[ \t]*`{0,3}([0-9a-fA-F]{8})(?![0-9a-fA-F])/g;
+
+/**
+ * Normalize a declared scope into the canonical digest input: trimmed, empties
+ * dropped, deduplicated, sorted, joined with `\n`. Order and incidental
+ * whitespace therefore never change the digest — two coordinators that wrote the
+ * same set of paths in a different order agree.
+ *
+ * @param {unknown} paths
+ * @returns {string[]}
+ */
+function normalizeScopePaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  const out = new Set();
+  for (const entry of paths) {
+    if (typeof entry !== 'string') continue;
+    const trimmed = entry.trim();
+    if (trimmed) out.add(trimmed);
+  }
+  return [...out].sort();
+}
+
+/**
+ * Digest of a declared file scope: sha256 over the normalized paths, first 8 hex.
+ * An empty (or unusable) scope digests the empty string — deterministic, and it
+ * never throws, so a Discovery wave's empty scope has a stable answer rather than
+ * an error path.
+ *
+ * @param {unknown} paths  array of path strings (anything else → empty scope).
+ * @returns {string} 8-character lowercase hex digest.
+ */
+export function scopeDigest(paths) {
+  return digestSha256Short(normalizeScopePaths(paths).join('\n'));
+}
+
+/**
+ * The single line the coordinator appends to an agent prompt after the fenced
+ * `FILE-SCOPE` block. It names the expected digest outright, so the agent only
+ * has to echo it — the check is about the line surviving the round trip, not
+ * about making the agent compute a hash.
+ *
+ * @param {unknown} paths
+ * @returns {string}
+ */
+export function renderScopeEchoInstruction(paths) {
+  return `End your final report with the line: ${SCOPE_ECHO_MARKER} ${scopeDigest(paths)}`;
+}
+
+/**
+ * Find the LAST scope-echo marker in an agent's report.
+ *
+ * The MARKER stays case-sensitive by design (a lowercase `scope-digest:` is not
+ * an echo), but the HEX PAYLOAD is accepted case-insensitively and normalized to
+ * lowercase: `0123ABCD` and `0123abcd` are the same 32 bits, and an agent that
+ * upper-cases the digest has demonstrably carried the line through — which is
+ * the only thing this signal measures.
+ *
+ * @param {unknown} reportText
+ * @returns {{ echoed: boolean, digest: string|null }}
+ */
+export function extractScopeEcho(reportText) {
+  if (typeof reportText !== 'string' || reportText.length === 0) {
+    return { echoed: false, digest: null };
+  }
+  let last = null;
+  ECHO_RE.lastIndex = 0;
+  for (const match of reportText.matchAll(ECHO_RE)) last = match[1].toLowerCase();
+  return last === null ? { echoed: false, digest: null } : { echoed: true, digest: last };
+}
+
+/**
+ * Read a per-agent scope file (`<state-dir>/filescopes/wave-<N>/<agent-id>.json`,
+ * a JSON array of path strings — shape (a) of the two scope shapes, see
+ * CLAUDE.md / AGENTS.md § allowedPaths) and compare its digest against the agent's echo.
+ *
+ * Never throws: an unreadable or wrongly-shaped scope file yields
+ * `{ match: false, reason: 'scope-file-unreadable' }` so the caller logs an
+ * informational line instead of failing a wave.
+ *
+ * An EMPTY declared scope (a Discovery wave, `[]`) is NOT a failed echo: no
+ * instruction line was ever injected, so the agent had nothing to echo. Those
+ * verdicts carry `applicable: false` + `reason: 'scope-empty'` so a consumer can
+ * exclude them from the echo-rate instead of counting every uninstructed agent
+ * as a miss. `applicable` is OMITTED (never `true`) on the instructed path — the
+ * same "absent is not zero" discipline `wave` follows.
+ *
+ * @param {{ scopeFilePath?: string, reportText?: string }} args
+ * @returns {{ echoed: boolean, match: boolean, expected: string|null, actual: string|null, applicable?: boolean, reason?: string }}
+ */
+export function checkScopeEcho({ scopeFilePath, reportText } = {}) {
+  const { echoed, digest } = extractScopeEcho(reportText);
+  /** @type {string|null} */
+  let expected;
+  try {
+    const parsed = JSON.parse(readFileSync(String(scopeFilePath), 'utf8'));
+    if (!Array.isArray(parsed)) throw new TypeError('scope file is not a JSON array');
+    if (normalizeScopePaths(parsed).length === 0) {
+      return {
+        echoed,
+        match: false,
+        expected: null,
+        actual: digest,
+        applicable: false,
+        reason: 'scope-empty',
+      };
+    }
+    expected = scopeDigest(parsed);
+  } catch {
+    return { echoed, match: false, expected: null, actual: digest, reason: 'scope-file-unreadable' };
+  }
+  if (!echoed) return { echoed, match: false, expected, actual: null, reason: 'echo-absent' };
+  const match = digest === expected;
+  return { echoed, match, expected, actual: digest, ...(match ? {} : { reason: 'digest-mismatch' }) };
+}
+
+/**
+ * Build the telemetry payload for a verdict. Counts, closed enums and digests
+ * only — NO path and NO prompt text (issue #1092 acceptance criterion 3): this
+ * record also travels over the optional Clank Event-Bus webhook with no
+ * redaction, and declared paths carry private project slugs.
+ *
+ * NO path here means no path in THIS function's own object literal, before the
+ * standard `sessionAttribution` spread, which adds the session ids like every
+ * event — that spread is applied by the caller and is out of this promise's
+ * scope.
+ *
+ * `wave` follows the "absent is not zero" rule (`docs/events-schema.md`): it is
+ * omitted rather than defaulted when the caller has no wave number. `applicable`
+ * follows the same rule in the other direction — it is emitted ONLY as `false`,
+ * for a verdict whose agent was never instructed (empty declared scope), so a
+ * consumer computing an echo-rate can filter those rows out. Its absence means
+ * "instructed", never "unknown". (Events-schema row owned elsewhere: the
+ * `orchestrator.wave_dispatch.scope_echo_checked` catalogue entry needs an
+ * `applicable` field row.)
+ *
+ * @param {{ echoed: boolean, match: boolean, expected: string|null, actual: string|null, applicable?: boolean, reason?: string }} verdict
+ * @param {{ wave?: unknown, agentId?: unknown }} [meta]
+ * @returns {Record<string, unknown>}
+ */
+export function scopeEchoPayload(verdict, meta = {}) {
+  const wave = Number(meta.wave);
+  const agentId = typeof meta.agentId === 'string' ? meta.agentId.slice(0, AGENT_ID_MAX) : null;
+  return {
+    ...(Number.isFinite(wave) && wave > 0 ? { wave } : {}),
+    ...(agentId ? { agent_id: agentId } : {}),
+    echoed: verdict.echoed,
+    match: verdict.match,
+    ...(verdict.applicable === false ? { applicable: false } : {}),
+    expected_digest: verdict.expected ?? null,
+    actual_digest: verdict.actual ?? null,
+    ...(verdict.reason ? { reason: verdict.reason } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/** `--help` text. Exit codes are named here per `.claude/rules/cli-design.md` § Discoverability. */
+const USAGE = `Usage:
+  scope-echo --scope-file <path> --instruction
+      Print the ONE prompt line instructing an agent to echo its scope digest.
+      Prints nothing for an empty or unreadable scope file.
+
+  scope-echo --scope-file <path> [--report-file <path>] [--wave N]
+             [--agent-id ID] [--emit]
+      Compare the agent report's SCOPE-DIGEST echo against the scope file and
+      print the verdict payload as JSON on stdout. --emit additionally appends
+      an ${SCOPE_ECHO_EVENT} row to .orchestrator/metrics/events.jsonl
+      (best-effort: a failed emit never changes the verdict or the exit code).
+
+  scope-echo --help
+
+Exit codes: 0 for every verdict, 1 for a missing --scope-file.
+`;
+
+/**
+ * Minimal `--flag value` / `--flag` parser (no dependency, same shape as the
+ * other `scripts/lib/*` CLIs in this repo).
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, string|boolean>}
+ */
+function parseArgv(argv) {
+  /** @type {Record<string, string|boolean>} */
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('--')) {
+      out[key] = next;
+      i += 1;
+    } else {
+      out[key] = true;
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} [argv]
+ * @returns {Promise<number>} process exit code: 0 for every verdict (this is an
+ *   observability tool — a broken echo check never fails a wave), or 1 for a
+ *   missing `--scope-file`, which is a USER error per `.claude/rules/cli-design.md`
+ *   (1 = user/input error; 2 is reserved for system errors).
+ */
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgv(argv);
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const scopeFilePath = typeof args['scope-file'] === 'string' ? args['scope-file'] : '';
+  if (!scopeFilePath) {
+    process.stderr.write('scope-echo: --scope-file <path> is required\n');
+    process.stderr.write(USAGE);
+    return 1;
+  }
+
+  if (args.instruction) {
+    let paths = [];
+    try {
+      const parsed = JSON.parse(readFileSync(scopeFilePath, 'utf8'));
+      if (Array.isArray(parsed)) paths = parsed;
+    } catch {
+      // Unreadable scope file → no instruction. Silent on stdout, because the
+      // caller splices stdout straight into the prompt. But it must NOT be
+      // silent altogether: a corrupt scope file and a legitimate empty Discovery
+      // scope both produced exit 0 with no output at all, so the operator could
+      // not tell an injected-nothing-by-design run from a broken one. One stderr
+      // line separates them (#1092 review R3).
+      process.stderr.write(
+        `scope-echo: scope file unreadable (${scopeFilePath}) — no echo line injected\n`,
+      );
+      return 0;
+    }
+    if (paths.length === 0) return 0;
+    process.stdout.write(`${renderScopeEchoInstruction(paths)}\n`);
+    return 0;
+  }
+
+  const reportFile = typeof args['report-file'] === 'string' ? args['report-file'] : '';
+  /** @type {string} */
+  let reportText;
+  try {
+    reportText = reportFile ? readFileSync(reportFile, 'utf8') : '';
+  } catch {
+    reportText = '';
+  }
+
+  const verdict = checkScopeEcho({ scopeFilePath, reportText });
+  const payload = scopeEchoPayload(verdict, {
+    wave: args.wave,
+    agentId: typeof args['agent-id'] === 'string' ? args['agent-id'] : undefined,
+  });
+
+  if (args.emit) {
+    try {
+      const repoRoot = process.cwd();
+      const { emitEvent, sessionAttribution } = await import('./events.mjs');
+      await emitEvent(
+        SCOPE_ECHO_EVENT,
+        { ...payload, ...sessionAttribution(repoRoot) },
+        { repoRoot },
+      );
+    } catch (err) {
+      // Telemetry never changes the verdict (same discipline as the send-side
+      // hook): an unwritable ledger — a full disk, or `events.jsonl` existing as
+      // a DIRECTORY — still prints the verdict on stdout and still exits 0.
+      process.stderr.write(`scope-echo: emit failed — ${err?.message ?? err}\n`);
+    }
+  }
+
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  return 0;
+}
+
+const invokedAsCli =
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+
+if (invokedAsCli) {
+  process.exitCode = await main();
+}