session-orchestrator 5.12.0 → 5.13.0

package/scripts/site-numbers.mjs

@@ -110,9 +110,10 @@ import { join, resolve, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
-import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isMeasuredSession, readCanonicalSessions } from './lib/sessions-canonical.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { slashCommandNames } from './lib/user-invocable-skills.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -393,6 +394,30 @@ export function isDirty(root) {
   }
 }
 
+/** Metrics counted from a gitignored ledger — the ones `--write` must never republish from the snapshot. */
+const LEDGER_METRICS = Object.freeze(['sessions', 'learnings']);
+
+/**
+ * Path of a gitignored metrics ledger. A linked worktree carries none of its own,
+ * so it reads its main checkout's copy (#1555) — the same mapping
+ * `scripts/resolve-session-invocation.mjs` applies to sessions.jsonl. Returns the
+ * root's own path when neither exists, so an absent ledger still reads as `null`
+ * downstream and the snapshot fallback stays reachable for a fresh clone.
+ *
+ * @param {string} root
+ * @param {string} name  e.g. `sessions.jsonl`
+ * @returns {string}
+ */
+function ledgerFile(root, name) {
+  // ledger-root: this tree's own copy first, on purpose; the shared one is the fallback below
+  const own = join(root, '.orchestrator', 'metrics', name);
+  if (existsSync(own)) return own;
+  const main = resolveEventsLedgerRoot(root);
+  // ledger-root: the shared copy in the main checkout, read on purpose beside the own one
+  const shared = join(main, '.orchestrator', 'metrics', name);
+  return main !== resolve(root) && existsSync(shared) ? shared : own;
+}
+
 // ---------------------------------------------------------------------------
 // The metric table — the part that must never be re-derived by hand
 // ---------------------------------------------------------------------------
