session-orchestrator 3.17.0 → 3.20.0

package/scripts/repair-invalid-sessions.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * repair-invalid-sessions.mjs — one-time repair CLI for schema-invalid session
+ * ledger records (GitLab #1004).
+ *
+ * Thin driver: argument parsing, output rendering, exit codes. All repair logic
+ * lives in `scripts/lib/session-record-repair.mjs` so tests import functions
+ * instead of spawning a process.
+ *
+ *   node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]
+ *                                            [--file PATH] [--repo-root PATH]
+ *
+ * SAFETY: `--dry-run` is the DEFAULT — nothing is written unless `--apply` is
+ * passed. Under `--apply` the original is ALWAYS copied to `<file>.bak-<stamp>`
+ * BEFORE the swap (the backup is mandatory — there is no opt-out, because this
+ * is a write path to a protected ledger and the `.bak` is its only forensic
+ * trail; MED-3), the new content is written to `<file>.tmp-<pid>` and renamed
+ * over the target (atomic), and the result is then re-verified against BOTH
+ * `validateSession` and `checkSessionsIntegrity`. A failed verification restores
+ * the backup byte-identically and exits 3 — the ledger is never left in a state
+ * worse than the one this CLI found.
+ *
+ * TARGET CONSTRAINT (MED-3): `--file` MUST resolve inside
+ * `<repo-root>/.orchestrator/metrics/`. Any target outside it — including a
+ * `..` traversal or a symlinked parent that escapes the dir — is refused with
+ * exit 1 BEFORE any read or write. This CLI is a write path to a protected
+ * ledger that the pre-bash-sessions-ledger-guard does not see (it resolves to
+ * verb `node`), so the target it may touch is bounded here.
+ *
+ * Exit codes (`.claude/rules/cli-design.md`):
+ *   0 — completed (dry-run or apply); the ledger is clean or unchanged
+ *   1 — user/input error (bad flag, unknown argument)
+ *   2 — system error (unreadable/unwritable ledger, I/O failure)
+ *   3 — post-verification failed; the backup was restored and nothing was kept
+ */
+
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
+import { SO_PROJECT_DIR } from './lib/platform.mjs';
+
+const USAGE =
+  'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
+  '                                                [--file PATH] [--repo-root PATH]\n' +
+  '  --dry-run     preview only (DEFAULT — nothing is written)\n' +
+  '  --apply       rewrite the ledger in place (mandatory backup + atomic rename)\n' +
+  '  --json        emit the summary as JSON to stdout\n' +
+  '  --file        ledger path (default: <repo-root>/' +
+  CANONICAL_LEDGER_REL +
+  ');\n' +
+  '                must resolve inside <repo-root>/.orchestrator/metrics/\n' +
+  '  --repo-root   project root (default: resolved SO_PROJECT_DIR)\n' +
+  'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n';
+
+/**
+ * Resolve `--file` and REFUSE any target outside
+ * `<repoRoot>/.orchestrator/metrics/` (MED-3). Symlinks are resolved on the
+ * metrics dir and on the target's PARENT (the file itself may not exist yet),
+ * so a symlinked parent cannot escape the dir; `path.resolve` collapses any
+ * `..` traversal before the prefix check.
+ *
+ * @param {string} file - the requested target (default or `--file` value).
+ * @param {string} repoRoot
+ * @returns {{ok: true, file: string}|{ok: false, metricsDir: string, resolved: string}}
+ */
+function resolveLedgerTarget(file, repoRoot) {
+  const metricsDir = path.resolve(repoRoot, '.orchestrator', 'metrics');
+  // `absFile` (normalized, `..` collapsed) is what the repair uses — NOT the
+  // symlink-resolved form, so the canonical-path equality in `verifyWritten`
+  // (which compares against a non-realpath'd repoRoot) still recognises it.
+  const absFile = path.resolve(file);
+
+  // The CONTAINMENT decision resolves symlinks on both the metrics dir and the
+  // target's PARENT (the file itself may not exist yet), so a symlinked parent
+  // cannot smuggle a path that textually sits under metrics but physically
+  // escapes it (`metrics/link -> /etc`, then `--file metrics/link/passwd`).
+  let realMetricsDir = metricsDir;
+  try {
+    realMetricsDir = fs.realpathSync(metricsDir);
+  } catch {
+    /* not created yet — fall back to the normalized path */
+  }
+  let realParent = path.dirname(absFile);
+  try {
+    realParent = fs.realpathSync(path.dirname(absFile));
+  } catch {
+    /* parent may not exist yet — fall back to the normalized parent */
+  }
+  const realFile = path.join(realParent, path.basename(absFile));
+
+  const prefix = realMetricsDir.endsWith(path.sep) ? realMetricsDir : realMetricsDir + path.sep;
+  if (!realFile.startsWith(prefix)) {
+    return { ok: false, metricsDir: realMetricsDir, resolved: realFile };
+  }
+  return { ok: true, file: absFile };
+}
+
+/**
+ * Human-readable summary — mirrors `scripts/backfill-abandoned-sessions.mjs`
+ * `renderHuman()` so the two migration CLIs read the same way.
+ *
+ * @param {object} s summary from `repairLedger`
+ * @returns {string}
+ */
+export function renderHuman(s) {
+  const lines = [];
+  lines.push(`Repair invalid session records — ${s.mode}`);
+  lines.push(`  file:            ${s.file}`);
+  lines.push(`  lines:           ${s.total}`);
+  lines.push(`  invalid before:  ${s.invalid_before}`);
+  lines.push(`  ${s.mode === 'apply' ? 'repaired:       ' : 'would repair:   '} ${s.repaired}`);
+  lines.push(`  invalid after:   ${s.invalid_after}${s.mode === 'apply' ? '' : ' (projected)'}`);
+  if (s.unparseable > 0) {
+    lines.push(`  unparseable:     ${s.unparseable} (passed through untouched)`);
+  }
+  if (s.duplicate_ids_observed.length > 0) {
+    const ids = s.duplicate_ids_observed.map((d) => `${d.session_id} x${d.count}`).join(', ');
+    lines.push(`  duplicate ids:   ${s.duplicate_ids_observed.length} (${ids}) — preserved, never deduped`);
+  }
+  const classes = Object.entries(s.defects_by_class);
+  if (classes.length > 0) {
+    lines.push('  defects by class:');
+    for (const [cls, n] of classes.sort((a, b) => b[1] - a[1])) lines.push(`    ${cls}: ${n}`);
+  }
+  if (s.backup_path) lines.push(`  backup:          ${s.backup_path}`);
+  if (s.errors.length > 0) {
+    lines.push(`  errors:          ${s.errors.length} (original line kept)`);
+    for (const e of s.errors) lines.push(`    line ${e.line} ${e.session_id ?? '<no session_id>'}: ${e.error}`);
+  }
+  if (s.post_verify && s.post_verify.integrity !== 'clean' && s.post_verify.integrity !== 'skipped-not-canonical-path') {
+    lines.push(`  integrity:       ${s.post_verify.integrity.message ?? 'FAILED'}`);
+  }
+  if (s.ok === false) {
+    lines.push('  POST-VERIFICATION FAILED — backup restored, ledger unchanged.');
+  }
+  return lines.join('\n') + '\n';
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        apply: { type: 'boolean', default: false },
+        'dry-run': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        file: { type: 'string' },
+        'repo-root': { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`repair-invalid-sessions: ${err.message}\n${USAGE}`);
+    process.exit(1);
+  }
+
+  const { values } = parsed;
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
+  const apply = values.apply === true && values['dry-run'] !== true;
+  const repoRoot = values['repo-root'] || SO_PROJECT_DIR;
+  const requestedFile = values.file || path.join(repoRoot, CANONICAL_LEDGER_REL);
+
+  // MED-3: bound the target to <repoRoot>/.orchestrator/metrics/ BEFORE any I/O.
+  const target = resolveLedgerTarget(requestedFile, repoRoot);
+  if (!target.ok) {
+    process.stderr.write(
+      `repair-invalid-sessions: --file must resolve inside ${target.metricsDir}${path.sep} ` +
+        `(got ${target.resolved})\n${USAGE}`
+    );
+    process.exit(1);
+  }
+  const file = target.file;
+
+  let summary;
+  try {
+    // The backup is mandatory (MED-3): this is a write path to a protected
+    // ledger and the `.bak` is its only forensic trail — there is no opt-out.
+    summary = repairLedger({ file, repoRoot, apply, backup: true });
+  } catch (err) {
+    process.stderr.write(`repair-invalid-sessions: ${err?.message ?? String(err)}\n`);
+    process.exit(2);
+  }
+
+  if (values.json) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+  } else {
+    process.stdout.write(renderHuman(summary));
+  }
+  process.exit(summary.ok === false ? 3 : 0);
+}
+
+const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`repair-invalid-sessions: unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(2);
+  });
+}

package/scripts/run-quality-gate.mjs

@@ -38,7 +38,9 @@ import { spawnSync } from 'node:child_process';
 
 import { die, warn } from './lib/common.mjs';
 import { loadQualityGatesPolicy, resolveCommand } from './lib/quality-gates-policy.mjs';
-import { emitEvent } from './lib/events.mjs';
+import { emitEvent, sessionAttribution } from './lib/events.mjs';
+import { admitSuiteCounts } from './lib/gates/gate-helpers.mjs';
+import { findScopeFile } from './lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -49,6 +51,14 @@ const GATES_DIR = join(__dirname, 'lib', 'gates');
 
 const VALID_VARIANTS = ['baseline', 'incremental', 'full-gate', 'per-file'];
 
+/**
+ * Ceiling on the gate sub-script's captured stdout. A gate writes one JSON line
+ * (5-line command tails + ≤50 debug artifacts), so this is effectively
+ * unreachable — it exists only so a pathological gate cannot be killed
+ * mid-write by the default 1 MiB spawnSync cap.
+ */
+const GATE_STDOUT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
 const DEFAULT_TEST_CMD = 'npm test';
 const DEFAULT_TYPECHECK_CMD = 'npm run typecheck';
 const DEFAULT_LINT_CMD = 'npm run lint';
@@ -148,6 +158,89 @@ function extractCommand(policy, policyKey, configKey, configJson, defaultCmd) {
   return defaultCmd;
 }
 
+/**
+ * Lift the suite counts out of a gate sub-script's JSON stdout envelope (#954).
+ *
+ * This function is the ENVELOPE ADAPTER only. The numeric admission policy —
+ * which triples count as a measurement and which are refused — lives once in
+ * {@link admitSuiteCounts} (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2),
+ * shared with `suiteCountsFromOutput` in `scripts/lib/quality-gate.mjs`. Before
+ * that split, the same `counts` field was written under two different policies
+ * and a consumer had to know both to read one number.
+ *
+ * The four rejections that stay here are envelope-shaped, not numeric:
+ *
+ *   1. stdout is absent or not parseable JSON;
+ *   2. `test` is not the object form — only `gate-full.mjs` reports numbers;
+ *      `gate-{baseline,incremental,per-file}.mjs` emit a bare status STRING, so
+ *      a non-full-gate variant structurally cannot carry counts;
+ *   3. the test gate was skipped (`status` neither `pass` nor `fail`);
+ *   4. the test COMMAND was detected as a stub (`echo …` / no-op) — a stub's
+ *      output parses to 0/0, which would be a fabricated zero.
+ *
+ * `failed` is NO LONGER derived here. Since #967 item 1 `gate-full.mjs`
+ * publishes it explicitly, so the whole `test` object is handed through and
+ * `admitSuiteCounts`'s `passed + failed === total` check becomes a real guard
+ * against producer/consumer envelope drift instead of an identity that a local
+ * `total - passed` derivation could never fail.
+ *
+ * Never throws — a malformed envelope yields `null`.
+ *
+ * @param {string} stdout — the gate sub-script's captured stdout.
+ * @returns {{ passed: number, failed: number, total: number }|null}
+ */
+function suiteCountsFromGateStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+
+  const test = parsed.test;
+  if (test === null || typeof test !== 'object' || Array.isArray(test)) return null;
+  if (test.status !== 'pass' && test.status !== 'fail') return null;
+  if (parsed.stubbed && typeof parsed.stubbed === 'object' && parsed.stubbed.test) return null;
+
+  return admitSuiteCounts(test);
+}
+
+/**
+ * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
+ *
+ * Mirrors `resolveWave()` in `hooks/pre-bash-memory-propose-audit.mjs` — the
+ * same `.{pi,cursor,codex,claude}/wave-scope.json` precedence via
+ * {@link findScopeFile} — with ONE deliberate difference: the hook returns `0`
+ * for "no wave-scope file", this returns `null`.
+ *
+ * Absent is not zero. A human running `npm run quality-gate` from a `git push`
+ * has no wave at all, and that is the common case; publishing `wave_number: 0`
+ * would invent a wave 0 that every consumer then has to special-case. The
+ * caller spreads the result so the KEY is omitted, exactly as `counts` is.
+ *
+ * A non-positive or non-numeric `wave` field is treated the same way — waves
+ * are 1-indexed, so `0` on disk carries no more information than an absent file.
+ *
+ * Never throws.
+ *
+ * @param {string} projectDir — directory whose wave-scope sidecar to read.
+ * @returns {number|null} positive wave number, or `null` when there is no wave.
+ */
+function resolveWaveNumber(projectDir) {
+  try {
+    const waveFile = findScopeFile(projectDir);
+    if (!waveFile || !existsSync(waveFile)) return null;
+    const wave = JSON.parse(readFileSync(waveFile, 'utf8'))?.wave;
+    if (typeof wave !== 'number' || !Number.isFinite(wave) || wave <= 0) return null;
+    return Math.trunc(wave);
+  } catch {
+    return null;
+  }
+}
+
 // Load policy file (never throws)
 const repoRoot = process.cwd();
 const policy = loadQualityGatesPolicy(repoRoot);
@@ -193,23 +286,48 @@ const env = {
   SESSION_START_REF: sessionStartRef,
 };
 
+// stdout is PIPED (not inherited) so the suite counts the gate already computed
+// can be lifted straight off its JSON envelope into telemetry (#954) instead of
+// travelling as prose through the STATE.md header. The envelope is re-emitted
+// verbatim below, so the stdout contract is unchanged — a gate sub-script writes
+// exactly one JSON line at the very end (its own child commands are captured by
+// `runCheck`), so nothing streamed before and nothing streams now. stderr stays
+// inherited, keeping warnings live.
 const result = spawnSync('node', [gatePath], {
   env,
-  stdio: 'inherit',
+  stdio: ['inherit', 'pipe', 'inherit'],
+  encoding: 'utf8',
+  maxBuffer: GATE_STDOUT_MAX_BUFFER_BYTES,
 });
 
-if (result.error) {
+const gateStdout = typeof result.stdout === 'string' ? result.stdout : '';
+if (gateStdout) process.stdout.write(gateStdout);
+
+if (result.error && typeof result.status !== 'number') {
   die(`Failed to run gate script: ${result.error.message}`);
 }
 
 // Quality-gate telemetry — one canonical event per gate run via emitEvent
-// (single emission path). Best-effort: a telemetry failure must NEVER alter the
-// gate's authoritative exit code.
+// (single emission path). `sessionAttribution` is the shared helper in
+// events.mjs (#941); this CLI wrapper runs against the CWD `repoRoot`, so the
+// bare emitEvent destination (SO_PROJECT_DIR default) is correct here.
+// Best-effort: a telemetry failure must NEVER alter the gate's authoritative
+// exit code — which is why the counts parse also lives inside this try.
 const exitCode = result.status ?? 1;
 try {
+  const counts = suiteCountsFromGateStdout(gateStdout);
+  // Wave-scope sidecar is read from the SAME project dir the event lands in
+  // (emitEvent's own destination precedence), so a tmp-scoped run cannot pick
+  // up the host repo's live wave. Mirrors the hook's projectDir resolution.
+  const waveNumber = resolveWaveNumber(
+    process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+  );
   await emitEvent(`orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`, {
     variant,
     exit_code: exitCode,
+    ...(counts ? { counts } : {}),
+    ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
+    ...sessionAttribution(repoRoot),
   });
 } catch { /* best-effort telemetry — gate result is authoritative */ }
 

package/scripts/sweep-expired-learnings.mjs

@@ -1,39 +1,56 @@
 #!/usr/bin/env node
 /**
- * sweep-expired-learnings.mjs — CLI for the mechanical expiry/archive sweep
- * (Epic #723 B4).
+ * sweep-expired-learnings.mjs — CLI for the two mechanical archive-safe writers
+ * over `learnings.jsonl`: the time-driven expiry sweep (Epic #723 B4, default)
+ * and the decision-driven prune (`--prune`, issue #1017).
  *
- * Moves `learnings.jsonl` entries that have been expired for longer than the
- * grace period into an append-only archive sidecar. NEVER deletes data —
- * archived entries remain readable in the archive file, tagged with
- * `_archived_at` / `_archive_reason: "expired"`.
+ * Both move records OUT of the active store and INTO an append-only archive
+ * sidecar. NEVER deletes data — archived entries remain readable in the archive
+ * file, tagged with `_archived_at` and an `_archive_reason` from the closed
+ * enum `expired | pruned | superseded | merged`.
  *
  * All read/partition/write logic lives in
- * `scripts/lib/learnings/expiry-sweep.mjs` (`sweepExpiredLearnings`), which
- * delegates the destructive store rewrite to `rewriteLearnings()` from
- * `scripts/lib/learnings/io.mjs` — automatic `.bak-<ISO>` backup + keep-3
- * rotation (#721) protects every `--apply` run.
+ * `scripts/lib/learnings/expiry-sweep.mjs` (`sweepExpiredLearnings` /
+ * `pruneLearnings`), which delegates the destructive store rewrite to
+ * `rewriteLearnings()` from `scripts/lib/learnings/io.mjs` — automatic
+ * `.bak-<ISO>` backup + keep-3 rotation (#721) protects every `--apply` run.
+ *
+ * Why `--prune` is a subcommand here and not an inline `node -e` block in
+ * `skills/evolve/SKILL.md`: a mechanism that lives inside prose has no test, no
+ * `--help`, and no exit-code contract. `/evolve` names this command; the
+ * mechanism stays in code.
  *
  * Usage:
- *   node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json]
- *     [--grace-days N] [--file PATH] [--archive PATH]
+ *   node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json]
+ *     [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
  *
  * Flags:
- *   --dry-run         Preview counts; write nothing (DEFAULT)
- *   --apply           Archive stale-expired entries + rewrite the store
+ *   --prune           Decision-driven prune+consolidate+rewrite instead of the
+ *                      time-driven expiry sweep (issue #1017)
+ *   --dry-run         Preview counts; write nothing (DEFAULT, both modes)
+ *   --apply           Perform the archive append + store rewrite
  *   --json            Emit a single machine-parseable JSON summary line
  *                      (default: human-readable one-liner)
- *   --grace-days N    Days past expiry before archiving (default: 14)
+ *   --grace-days N    Days past expiry before archiving (default: 14).
+ *                      SWEEP ONLY — `--prune` has no grace window by design.
+ *   --entries PATH    JSONL sidecar holding the caller's next store generation.
+ *                      PRUNE ONLY. Must exist, parse cleanly, and hold at least
+ *                      one record — absent/malformed/empty all exit 1 untouched.
+ *                      Omitted ⇒ a pure prune+consolidate pass over the on-disk
+ *                      store.
  *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
  *   --archive PATH    Archive sidecar (default: .orchestrator/metrics/learnings-archive.jsonl)
  *
  * Exit codes:
  *   0  Success (including no-op when nothing is archive-eligible)
- *   1  Usage error (bad flag/value)
- *   2  Sweep error (I/O or validation failure inside sweepExpiredLearnings)
+ *   1  Usage/input error (bad flag/value, flag used in the wrong mode, or an
+ *      absent/malformed/empty `--entries` sidecar)
+ *   2  Sweep/prune error (I/O or validation failure inside the lib)
  */
 
-import { sweepExpiredLearnings } from './lib/learnings/expiry-sweep.mjs';
+import { existsSync } from 'node:fs';
+import { sweepExpiredLearnings, pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
+import { readLearnings } from './lib/learnings/io.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -41,32 +58,51 @@ const DEFAULT_GRACE_DAYS = 14;
 
 function printHelp() {
   process.stdout.write(
-    `Usage: node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json] [--grace-days N] [--file PATH] [--archive PATH]
+    `Usage: node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json] [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
+
+Modes:
+  (default)         Expiry sweep — archive entries expired past the grace window
+  --prune           Prune + consolidate + rewrite (issue #1017): archives
+                    expired / zero-confidence / superseded / caller-dropped
+                    records instead of deleting them
 
 Options:
   --dry-run         Preview counts; write nothing (default)
-  --apply           Archive stale-expired entries + rewrite the store
+  --apply           Perform the archive append + store rewrite
   --json            Emit a single machine-parseable JSON summary line
-  --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS})
+  --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS}); sweep only
+  --entries PATH    JSONL sidecar with the next store generation; prune only.
+                    Must exist, parse cleanly, and hold >= 1 record
   --file PATH       Learnings store (default: ${DEFAULT_FILE})
   --archive PATH    Archive sidecar (default: ${DEFAULT_ARCHIVE})
 
-Exit codes:  0 success  1 usage error  2 sweep error
+Exit codes:  0 success  1 usage/input error  2 sweep/prune error
 `
   );
 }
 
