session-orchestrator 3.21.0 → 3.23.0

package/scripts/run-quality-gate.mjs

@@ -277,8 +277,22 @@ if (!existsSync(gatePath)) {
   die(`Gate script not found: ${gatePath}`);
 }
 
+// `npm_config_loglevel` is INHERITED by every descendant, and the pre-push hook
+// invokes this script as `npm run --silent quality-gate` — which sets it to
+// `silent`. That level then reached the gate's own children: `npm pack
+// --dry-run` emitted ZERO `npm notice` lines instead of 818 (measured
+// 2026-08-22), so the release leakage test saw an empty listing, and several
+// validate-plugin/e2e tests that shell out to npm went red the same way. Every
+// one of them passes under a bare `npm test` and fails only INSIDE the gate,
+// which is the hardest shape to diagnose and cost an hour of chasing phantoms.
+//
+// Pinned rather than deleted: an explicit level makes the gate's children
+// independent of how the gate itself was invoked. `--silent` still does its real
+// job — keeping THIS process's stdout to the single JSON envelope — because the
+// children's output is captured by `runCheck`, never streamed.
 const env = {
   ...process.env,
+  npm_config_loglevel: 'notice',
   TYPECHECK_CMD,
   TEST_CMD,
   LINT_CMD,

package/scripts/token-audit.sh

@@ -141,8 +141,15 @@ if [ -f "$CLAUDE_SETTINGS" ]; then
         fi
     fi
 
-    # Count enabled plugins
-    plugin_count=$(grep -c ': true' "$CLAUDE_SETTINGS" 2>/dev/null || echo "0")
+    # Count enabled plugins.
+    # `|| true` rather than `|| echo "0"`: grep -c ALREADY prints 0 on no-match and
+    # still exits 1, so an echo fallback appends a second line — the capture becomes
+    # "0\n0", which every numeric test downstream rejects (bash-harness-pitfalls.md §1).
+    plugin_count=$(grep -c ': true' "$CLAUDE_SETTINGS" 2>/dev/null || true)
+    # NOTE: after the :-0 default an unreadable file prints the same as "zero
+    # plugins" — accepted, the only consumer is the informational echo below.
+    # The #1077 fix here is the removed double-"0" line, not a failure sentinel.
+    plugin_count=${plugin_count:-0}
     echo "  Enabled plugins: $plugin_count"
 fi
 echo ""

package/scripts/validate-plugin.mjs

@@ -244,6 +244,9 @@ if (runCheck('check-pi-package.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-pi-prompts.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-cursor-adapter.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-session-plan-routing.mjs') !== 0) checkFailed = 1;
 
@@ -259,6 +262,9 @@ if (runCheck('check-owner-leakage.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-rules.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-auq-clarity.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 

package/scripts/validate-wave-scope.mjs

@@ -115,6 +115,11 @@ function die(msg, code = 1) {
  * inherit it: a swallowed flag is silent (the mode never runs, and the caller
  * believes it did), whereas this refusal is loud and one line long.
  *
+ * An EMPTY value is the same failure class and is refused for the same reason.
+ * `--assert-disjoint ""` is what a failed `$(...)` capture of the materializer's
+ * stdout produces; since the mode is gated on a truthy path, the empty string
+ * silently skipped the collision check and still exited 0 (#1083).
+ *
  * @param {string[]} argv
  * @param {number} i - index of the FLAG token
  * @param {string} flag - the flag name, for the error message
@@ -122,7 +127,7 @@ function die(msg, code = 1) {
  */
 function flagValue(argv, i, flag) {
   const value = argv[i + 1];
-  if (value === undefined || value.startsWith('--')) {
+  if (value === undefined || value === '' || value.startsWith('--')) {
     die(`${flag} requires a file-path argument`, 1);
   }
   return value;
@@ -247,6 +252,72 @@ function validateRequired(obj, errors) {
   }
 }
 
+/**
+ * Shape-check ONE optional identifier field: present ⇒ a non-empty string.
+ *
+ * Returns whether the key was PRESENT at all (regardless of validity), so the
+ * caller can distinguish "absent" from "present but malformed" — the two need
+ * different treatment and only the first is a warning.
+ *
+ * An EMPTY string is an error rather than a second flavour of absent, for the
+ * reason `sessionAttribution()` (scripts/lib/events.mjs) already states about
+ * omitting the key: an empty id satisfies a truthiness check while attributing
+ * to nothing. A reader comparing `manifest.session === <own session id>` would
+ * then treat the manifest as FOREIGN (ignore it) where the writer meant
+ * UNBOUND (enforce it) — the two dispositions are opposites, so the ambiguity
+ * is not cosmetic. Absence is the only honest encoding of "not session-bound".
+ *
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @param {string[]} errors
+ * @returns {boolean} true when the key is present (valid or not)
+ */
+function validateOptionalSessionId(obj, key, errors) {
+  if (!(key in obj) || obj[key] === undefined) return false;
+  const value = obj[key];
+  const t = value === null ? 'null' : typeof value;
+  if (t !== 'string') {
+    errors.push(`${key} must be a non-empty string, got type: ${t}`);
+    return true;
+  }
+  if (/** @type {string} */ (value).length === 0) {
+    errors.push(
+      `${key} must be a non-empty string, got: "" — an empty id attributes to nothing; omit the key entirely to declare the manifest unbound`,
+    );
+  }
+  return true;
+}
+
+/**
+ * Validate the OPTIONAL session binding (#1123): `session` (the raw
+ * `session_id` of the session that WROTE this manifest) and its human-readable
+ * twin `semantic_session`. Both come from one `sessionAttribution(repoRoot)`
+ * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest.
+ *
+ * Deliberately NOT part of {@link validateRequired}, and that is a compatibility
+ * constraint rather than a preference: `wave-scope.json` is a shared
+ * working-copy artefact, every manifest written before #1123 lacks the field,
+ * and the pre-union skeleton of § Scope Manifest 3.3 is fed through this very
+ * validator before the union exists. Requiring it would reject manifests the
+ * documented procedure itself produces. The absent case therefore WARNS — the
+ * flip to an error belongs to a later release, once no legacy writer remains.
+ *
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ */
+function validateSession(obj, errors, warnings) {
+  const present = validateOptionalSessionId(obj, 'session', errors);
+  validateOptionalSessionId(obj, 'semantic_session', errors);
+  if (!present) {
+    warnings.push(
+      'no session field — manifest is not session-bound (legacy, #1123), so every session sharing this ' +
+        'working copy is enforced against it. The writer derives it from sessionAttribution() — see ' +
+        'skills/wave-executor/wave-loop.md § Scope Manifest.',
+    );
+  }
+}
+
 /**
  * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
  * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
@@ -678,6 +749,7 @@ function validate(
   const warnings = [];
 
   validateRequired(obj, errors);
+  validateSession(obj, errors, warnings);
   validateAllowedPaths(obj, errors, warnings);
   validateBlockedCommands(obj, errors);
   validateGates(obj, errors);

package/scripts/vault-backfill.mjs

@@ -25,12 +25,12 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 
 import {
   assertGlabExists, setVerbose as setGlabVerbose,
-  listGroupRepos, checkVaultYaml, fetchRepoOwner,
+  listGroupRepos, checkVaultYaml,
 } from './lib/vault-backfill/glab.mjs';
 
 import {
@@ -155,11 +155,25 @@ function createVaultFolderStub(vaultDir, slug) {
 
 // ── Process one repo ──────────────────────────────────────────────────────────
 
+/** Derive the complete parent namespace from a canonical GitLab project path. */
+function parentNamespace(repoPath) {
+  if (typeof repoPath !== 'string') return 'unknown';
+
+  const segments = repoPath.split('/');
+  if (
+    segments.length < 2 ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..')
+  ) {
+    return 'unknown';
+  }
+
+  return segments.slice(0, -1).join('/');
+}
+
 function processRepo(entry, vaultDir, templateContent) {
   const { path: repoPath, slug, tier, visibility, group, id } = entry;
   const humanName = slugToHumanName(slug);
-
-  const owner = applyWrites ? fetchRepoOwner(id) : 'unknown';
+  const owner = parentNamespace(repoPath);
 
   let renderedContent;
   try {
@@ -184,7 +198,20 @@ function processRepo(entry, vaultDir, templateContent) {
   }
 
   // Apply: write to staging directory at <out-dir>/<group>/<repo>/.vault.yaml
-  const writePath = join(outDir, repoPath, '.vault.yaml');
+  const writePath = resolve(outDir, repoPath, '.vault.yaml');
+  const writePathRelativeToOutDir = relative(outDir, writePath);
+  if (
+    writePathRelativeToOutDir === '..' ||
+    writePathRelativeToOutDir.startsWith(`..${sep}`) ||
+    isAbsolute(writePathRelativeToOutDir)
+  ) {
+    const error = 'refusing to write outside staging directory';
+    emitAction('write-failed', '', { error });
+    process.stderr.write(`[vault-backfill] ERROR: ${error}\n`);
+    hadWriteError = true;
+    return;
+  }
+
   try {
     mkdirSync(dirname(writePath), { recursive: true });
     writeFileSync(writePath, renderedContent, 'utf8');

package/scripts/vault-mirror.mjs

@@ -56,6 +56,7 @@ import { createReadStream } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 
 import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
+import { emitMirrorEvent, emitMirrorRunEvent } from './lib/vault-mirror/telemetry.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
@@ -105,6 +106,43 @@ export function _normalizeRemote(url) {
     .replace(/\/+$/, '');
 }
 
+// ── Mirror telemetry (#1116) ──────────────────────────────────────────────────
+//
+// The mirror run itself used to be SILENT in `.orchestrator/metrics/events.jsonl`
+// (measured 2026-08-23: `jq -r '.event' … | grep -icE 'board|mirror'` → 0 of
+// 28 387 records; the only event this CLI emitted was
+// `orchestrator.secret_masker.applied`). The expensive consequence is the
+// `skipped-invalid` path below: a schema-invalid record is reported on stdout
+// and the process still exits 0, so the affected session ends up WITHOUT a vault
+// note and nothing durable records which one.
+//
+// Design constraints, all load-bearing:
+//   - Additive only. The stdout JSON protocol is untouched; consumers parse it.
+//   - Best-effort. A telemetry failure must never fail a mirror run, so every
+//     emit is wrapped and its rejection swallowed (same posture as the masker
+//     emit at the end of main()).
+//   - "Absent is not zero" (docs/events-schema.md): a field that was not
+//     measured is OMITTED, never written as 0/null. Hence no `path` key here —
+//     these emit sites are reached BEFORE any target path is resolved, so there
+//     is no path to report. `record_id` is likewise omitted when the record
+//     carries neither `id` nor `session_id`; `line` is the fallback locator that
+//     is always measured.
+//   - Same ledger as the masker emit: `emitEvent` is called 2-arg so both events
+//     from one run resolve the SAME destination (`SO_PROJECT_DIR`, i.e.
+//     `CLAUDE_PROJECT_DIR` or the CWD walk-up). This CLI has no repo-root flag
+//     and deriving one from `--source` would split a single run's telemetry
+//     across two ledgers.
+//
+// #1147 moved both emitters into `scripts/lib/vault-mirror/telemetry.mjs` and
+// widened the coverage from "the two skipped-invalid branches" to "every entry,
+// plus one run-level roll-up":
+//   - `emitMirrorEvent` is now also called from `process.mjs`'s 18 `emitAction`
+//     sites, so `created`/`updated`/every `skipped-*` gets a record too.
+//   - `emitMirrorRunEvent` adds the DENOMINATOR. Per-entry records alone cannot
+//     distinguish "healthy run over an empty source" from "the emitter is
+//     broken" — both write nothing (HR-105). The run event is emitted
+//     unconditionally, so `total: 0` is a measured zero.
+
 // ── CLI argument parsing ──────────────────────────────────────────────────────
 //
 // Migrated to scripts/lib/cli-flags.mjs (#510). Behaviour changes vs prior
@@ -285,11 +323,115 @@ if (kind !== 'learning' && kind !== 'session') {
 // imports) so they are import-safe and unit-testable; see _resolveCanonicalSuffix
 // / _normalizeRemote there (#607 D2).
 
+// ── Run-level accounting + run close-out (#1147) ──────────────────────────────
+//
+// Deliberately OUTSIDE main(): the run event's whole contract is that it is
+// written ONCE PER RUN and that its ABSENCE is the broken-emitter signal
+// (HR-105). Six exits bypass main's normal tail — the three PRE-LOOP aborts at
+// the top of main (missing vault-dir, non-canonical vault, missing source), the
+// malformed-JSON abort and the filesystem-error abort inside the loop (all five
+// `process.exit`, which no `finally` and no `catch` can intercept), and the
+// top-level `main().catch`, which runs in a scope where main's locals no longer
+// exist. Keeping the counters and the emitter out here is what lets all six
+// close the run out through ONE function instead of each re-deriving the
+// payload.
+const runState = {
+  /** Non-blank JSONL lines the run ATTEMPTED — the denominator. */
+  total: 0,
+  /** Entries that produced `skipped-invalid` (validation error or mapper crash). */
+  skippedInvalid: 0,
+  /** Per-`action` tally, keyed by the same strings the entries wrote to stdout. */
+  actions: new Map(),
+  /** Latch: the run may only be closed out once. */
+  finished: false,
+};
+
+/** Count one entry action into {@link runState}. Ignores a non-string action. */
+const tally = (action) => {
+  if (typeof action !== 'string' || action.length === 0) return;
+  runState.actions.set(action, (runState.actions.get(action) ?? 0) + 1);
+};
+
+/**
+ * Close the run out: emit the run-level roll-up AND the masking roll-up,
+ * exactly once. Never throws, never exits — the caller owns the exit code.
+ *
+ * Both emits are documented as unconditional, and both used to sit only on the
+ * happy tail: an abort skipped them, so the very runs an operator most wants
+ * counted were the ones that vanished from the ledger, in the one shape
+ * ("no record") that the docstring reserves for a broken emitter.
+ *
+ * @param {'missing-vault-dir'|'vault-not-canonical'|'missing-source'|'malformed-json'|'filesystem-error'|'unexpected-error'} [aborted]
+ *   Omitted on a complete run. When present it LABELS the counters as partial:
+ *   every line after the abort was never attempted, so the classes no longer
+ *   partition `total`. On the three PRE-LOOP values (#1151) nothing was
+ *   attempted at all — `total` is a measured 0 and the label is what separates
+ *   "never started" from "ran over an empty source".
+ * @returns {Promise<void>}
+ */
+async function finishRun(aborted) {
+  if (runState.finished) return;
+  runState.finished = true;
+
+  const countOf = (action) => runState.actions.get(action) ?? 0;
+  const actionBreakdown = Object.fromEntries(runState.actions);
+  await emitMirrorRunEvent({
+    kind,
+    total: runState.total,
+    created: countOf('created'),
+    updated: countOf('updated'),
+    // Every non-failure skip class, summed from the SAME map the breakdown is
+    // built from — `skipped-invalid` is deliberately excluded and reported as
+    // `failed`, because those are the entries whose session silently ends up
+    // without a vault note.
+    skipped: [...runState.actions].reduce(
+      (sum, [action, n]) =>
+        action.startsWith('skipped-') && action !== 'skipped-invalid' ? sum + n : sum,
+      0,
+    ),
+    failed: runState.skippedInvalid,
+    actionBreakdown,
+    dryRun,
+    ...(aborted ? { aborted } : {}),
+  });
+
+  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
+  //
+  // Emitted here, at the END of the run, rather than at the lazy build site
+  // inside process.mjs. The build site is only reached once a record is actually
+  // processed, so a run over an empty/fully-skipped source would emit nothing and
+  // "the masker never ran" would be indistinguishable from "this channel has no
+  // masker wired".
+  //
+  // Counts only — never a needle, never a prefix of one, never masked text.
+  // Best-effort: a telemetry write must never be the reason a mirror run fails.
+  try {
+    const maskerStats = getMaskerStats();
+    await emitEvent('orchestrator.secret_masker.applied', {
+      channel: 'vault-mirror',
+      needle_count: maskerStats.needleCount,
+      records: maskerStats.records,
+      hits: maskerStats.hits,
+      dry_run: dryRun,
+    });
+  } catch {
+    // Silent no-op — see the note above.
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
+  // The three PRE-LOOP aborts below (#1151) close the run out through the same
+  // `finishRun` every other exit uses. They are the runs that never reached
+  // their first entry — a bad vault-dir, a wrong vault, a missing source — and
+  // until now they were the only outcomes that left NO record at all, which is
+  // the one shape the run event reserves for a broken emitter. Their counters
+  // are all `0`, and `aborted` is what makes that zero readable as "never
+  // started" rather than "ran over an empty source".
   if (!existsSync(resolve(vaultDir))) {
     process.stderr.write(`vault-mirror: vault-dir not found: ${vaultDir}\n`);
+    await finishRun('missing-vault-dir');
     process.exit(2);
   }
 
@@ -307,12 +449,14 @@ async function main() {
       process.stderr.write(
         `vault-mirror: refusing to mirror — "${vaultDir}" is not the canonical Meta-Vault (expected git origin ending in one of: ${canonicalSuffixes.join(', ')}; got ${got})\n`,
       );
+      await finishRun('vault-not-canonical');
       process.exit(2);
     }
   }
 
   if (!existsSync(resolve(source))) {
     process.stderr.write(`vault-mirror: source file not found: ${source}\n`);
+    await finishRun('missing-source');
     process.exit(2);
   }
 
@@ -328,7 +472,13 @@ async function main() {
   }
 
   let lineNum = 0;
-  let skippedInvalidCount = 0;
+  // The run-level denominator lives in `runState` above: `runState.total` counts
+  // every NON-BLANK line the run attempted, so
+  // `created + updated + skipped + failed === runState.total` for any run that
+  // does not abort — and an aborted run says so with the `aborted` field rather
+  // than publishing a partial count as a complete one. The breakdown is keyed by
+  // the same `action` string the entry wrote to stdout, so no second vocabulary
+  // is introduced.
   const ctx = {
     vaultDir,
     dryRun,
@@ -343,21 +493,30 @@ async function main() {
     lineNum++;
     const trimmed = line.trim();
     if (!trimmed) continue;
+    runState.total++;
 
     let entry;
     try {
       entry = JSON.parse(trimmed);
     } catch (err) {
       process.stderr.write(`vault-mirror: malformed JSON on line ${lineNum}: ${err.message}\n`);
+      // Close the run out BEFORE exiting: `process.exit` runs no `finally`, so
+      // without this the abort is the one outcome that leaves no run record —
+      // exactly the shape reserved for a broken emitter.
+      await finishRun('malformed-json');
       process.exit(1);
     }
 
     try {
-      if (kind === 'learning') {
-        await processLearning(entry, lineNum, ctx);
-      } else {
-        await processSession(entry, lineNum, ctx);
-      }
+      // Both processors return the `action` string they emitted (every one of
+      // their exit paths is an `emitAction` call), so the tally needs no second
+      // census of the 18 call sites in process.mjs — a census that would go
+      // stale the first time a branch is added.
+      const action =
+        kind === 'learning'
+          ? await processLearning(entry, lineNum, ctx)
+          : await processSession(entry, lineNum, ctx);
+      tally(action);
     } catch (err) {
       // Validation errors (missing required fields) → per-entry skip, not a global failure
       if (err.message.startsWith('vault-mirror:')) {
@@ -366,7 +525,17 @@ async function main() {
         process.stdout.write(
           JSON.stringify({ action: 'skipped-invalid', path: null, kind, id: entryId }) + '\n',
         );
-        skippedInvalidCount++;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: lineNum,
+          recordId: entryId,
+          skipClass: 'validation',
+          reason: err.message,
+          dryRun,
+        });
         continue;
       }
       // #718: discriminate genuine filesystem/system errors (which must still
@@ -395,47 +564,43 @@ async function main() {
             reason: 'mapper-crash',
           }) + '\n',
         );
-        skippedInvalidCount++;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: lineNum,
+          recordId: entryId,
+          skipClass: 'mapper-crash',
+          reason: err.message,
+          dryRun,
+        });
         continue;
       }
       // Unexpected filesystem errors → fatal
       process.stderr.write(`vault-mirror: filesystem error on line ${lineNum}: ${err.message}\n`);
+      await finishRun('filesystem-error');
       process.exit(2);
     }
   }
 
-  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
+  // ── Run close-out (#1147) ───────────────────────────────────────────────────
   //
-  // Emitted UNCONDITIONALLY, exactly once per channel run, and HERE — at the end
-  // of the run rather than at the lazy build site inside process.mjs. The build
-  // site is only reached once a record is actually processed, so a run over an
-  // empty/fully-skipped source would emit nothing and "the masker never ran" would
-  // be indistinguishable from "this channel has no masker wired". Placed BEFORE
-  // the --strict-schema abort so a failing run still reports its masking posture.
-  //
-  // Counts only — never a needle, never a prefix of one, never masked text.
-  // Best-effort: a telemetry write must never be the reason a mirror run fails.
-  try {
-    const maskerStats = getMaskerStats();
-    await emitEvent('orchestrator.secret_masker.applied', {
-      channel: 'vault-mirror',
-      needle_count: maskerStats.needleCount,
-      records: maskerStats.records,
-      hits: maskerStats.hits,
-      dry_run: dryRun,
-    });
-  } catch {
-    // Silent no-op — see the note above.
-  }
+  // The happy tail. Both roll-ups live in `finishRun` above, which every abort
+  // path also calls, so "the run ended" is emitted from ONE place regardless of
+  // HOW it ended. Placed BEFORE the --strict-schema abort so a failing run still
+  // reports its denominator — that run is precisely the one an operator wants
+  // counted.
+  await finishRun();
 
   // --strict-schema: abort with exit 1 when any entry was skipped-invalid.
   // Useful in CI to catch producer-side schema drift early (issue #249).
-  if (strictSchema && skippedInvalidCount > 0) {
+  if (strictSchema && runState.skippedInvalid > 0) {
     process.stdout.write(
-      JSON.stringify({ action: 'strict-schema-abort', skipped: skippedInvalidCount, kind }) + '\n',
+      JSON.stringify({ action: 'strict-schema-abort', skipped: runState.skippedInvalid, kind }) + '\n',
     );
     process.stderr.write(
-      `vault-mirror: --strict-schema: ${skippedInvalidCount} entries failed validation — exiting 1\n`,
+      `vault-mirror: --strict-schema: ${runState.skippedInvalid} entries failed validation — exiting 1\n`,
     );
     process.exit(1);
   }
@@ -448,8 +613,12 @@ async function main() {
   }
 }
 
-  main().catch((err) => {
+  main().catch(async (err) => {
     process.stderr.write(`vault-mirror: unexpected error: ${err.message}\n`);
+    // Same reason as the two in-loop aborts: an unexpected throw is a run that
+    // ENDED, and the ledger has to say so. `finishRun` never throws, so this
+    // cannot turn a diagnosable crash into a silent one.
+    await finishRun('unexpected-error');
     process.exit(2);
   });
 }

package/skills/_shared/monitor-patterns.md

@@ -36,7 +36,17 @@ the GitHub mirror's main-branch SHA so the operator can confirm parity.
 ```bash
 prev=""
 while true; do
-  s=$(glab ci status -R <OWNER>/<REPO> --output json 2>/dev/null || echo '{"jobs":[]}')
+  # Fallback carries an `error` key, NOT '{"jobs":[]}': an empty job list is a
+  # legitimate glab answer, so it makes a dead CLI read as "pipeline with no jobs"
+  # and the watch goes silent (LM-002: silence is not success).
+  s=$(glab ci status -R <OWNER>/<REPO> --output json 2>/dev/null || echo '{"error":"glab-ci-status-failed"}')
+  # Anything that is not a jobs-carrying object — the sentinel above, or raw
+  # non-JSON glab noise — becomes a visible `error:` line, never silence.
+  if ! jq -e 'type=="object" and has("jobs")' <<<"$s" >/dev/null 2>&1; then
+    echo "$(date -u +%H:%M:%SZ) error: glab ci status unusable — $(printf '%.60s' "$s")"
+    sleep 30
+    continue
+  fi
   cur=$(jq -r '.jobs[] | select(.status!="running" and .status!="pending") | "\(.name): \(.status)"' <<<"$s" 2>/dev/null | sort)
   comm -13 <(echo "$prev") <(echo "$cur")
   prev=$cur
@@ -50,10 +60,16 @@ done
 ```
 
 **Coverage.** Emits a line for each job transitioning out of `running` /
-`pending`. Terminates when **all** jobs are in a terminal state (`success`,
-`failed`, `canceled`, `skipped`). The final line prints the GitHub mirror
-SHA — silence at the end means glab JSON parsing failed (the `||` fallbacks
-prevent the whole loop from dying).
+`pending`, **plus an `error:` line on every iteration where glab produced
+nothing usable** — a dead CLI, an auth expiry, or a network drop surfaces as a
+notification rather than as absence. Terminates when **all** jobs are in a
+terminal state (`success`, `failed`, `canceled`, `skipped`). The final line
+prints the GitHub mirror SHA. Silence now carries exactly one meaning: the
+pipeline is running and no job has changed state.
+
+If you feed this snippet's output through a downstream `grep -E` filter, the
+alternation must include `error` alongside the job-status tokens — the failure
+signature is a word, not an absence.
 
 **Probed 2026-08-14 (glab 1.91.0), three corrections — #1022.** The snippet
 above was silence-is-not-success in its own right until that date, and each
@@ -74,6 +90,16 @@ half failed into the next one's fallback:
   terminal test against `{"jobs":[]}` (exit 1 = keep watching) versus the old
   form against `[]` (exit 0 = break).
 
+**Amended 2026-08-24 — #1077.** The `{"jobs":[]}` fallback the third bullet
+describes was still *indistinguishable from a real answer*: a pipeline can
+legitimately report zero jobs, so a dead glab produced a well-formed payload,
+no `error`, and no output. Non-terminal is not the same as visible. The
+fallback is now `{"error":"glab-ci-status-failed"}` plus the shape guard at the
+top of the loop, and the `(.jobs|length) > 0` terminal guard stays as the
+second line of defence for a genuine zero-job response. Probed: the sentinel
+and raw non-JSON glab noise both emit the `error:` line;
+`{"jobs":[],"pipeline":{}}` and a populated payload both take the normal path.
+
 **GitHub-mirror equivalent.** When the pipeline is GitHub-Actions-native (PR
 checks rather than a GitLab pipeline), use
 `gh pr checks -R <OWNER>/<REPO> <pr> --watch --fail-fast`