@@ -472,9 +497,9 @@ export const METRIC_DEFS = Object.freeze([
     // Measured on THIS repo's own ledger @ 2ccea0f2: raw line count 289 vs
     // canonical (deduped) count 278 — an over-count of 11 records, which is the
     // bug's magnitude this migration removes.
-    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186)',
+    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186; synthetic backfill stubs excluded — isMeasuredSession, audit E1)',
     compute: (root) => {
-      const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+      const file = ledgerFile(root, 'sessions.jsonl');
       // Same absent/non-file guard as countJsonlEntries, kept explicit here
       // because readCanonicalSessions returns [] (not null) on a missing ledger
       // — collapsing that into fmtCount(0) would silently defeat the
@@ -487,7 +512,9 @@ export const METRIC_DEFS = Object.freeze([
       // identified for dedup. Measured @ 2ccea0f2 on this repo's own ledger:
       // 0 such rows (raw 289 lines == 289 identified), so the drop is inert
       // here; it only matters for a future malformed/legacy row.
-      return fmtCount(readCanonicalSessions({ filePath: file }).length);
+      // Audit E1: count MEASURED sessions only — synthetic backfill stubs are
+      // records of a start, not sessions (`isMeasuredSession`).
+      return fmtCount(readCanonicalSessions({ filePath: file }).filter(isMeasuredSession).length);
     },
   },
   {
@@ -497,7 +524,7 @@ export const METRIC_DEFS = Object.freeze([
     snapshotFallback: true,
     source: 'grep -c . .orchestrator/metrics/learnings.jsonl',
     compute: (root) => {
-      const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', 'learnings.jsonl'));
+      const r = countJsonlEntries(ledgerFile(root, 'learnings.jsonl'));
       return r === null ? null : fmtCount(r.entries);
     },
   },
@@ -743,7 +770,7 @@ export function collect(root, ctx = {}) {
     ['sessions', 'sessions.jsonl'],
     ['learnings', 'learnings.jsonl'],
   ]) {
-    const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', file));
+    const r = countJsonlEntries(ledgerFile(root, file));
     if (r && r.malformed > 0) {
       // #1186: the two ledgers now disagree on what a malformed line DOES to
       // the published count. `learnings` is still the raw countJsonlEntries
@@ -759,7 +786,7 @@ export function collect(root, ctx = {}) {
     }
   }
 
-  return { values, missing, warnings, fromSnapshot };
+  return { values, missing, warnings, fromSnapshot, localFallbacks };
 }
 
 // ---------------------------------------------------------------------------
@@ -1307,7 +1334,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
     return 2;
   }
 
-  const { values, missing, warnings, fromSnapshot } = collect(root, { usage: env.usage });
+  const { values, missing, warnings, fromSnapshot, localFallbacks } = collect(root, { usage: env.usage });
   if (missing.length > 0) {
     stderr(
       `Error: could not measure ${missing.join(', ')} under ${root} — ` +
@@ -1315,6 +1342,22 @@ export function main(argv = process.argv.slice(2), env = {}) {
     );
     return 2;
   }
+  // #1555: a --write of the SERVED site publishes what it measured. A ledger
+  // metric answered by the snapshot is the previous release's number, not a
+  // measurement (5.11.0 and 5.12.0 both republished 475 sessions / 220
+  // learnings from a release worktree), so it is refused. Only the real site/
+  // is guarded; a --write --site <fixture> run publishes nothing. counted-sha
+  // keeps its snapshot answer — the tested no-.git contract below.
+  const writesServedSite = args.write && resolve(siteDir) === resolve(join(root, 'site'));
+  const staleLedgers = localFallbacks.filter((id) => LEDGER_METRICS.includes(id));
+  if (writesServedSite && staleLedgers.length > 0) {
+    stderr(
+      `Error: ${staleLedgers.join(', ')} not measurable under ${root} — the gitignored ledgers are absent ` +
+        `here and in the main checkout; refusing to republish the old ${CENSUS_FILE.join('/')} values. ` +
+        'Run --write from a checkout that has them.',
+    );
+    return 2;
+  }
   for (const w of warnings) stderr(`WARN: ${w}`);
 
   const dirty = isDirty(root);
@@ -1489,7 +1532,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // release preflight's clean-tree check. A fixture run is a read of the repo,
   // never a write to it.
   let censusWritten = false;
-  const writesCensus = args.write && resolve(siteDir) === resolve(join(root, 'site'));
+  const writesCensus = writesServedSite;
   if (writesCensus && ok) {
     const res = writeCensusSnapshot(root, values);
     if (res.ok) {

package/scripts/snapshot-probe.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * snapshot-probe.mjs — run validate-plugin and the test suite on the curated public
+ * snapshot tree, materialized outside the repo without a remote (#1712).
+ * Library: scripts/lib/snapshot-probe.mjs.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+import { KNOWN_STEPS, SnapshotProbeSystemError, runSnapshotProbe } from './lib/snapshot-probe.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const HELP = `Usage: node scripts/snapshot-probe.mjs [options]
+
+Builds the curated public GitHub snapshot of a source commit (the tree minus the paths in
+.orchestrator/policy/public-export.json — the same helper the export uses), materializes it
+under $TMPDIR as a one-commit git repo WITHOUT any remote, and runs the steps there. Catches
+tests and validators that depend on a file the public export drops.
+
+Options:
+  --source <rev>     source commit (default HEAD)
+  --steps <list>     comma-separated steps, from: ${KNOWN_STEPS.join(', ')} (default: both)
+  --host <alias>     run the 'test' step on an offload host instead: one 'remote-gate' step
+                     (the pre-push router's full gate against the snapshot commit, no gate
+                     telemetry); validate-plugin still runs locally
+  --local            run the 'test' step (full suite) on this host instead
+                     The 'test' step needs exactly one of --host or --local.
+  --keep             keep the materialized snapshot directory (printed as dir)
+  --no-receipt       do not write .orchestrator/tmp/snapshot-probe/<tree>.json
+  --json             print one JSON object instead of the human summary (remote gate
+                     output goes to stderr)
+  --version          print the plugin version
+  -h, --help         show this help
+
+Exit codes:
+  0  every step passed
+  1  usage error
+  2  system error: git, tar or mkdtemp failure, or the remote gate did not run the suite
+     to completion (host unknown or not ready, fallback, gate-timeout, a timed-out check,
+     no test result) — no receipt is written
+  3  the probe ran and the snapshot is red (a step failed or timed out)
+
+A receipt is written only when a suite step ran ('test' or 'remote-gate'); a
+--steps validate-plugin run prints its result and leaves any existing receipt untouched.
+The release preflight accepts only receipts whose steps include a passing suite step:
+'test' (--local) or 'remote-gate' (--host).
+
+Examples:
+  node scripts/snapshot-probe.mjs --steps validate-plugin
+  node scripts/snapshot-probe.mjs --host m5 --json
+  node scripts/snapshot-probe.mjs --local --json
+`;
+
+/**
+ * Parse argv into probe options.
+ * @param {string[]} argv
+ * @returns {{ ok: true, opts: object } | { ok: false, error: string } | { ok: true, help: true } | { ok: true, version: true }}
+ */
+export function parseCli(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        source: { type: 'string', default: 'HEAD' },
+        steps: { type: 'string' },
+        local: { type: 'boolean', default: false },
+        host: { type: 'string' },
+        keep: { type: 'boolean', default: false },
+        'no-receipt': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    }));
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  if (values.help) return { ok: true, help: true };
+  if (values.version) return { ok: true, version: true };
+  const steps = values.steps === undefined ? [...KNOWN_STEPS] : values.steps.split(',').map((s) => s.trim()).filter(Boolean);
+  if (steps.length === 0) return { ok: false, error: '--steps is empty' };
+  const unknown = steps.filter((s) => !KNOWN_STEPS.includes(s));
+  if (unknown.length > 0) return { ok: false, error: `unknown step(s): ${unknown.join(', ')} (known: ${KNOWN_STEPS.join(', ')})` };
+  if (values.local && values.host !== undefined) return { ok: false, error: '--host and --local are mutually exclusive' };
+  if (values.host !== undefined && !/^[A-Za-z0-9._-]+$/.test(values.host)) return { ok: false, error: `invalid --host alias '${values.host}'` };
+  // Host rule: full suites belong on a remote host; the local host only with --local.
+  if (steps.includes('test') && !values.local && values.host === undefined) {
+    return { ok: false, error: "the 'test' step runs the full suite — pass --host <alias> or --local, or use --steps validate-plugin" };
+  }
+  return {
+    ok: true,
+    opts: { source: values.source, steps, keep: values.keep, writeReceipt: !values['no-receipt'], json: values.json, ...(values.host !== undefined ? { host: values.host } : {}) },
+  };
+}
+
+function humanSummary(r) {
+  const lines = [
+    `snapshot probe ${r.ok ? 'GREEN' : 'RED'} — source ${r.sourceSha.slice(0, 12)}, tree ${r.snapshotTree.slice(0, 12)} (route ${r.route})`,
+    `files: ${r.counts.source} source, ${r.counts.excluded} excluded, ${r.counts.exported} exported`,
+  ];
+  for (const s of r.steps) {
+    lines.push(`  ${s.name}: ${s.status} (exit ${s.exitCode}, ${Math.round(s.durationMs / 1000)}s)`);
+    if (s.reason) lines.push(`    ${s.reason}`);
+    if (s.failedFiles) for (const f of s.failedFiles) lines.push(`    FAIL ${f}`);
+    if (s.tail) lines.push(...s.tail.split('\n').map((l) => `    | ${l}`));
+  }
+  if (r.dir) lines.push(`kept: ${r.dir}`);
+  return lines.join('\n');
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ repoRoot?: string, probe?: typeof runSnapshotProbe }} [deps]
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, { repoRoot = REPO_ROOT, probe = runSnapshotProbe } = {}) {
+  const parsed = parseCli(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`snapshot-probe: ${parsed.error}\n\n${HELP}`);
+    return 1;
+  }
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (parsed.version) {
+    process.stdout.write(`${JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version}\n`);
+    return 0;
+  }
+  const { json, ...opts } = parsed.opts;
+  let result;
+  try {
+    result = await probe({ repoRoot, ...opts });
+  } catch (err) {
+    const message = err instanceof SnapshotProbeSystemError ? err.message : `unexpected failure: ${err?.message ?? err}`;
+    if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+    process.stderr.write(`snapshot-probe: ${message}\n`);
+    return 2;
+  }
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `${humanSummary(result)}\n`);
+  return result.ok ? 0 : 3;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/scripts/so-hud.mjs

@@ -7,6 +7,7 @@ import { execFile } from 'node:child_process';
 import { promisify, parseArgs } from 'node:util';
 import { measure } from './lib/so-hud/runtime.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { parseSessionId } from './lib/session-id.mjs';
 const exec = promisify(execFile);
 const SO_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
@@ -15,13 +16,17 @@ export async function main(argv, deps = {}) {
   const error = deps.error ?? (s => process.stderr.write(s));
   let values;
   try {
-    ({ values } = parseArgs({ args: argv, options: { json: { type: 'boolean' }, 'repo-root': { type: 'string' }, 'register-root': { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false }));
+    ({ values } = parseArgs({ args: argv, options: { json: { type: 'boolean' }, 'repo-root': { type: 'string' }, 'session-id': { type: 'string' }, 'register-root': { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false }));
     if (values.help) {
-      output('so-hud --json [--repo-root <path>] [--register-root]\nRead-only HUD JSON v1. --register-root registers this SO installation (0600).\nDefault repo: git toplevel of cwd. Exit 0: measured; 2: invocation/registration error; 6: repository unavailable.\n');
+      output('so-hud --json [--repo-root <path>] [--session-id <raw-uuid>] [--register-root]\nRead-only HUD JSON v1. --register-root registers this SO installation (0600).\nDefault repo: git toplevel of cwd. --session-id: the session whose agents are counted, read beside its own session.lock (#1730); without it the id comes from CLAUDE_SESSION_ID/SO_SESSION_ID and agents are read in the repo.\nExit 0: measured; 2: invocation/registration error; 6: repository unavailable.\n');
       return 0;
     }
     if (!values.json && !values['register-root']) throw new Error('--json required');
-  } catch { error('so-hud: --json erforderlich; siehe --help\n'); return 2; }
+    if (values['session-id'] !== undefined && parseSessionId(values['session-id'])?.format !== 'uuid') throw new Error('bad --session-id');
+  } catch (e) {
+    error(e?.message === 'bad --session-id' ? 'so-hud: --session-id braucht eine Roh-UUID; siehe --help\n' : 'so-hud: --json erforderlich; siehe --help\n');
+    return 2;
+  }
   if (values['register-root']) {
     try {
       const dir = path.join(deps.home ?? os.homedir(), '.config/session-orchestrator/hud');
@@ -36,10 +41,28 @@ export async function main(argv, deps = {}) {
   }
   let root;
   try {
-    root = values['repo-root'] ? path.resolve(values['repo-root']) : (await (deps.exec ?? exec)('git', ['rev-parse', '--show-toplevel'], { timeout: 700 })).stdout.trim();
-    if (!root || !(await fs.stat(root)).isDirectory()) throw new Error('missing');
+    // A session started in a subdirectory measures its working copy: the git toplevel. Not a repo → the given
+    // directory itself (never fail the measurement).
+    const given = values['repo-root'] ? path.resolve(values['repo-root']) : null;
+    const top = await (deps.exec ?? exec)('git', [...(given ? ['-C', given] : []), 'rev-parse', '--show-toplevel'], { timeout: 700 })
+      .then(r => r.stdout.trim(), () => '');
+    if (!top && !given) throw new Error('missing');
+    root = await fs.realpath(top || given);
+    // git answers in physical spelling, but the session writes file paths in the spelling it was given, and the
+    // collision guard compares those as strings: keep the caller's spelling of the toplevel where it is derivable.
+    // Peers are compared physically in collect.mjs. The caller's spelling is used only when it resolves to the
+    // physical toplevel: a symlinked last path part (<d>/elsewhere/scripts → <d>/repo/scripts) would otherwise
+    // map to <d>/elsewhere, which is not the repository.
+    if (given) {
+      const sub = path.relative(root, await fs.realpath(given));
+      let candidate = null;
+      if (sub === '') candidate = given;
+      else if (sub !== '..' && !sub.startsWith(`..${path.sep}`) && given.endsWith(`${path.sep}${sub}`)) candidate = given.slice(0, -sub.length - 1);
+      if (candidate !== null && await fs.realpath(candidate).catch(() => null) === root) root = candidate;
+    }
+    if (!(await fs.stat(root)).isDirectory()) throw new Error('missing');
   } catch { error('so-hud: Repo nicht ermittelbar\n'); return 6; }
-  try { output(`${JSON.stringify(await (deps.measure ?? measure)(root))}\n`); return 0; }
+  try { output(`${JSON.stringify(await (deps.measure ?? measure)(root, { sessionId: values['session-id'] ?? null }))}\n`); return 0; }
   catch { error('so-hud: Messung fehlgeschlagen\n'); return 6; }
 }
 if (isMainModule(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/scripts/state-md-idle-reset.mjs

@@ -12,7 +12,8 @@ Phase 1.5, Idle Reset rules 1-7): status idle, current-wave 0, Wave History
 demoted into Previous Session, Deviations emptied, scope-baseline-* keys
 deleted. The five recommendation keys stay in the frontmatter so the Phase 7.5
 Mode-Selector can read them. Any other status is a no-op; reasons:
-status-not-completed, unparseable, missing (no or empty STATE.md).
+status-not-completed, unparseable, missing (no or empty STATE.md),
+foreign-state-md (only another platform's foreign STATE.md exists, #1618).
 
   --repo-root <dir>  Repository root holding the state dir (default: cwd)
   --json             Emit {"changed", "reason", "path"} instead of one line

package/scripts/sweep-expired-learnings.mjs

@@ -139,6 +139,7 @@ import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
+import { resolveLedgerPath, resolveLedgerRoot } from './lib/ledger-path.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -257,6 +258,7 @@ function parseArgs(argv) {
     generation: null,
     acceptEmbedded: false,
   };
+  let fileExplicit = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--prune') {
@@ -296,6 +298,7 @@ function parseArgs(argv) {
       args.snapshot = pathValue(a, argv[++i]);
     } else if (a === '--file') {
       args.file = pathValue(a, argv[++i]);
+      fileExplicit = true;
     } else if (a === '--archive') {
       args.archive = pathValue(a, argv[++i]);
       args.archiveExplicit = true;
@@ -343,6 +346,12 @@ function parseArgs(argv) {
     }
   }
 
+  // #1722: the DEFAULT store/archive route through the ledger resolver (main
+  // checkout when cwd is a linked worktree that gitignores them); outside one
+  // the relative defaults are kept verbatim. Explicit --file/--archive stay.
+  if (!fileExplicit) args.file = routedDefault(DEFAULT_FILE);
+  if (!args.archiveExplicit) args.archive = routedDefault(DEFAULT_ARCHIVE);
+
   // Mode/flag mismatches are usage errors, never silent no-ops: a `--grace-days`
   // that the prune path ignores would read as "the grace window applied" in a
   // transcript, and an `--entries` the sweep ignores would read as "my next
@@ -381,7 +390,7 @@ function parseArgs(argv) {
       // (macOS /var → /private/var) refused a store inside it. The file goes
       // through resolveLedger (realpath when it exists), because
       // canonicalizeRoot realpaths only the root.
-      if (!validatePathInsideProject(resolveLedger(args.file), args.repoRoot, { canonicalizeRoot: true }).ok) {
+      if (ledgerRootOf(args.file, args.repoRoot) === null) {
         usageError(`--file ${args.file} lies outside --repo-root ${args.repoRoot} — nothing written`);
       }
     }
@@ -441,7 +450,9 @@ async function runSweep(args) {
   } else {
     process.stdout.write(
       `sweep-expired-learnings: scanned=${summary.scanned} kept=${summary.kept} ` +
-        `archived=${summary.archived} dry_run=${summary.dryRun} archive=${summary.archivePath}\n`
+        `archived=${summary.archived} dry_run=${summary.dryRun} archive=${summary.archivePath}` +
+        // An inbox-role apply (#1516) wrote nothing; say so, as --json does.
+        `${summary.skipped ? ` skipped=${summary.skipped}` : ''}\n`
     );
   }
 }
@@ -609,6 +620,39 @@ function resolveLedger(p) {
   }
 }
 
+/**
+ * The default ledger for this cwd (#1722): `rel` verbatim unless the resolver
+ * maps it elsewhere (linked worktree that gitignores it), then that absolute path.
+ *
+ * @param {string} rel
+ * @returns {string}
+ */
+function routedDefault(rel) {
+  const routed = resolveLedgerPath(rel, process.cwd());
+  return routed === path.resolve(rel) ? rel : routed;
+}
+
+/**
+ * Which root a store lies inside, canonically (#1500 F4): `repoRoot` itself, or
+ * its ledger root (the main checkout of a linked worktree, #1722) — but only for
+ * a file inside the DIRECTORY of the mapped default store, never anywhere in
+ * that other checkout (a worktree session must not rewrite a foreign tree).
+ * `null` when it lies outside both.
+ *
+ * @param {string} file
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function ledgerRootOf(file, repoRoot) {
+  const abs = resolveLedger(file);
+  if (validatePathInsideProject(abs, repoRoot, { canonicalizeRoot: true }).ok) return repoRoot;
+  const storeDir = path.dirname(resolveLedgerPath(DEFAULT_FILE, repoRoot));
+  if (validatePathInsideProject(abs, storeDir, { canonicalizeRoot: true }).ok) {
+    return resolveLedgerRoot(DEFAULT_FILE, repoRoot);
+  }
+  return null;
+}
+
 /**
  * Exit 1 when `--snapshot` would replace the store or the archive. The rename
  * lands the header as the store's line 1 with no `.bak` (and drops malformed
@@ -820,7 +864,9 @@ async function runPrune(args) {
   // hand-assembled `--entries` sidecar) never wrote anything, so it must not
   // report a completed run either. Best-effort — never changes this
   // command's exit code or stdout contract.
-  if (!args.dryRun) {
+  // An inbox-role apply (#1516) returns `skipped`: it archived nothing and did
+  // not rewrite the store, so there is no completed store write to report.
+  if (!args.dryRun && !result.skipped) {
     await emitEvolveCompleted({
       repoRoot: args.repoRoot,
       appended: args.appended,
@@ -841,7 +887,7 @@ async function runPrune(args) {
     process.stdout.write(
       `sweep-expired-learnings: prune scanned=${summary.scanned} kept=${summary.kept} ` +
         `archived=${summary.archived} by_reason=${byReason} dry_run=${summary.dryRun} ` +
-        `archive=${summary.archivePath}\n`
+        `archive=${summary.archivePath}${summary.skipped ? ` skipped=${summary.skipped}` : ''}\n`
     );
   }
 }
@@ -858,7 +904,7 @@ async function runPrune(args) {
 async function emitMalformedDropped(args, result) {
   // Both sides canonical, as the parseArgs check judged them: a lexical
   // relative() across /var vs /private/var reads `../../private/...`.
-  const root = resolveLedger(args.repoRoot);
+  const root = resolveLedger(ledgerRootOf(args.file, args.repoRoot) ?? args.repoRoot);
   const rel = (p) => path.relative(root, resolveLedger(p));
   try {
     const { emitEvent, sessionAttribution } = await import('./lib/events.mjs');
@@ -916,7 +962,9 @@ async function runDropMalformed(args) {
     process.exit(2);
   }
 
-  if (!args.dryRun) await emitMalformedDropped(args, result);
+  // An inbox-role host (#1516) returns the dry-run probe with `skipped` set:
+  // nothing was dropped, so no event may claim it was.
+  if (!args.dryRun && !result.skipped) await emitMalformedDropped(args, result);
 
   const summary = {
     file: args.file,

package/scripts/sweep-expired-rules.mjs

@@ -105,6 +105,7 @@ export function parseArgs(argv) {
     } else if (a === '--learnings') {
       const raw = argv[++i];
       if (typeof raw !== 'string' || raw.length === 0) usageError('--learnings requires a path');
+      if (path.isAbsolute(raw)) usageError('--learnings requires a repo-relative path');
       args.learnings = raw;
     } else if (a === '--help' || a === '-h') {
       printHelp();
@@ -140,6 +141,7 @@ export function summarize(plan, args, applied) {
     expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
     unresolved_pairs: plan.plans.reduce((n, p) => n + p.unresolvedPairIds.length, 0),
     malformed_lines: plan.malformedLines,
+    archive_malformed_lines: plan.archiveMalformedLines,
     rules_dir_readable: plan.ok,
     skipped: plan.skipped,
     plans: plan.plans.map(({ nextContent: _nextContent, ...rest }) => rest),
@@ -178,7 +180,8 @@ async function main(argv) {
         `(${summary.header_raises} header-raise(s)), ` +
         `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
         `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
-        `${summary.malformed_lines} malformed learnings line(s)\n`,
+        `${summary.malformed_lines} malformed learnings line(s), ` +
+        `${summary.archive_malformed_lines} malformed archive line(s)\n`,
     );
     for (const s of plan.skipped) process.stdout.write(`  skipped ${s.file}: ${s.reason}\n`);
     for (const p of plan.plans) {

package/scripts/validate-plugin.mjs

@@ -481,6 +481,11 @@ runCheck('check-learning-provenance.mjs');
 process.stdout.write('\n');
 runCheck('check-vcs-repo-flag.mjs');
 
+// Separate advice contract (#1024): name the PR or drop a rejected repo flag.
+// WARN-only, with tool errors surfaced through FAIL lines as in the bare census.
+process.stdout.write('\n');
+runCheck('check-vcs-repo-flag-positional.mjs');
+
 // WARN-only (#1023): a `gh`/`glab` command cited in docs that no released CLI
 // ever had — `glab repo edit --visibility`, `glab group list` — costs an
 // operator a failed command and a re-derivation. The oracle is the CLI's own
@@ -539,6 +544,13 @@ if (runCheck('check-learnings-shell-writes.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 runCheck('check-test-git-config-target.mjs');
 
+// BLOCKING (#1613): a test that spawns `sh`/`bash` by bare name is red on native
+// Windows (no sh on PATH, bash is WSL) — 301 red tests at fd8d3673. It may block
+// because the backlog was drained in the same change: the live census leaves only
+// three files in open MRs, baselined inside the checker as WARN.
+process.stdout.write('\n');
+if (runCheck('check-test-posix-shell.mjs') !== 0) checkFailed = 1;
+
 // BLOCKING (#1183): every `emitEvent()` call site under hooks/**/*.mjs must be
 // try/catch-guarded (emitEvent() throws EventValidationError on a malformed
 // record — an unguarded call aborts the hook process). Five pre-existing
@@ -548,6 +560,16 @@ runCheck('check-test-git-config-target.mjs');
 process.stdout.write('\n');
 if (runCheck('check-hooks-emit-event-guard.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n'); if (runCheck('check-workflow-continue-on-error.mjs') !== 0) checkFailed = 1;
+
+// BLOCKING (#1722): a module under scripts/ or hooks/ that builds a
+// `.orchestrator/metrics` path must route it through resolveLedgerPath()
+// (events/sessions: resolveEventsLedgerRoot()). The ledgers are gitignored, so
+// from a linked worktree an unrouted writer leaves a copy that is lost with the
+// worktree. Deliberately local sites sit on the checker's own ALLOWLIST.
+process.stdout.write('\n');
+if (runCheck('check-metrics-ledger-root.mjs') !== 0) checkFailed = 1;
+
 // BLOCKING (#1184): every scripts/lib/validate/check-*.mjs must be referenced
 // by basename from this file, .husky/pre-commit, or .gitlab-ci.yml — or carry
 // a `// registration: standalone <reason>` header marker declaring itself