+/** Exit 1 with a diagnostic on stderr (usage/input errors). */
+function usageError(message) {
+  process.stderr.write(`sweep-expired-learnings: ${message}\n`);
+  process.exit(1);
+}
+
 function parseArgs(argv) {
   const args = {
+    prune: false,
     dryRun: true,
     json: false,
     graceDays: DEFAULT_GRACE_DAYS,
+    graceDaysExplicit: false,
+    entries: null,
     file: DEFAULT_FILE,
     archive: DEFAULT_ARCHIVE,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--apply') {
+    if (a === '--prune') {
+      args.prune = true;
+    } else if (a === '--apply') {
       args.dryRun = false;
     } else if (a === '--dry-run') {
       args.dryRun = true;
@@ -76,12 +112,12 @@ function parseArgs(argv) {
       const raw = argv[++i];
       const v = Number(raw);
       if (!Number.isFinite(v) || v < 0) {
-        process.stderr.write(
-          `sweep-expired-learnings: --grace-days requires a non-negative number, got: ${raw}\n`
-        );
-        process.exit(1);
+        usageError(`--grace-days requires a non-negative number, got: ${raw}`);
       }
       args.graceDays = v;
+      args.graceDaysExplicit = true;
+    } else if (a === '--entries') {
+      args.entries = argv[++i];
     } else if (a === '--file') {
       args.file = argv[++i];
     } else if (a === '--archive') {
@@ -90,16 +126,29 @@ function parseArgs(argv) {
       printHelp();
       process.exit(0);
     } else {
-      process.stderr.write(`sweep-expired-learnings: unknown argument: ${a}\n`);
-      process.exit(1);
+      usageError(`unknown argument: ${a}`);
     }
   }
+
+  // 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
+  // generation was written".
+  if (args.prune && args.graceDaysExplicit) {
+    usageError('--grace-days is not valid with --prune (the prune path has no grace window)');
+  }
+  if (!args.prune && args.entries !== null) {
+    usageError('--entries is only valid with --prune');
+  }
   return args;
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-
+/**
+ * Time-driven expiry sweep (Epic #723 B4) — the default mode.
+ *
+ * @param {ReturnType<typeof parseArgs>} args
+ */
+async function runSweep(args) {
   let result;
   try {
     result = await sweepExpiredLearnings({
@@ -129,6 +178,117 @@ async function main() {
   }
 }
 
+/**
+ * Resolve the `--entries` sidecar into the caller's next store generation.
+ *
+ * Fails closed on THREE input conditions, all of which yield the same lethal
+ * value — an empty next generation, which makes `pruneLearnings()` treat the
+ * ENTIRE store as caller-dropped:
+ *
+ *   1. **absent file** — `readLearnings()` returns `{entries: [], malformed: []}`
+ *      for a missing path, so one mistyped path would archive every active
+ *      learning. A path the operator named and the filesystem does not have is
+ *      an input error, not an empty set.
+ *   2. **malformed line** — a half-written sidecar reads as a SHORTER next
+ *      generation, pruning every record the truncated tail omitted.
+ *   3. **parses to zero records** — a 0-byte or blank-line-only file. Guard (1)
+ *      closes ABSENCE, which is a different condition: an empty file EXISTS, so
+ *      it sails past `existsSync` and parses to a legitimate-looking empty
+ *      generation. Measured on a 3-record fixture before this guard: a 0-byte
+ *      `--entries` archived all 3 and exited 0.
+ *
+ * Condition 3 is REJECTED rather than obeyed because at a file boundary an
+ * empty parse is indistinguishable from a truncated write, a failed producer,
+ * or a typo that landed on an unrelated empty file — and no caller expresses
+ * "archive the whole corpus" through this flag: `/evolve`'s next generation
+ * always carries the survivors. The cost of rejecting a genuinely-intended
+ * empty generation is one re-run; the cost of obeying a corrupt one is the
+ * active store. Note this guard is deliberately NOT in `pruneLearnings()`: an
+ * explicit `entries: []` written in CODE is a statement, and the lib keeps it
+ * expressible. Only the FILE is ambiguous, so only the file is guarded.
+ *
+ * @param {string} entriesPath
+ * @returns {Promise<object[]>} the validated, non-empty next generation
+ */
+async function loadEntriesSidecar(entriesPath) {
+  if (!existsSync(entriesPath)) {
+    usageError(
+      `--entries sidecar not found: ${entriesPath} (refusing to prune — an absent ` +
+        `next generation would archive the whole store)`
+    );
+  }
+  let read;
+  try {
+    read = await readLearnings(entriesPath);
+  } catch (err) {
+    usageError(`--entries sidecar unreadable: ${entriesPath}: ${err.message}`);
+  }
+  if (read.malformed.length > 0) {
+    usageError(
+      `refusing to prune — ${read.malformed.length} malformed line(s) in ${entriesPath}`
+    );
+  }
+  if (read.entries.length === 0) {
+    usageError(
+      `--entries sidecar holds no records: ${entriesPath} (refusing to prune — an empty ` +
+        `next generation would archive every record in the store; omit --entries for a ` +
+        `pure prune+consolidate pass)`
+    );
+  }
+  return read.entries;
+}
+
+/**
+ * Decision-driven prune + consolidate + rewrite (issue #1017).
+ *
+ * @param {ReturnType<typeof parseArgs>} args
+ */
+async function runPrune(args) {
+  const entries = args.entries === null ? undefined : await loadEntriesSidecar(args.entries);
+
+  let result;
+  try {
+    result = await pruneLearnings({
+      filePath: args.file,
+      archivePath: args.archive,
+      entries,
+      dryRun: args.dryRun,
+    });
+  } catch (err) {
+    process.stderr.write(`sweep-expired-learnings: prune failed: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const summary = {
+    file: args.file,
+    entries_from: args.entries,
+    ...result,
+  };
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+  } else {
+    const byReason =
+      Object.entries(summary.byReason)
+        .map(([reason, n]) => `${reason}:${n}`)
+        .join(',') || '-';
+    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`
+    );
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.prune) {
+    await runPrune(args);
+    return;
+  }
+  await runSweep(args);
+}
+
 main().catch((err) => {
   process.stderr.write(`sweep-expired-learnings: unexpected error: ${err?.stack ?? err}\n`);
   process.exit(2);