session-orchestrator 3.16.0

package/scripts/backfill-learnings-expires.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * backfill-learnings-expires.mjs — one-shot backfill helper for `expires_at`.
+ *
+ * Closes issue #323. Surfaced by 2026-05-07 W1 D2 surface-map: 1/129 records
+ * in .orchestrator/metrics/learnings.jsonl was missing `expires_at` (id:
+ * `archive-en-masse-residual-policy-2026-05-01`).
+ *
+ * For each record without `expires_at`, derives one from `created_at` + `type`
+ * via `deriveExpiresAt()` from `scripts/lib/learnings.mjs`. Records that
+ * already have `expires_at` pass through untouched.
+ *
+ * Forensics: every patched record gets a `_backfilled_expires_at: true` tag
+ * so downstream readers can identify backfilled vs originally-stamped values.
+ *
+ * Usage:
+ *   node scripts/backfill-learnings-expires.mjs [--source <path>] [--dry-run] [--apply]
+ *
+ * Flags:
+ *   --source <path>   Path to learnings.jsonl (default: .orchestrator/metrics/learnings.jsonl)
+ *   --dry-run         Preview changes without writing (DEFAULT)
+ *   --apply           Write patched records back; backup original to <path>.bak.<isoDate>
+ *
+ * Exit codes:
+ *   0  Success (including no-op when nothing needs backfilling)
+ *   1  Input/validation error
+ *   2  I/O error
+ *
+ * Idempotent: a second --apply run produces 0 to_backfill (every record now
+ * has expires_at; the `_backfilled_expires_at` tag is preserved).
+ *
+ * Output (stdout — single JSON summary line):
+ *   {"total":N,"already_has_expires":A,"to_backfill":B,"parse_errors":P,"applied":bool}
+ *
+ * Per-record narration goes to stderr so stdout stays machine-parseable.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { deriveExpiresAt } from './lib/learnings.mjs';
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    `Usage: backfill-learnings-expires.mjs [--source <path>] [--dry-run] [--apply]
+
+Options:
+  --source <path>   Path to learnings.jsonl (default: .orchestrator/metrics/learnings.jsonl)
+  --dry-run         Preview changes without writing (DEFAULT)
+  --apply           Write patched records; backup original to <path>.bak.<isoDate>
+
+Exit codes:  0 success  1 input error  2 I/O error
+`
+  );
+  process.exit(0);
+}
+
+const applyFlag = args.includes('--apply');
+const dryRun = !applyFlag;
+
+const sourceIdx = args.indexOf('--source');
+const sourcePath =
+  sourceIdx !== -1 && args[sourceIdx + 1]
+    ? args[sourceIdx + 1]
+    : '.orchestrator/metrics/learnings.jsonl';
+
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+
+if (!existsSync(sourcePath)) {
+  process.stderr.write(`backfill-learnings-expires: source file not found: ${sourcePath}\n`);
+  process.exit(1);
+}
+
+let raw;
+try {
+  raw = readFileSync(sourcePath, 'utf8');
+} catch (err) {
+  process.stderr.write(
+    `backfill-learnings-expires: failed to read ${sourcePath}: ${err.message}\n`
+  );
+  process.exit(2);
+}
+
+const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+
+// ---------------------------------------------------------------------------
+// Backfill
+// ---------------------------------------------------------------------------
+
+let countAlready = 0;
+let countToBackfill = 0;
+let countParseErrors = 0;
+const outputLines = [];
+
+for (const line of lines) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    countParseErrors++;
+    process.stderr.write(
+      `backfill-learnings-expires: WARN skipping malformed JSON line: ${line.slice(0, 80)}\n`
+    );
+    // Preserve original line — never destroy data
+    outputLines.push(line);
+    continue;
+  }
+
+  const hasExpires =
+    typeof parsed.expires_at === 'string' && parsed.expires_at.length > 0;
+  if (hasExpires) {
+    countAlready++;
+    outputLines.push(JSON.stringify(parsed));
+    continue;
+  }
+
+  // Derive expires_at from created_at + type. deriveExpiresAt() falls back
+  // to Date.now() when created_at is missing/unparseable, so we always
+  // produce a valid ISO timestamp.
+  const newExpires = deriveExpiresAt(parsed.created_at, parsed.type);
+  const patched = {
+    ...parsed,
+    expires_at: newExpires,
+    _backfilled_expires_at: true,
+  };
+  countToBackfill++;
+  outputLines.push(JSON.stringify(patched));
+  process.stderr.write(
+    `backfill-learnings-expires: patched id=${parsed.id ?? '<no id>'} type=${parsed.type ?? '<no type>'} expires_at=${newExpires}\n`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Write (--apply only)
+// ---------------------------------------------------------------------------
+
+let applied = false;
+if (!dryRun && countToBackfill > 0) {
+  // Backup first
+  const isoDate = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${sourcePath}.bak.${isoDate}`;
+  try {
+    copyFileSync(sourcePath, backupPath);
+  } catch (err) {
+    process.stderr.write(
+      `backfill-learnings-expires: ERROR failed to create backup ${backupPath}: ${err.message}\n`
+    );
+    process.exit(2);
+  }
+
+  // Atomic write via tmp + rename
+  const body = outputLines.join('\n') + '\n';
+  const tmp = `${sourcePath}.backfill-tmp-${process.pid}-${Date.now()}`;
+  try {
+    mkdirSync(dirname(sourcePath), { recursive: true });
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, sourcePath);
+    applied = true;
+    process.stderr.write(
+      `backfill-learnings-expires: backup written to ${backupPath}\n`
+    );
+  } catch (err) {
+    process.stderr.write(
+      `backfill-learnings-expires: ERROR failed to write ${sourcePath}: ${err.message}\n`
+    );
+    try {
+      if (existsSync(tmp)) renameSync(tmp, tmp + '.failed');
+    } catch {
+      /* ignore */
+    }
+    process.exit(2);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary (single JSON line on stdout)
+// ---------------------------------------------------------------------------
+
+const summary = {
+  total: lines.length,
+  already_has_expires: countAlready,
+  to_backfill: countToBackfill,
+  parse_errors: countParseErrors,
+  applied,
+  dry_run: dryRun,
+  source: sourcePath,
+};
+process.stdout.write(JSON.stringify(summary) + '\n');
+
+process.exit(0);

package/scripts/backfill-learnings.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * backfill-learnings.mjs — normalize producer DIALECTS in learnings.jsonl.
+ *
+ * Epic #723 B2. The live corpus historically carried the rule-conversion scope
+ * under `files` (not the canonical `file_paths`), duplicated `source_session`
+ * into `session_id`, used `last_seen` instead of `updated_at`, and left
+ * `next_review: null` / non-canonical (no-millis) timestamps. This one-shot
+ * backfill routes every line through the schema SSOT (`migrateLegacyLearning`,
+ * which applies `normalizeDialects` + the insight/subject alias chain + a
+ * `schema_version:1` stamp), gates the result with `validateLearning`, and
+ * rewrites the file where a safe normalization exists.
+ *
+ * Data-loss safety (three guarantees):
+ *   - A line that fails `JSON.parse` is preserved byte-identical and counted
+ *     (`parse_errors`) — never dropped.
+ *   - A record that still fails `validateLearning` AFTER migration is passed
+ *     through byte-identical and counted (`invalid_after_migration`) — never
+ *     mutated, never flagged.
+ *   - `--apply` writes atomically (copy-to-`.bak-<ISO>` → tmp → rename), so the
+ *     canonical file always exists holding either the old or the new content.
+ *
+ * This script duplicates NO normalization logic — all shape work lives in
+ * `scripts/lib/learnings/schema.mjs`.
+ *
+ * Usage:
+ *   node scripts/backfill-learnings.mjs [--file PATH] [--apply|--dry-run]
+ *
+ * Modes:
+ *   (default / --dry-run)   compute + report intended rewrites per line; does
+ *                           not touch the file
+ *   --apply                 write the normalized file atomically via tmp+rename,
+ *                           after copying the original to `${file}.bak-<ISO>`
+ *
+ * Exit codes:
+ *   0 — completed (dry-run or apply)
+ *   1 — I/O error (file not found, unreadable, write failed)
+ *   2 — usage error (unknown argument)
+ *
+ * Output: JSON summary on stdout (single line)
+ *   {"scanned":N,"normalized":N,"unchanged":N,"parse_errors":N,
+ *    "invalid_after_migration":N,"applied":bool,"dry_run":bool,"backup":"<path>|null","file":"<path>"}
+ */
+
+import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import {
+  migrateLegacyLearning,
+  normalizeDialects,
+  validateLearning,
+  ValidationError,
+} from './lib/learnings/schema.mjs';
+
+const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
+
+function parseArgs(argv) {
+  const args = { file: DEFAULT_FILE, apply: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file') args.file = argv[++i];
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--dry-run') args.apply = false;
+    else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        'Usage: node scripts/backfill-learnings.mjs [--file PATH] [--apply|--dry-run]\n' +
+          '  --file      target learnings.jsonl (default: .orchestrator/metrics/learnings.jsonl)\n' +
+          '  --dry-run   report normalizations; do not modify file (default)\n' +
+          '  --apply     rewrite file atomically with a .bak-<ISO> backup\n'
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`backfill-learnings: unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+/**
+ * Classify + transform a single parsed record via the schema SSOT.
+ *
+ * Returns { outcome, line } where outcome is one of:
+ *   - 'unchanged'   : migration is a semantic no-op (serialized form matches input)
+ *   - 'normalized'  : migration changed the record AND it validates
+ *   - 'invalid'     : migration result still fails validateLearning → keep original
+ *
+ * @param {object} parsed — the JSON.parse'd record
+ * @param {string} originalLine — the verbatim source line (returned untouched on 'invalid')
+ * @returns {{ outcome: 'unchanged'|'normalized'|'invalid', line: string }}
+ */
+function processRecord(parsed, originalLine) {
+  // Two SSOT calls, no duplicated normalization logic:
+  //   1. migrateLegacyLearning — aliases + schema_version:1 stamp + dialects
+  //      (files→file_paths, session_id/last_seen/next_review), byte-exact timestamps.
+  //   2. normalizeDialects (full) — canonicalize timestamp FORMAT to millis+Z.
+  //      Idempotent for every other dialect (already handled in step 1).
+  const migrated = normalizeDialects(migrateLegacyLearning(parsed));
+
+  // Gate: a record that cannot pass the schema after migration is passed
+  // through byte-identical (never mutated, never flagged).
+  try {
+    validateLearning(migrated);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      return { outcome: 'invalid', line: originalLine };
+    }
+    throw err;
+  }
+
+  const migratedLine = JSON.stringify(migrated);
+  // Semantic-equality against the re-serialized parsed input: a migration that
+  // reorders nothing and changes no value is a no-op.
+  if (migratedLine === JSON.stringify(parsed)) {
+    return { outcome: 'unchanged', line: migratedLine };
+  }
+  return { outcome: 'normalized', line: migratedLine };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.file || !existsSync(args.file)) {
+    process.stderr.write(`backfill-learnings: file not found: ${args.file}\n`);
+    process.exit(1);
+  }
+
+  let lines;
+  try {
+    lines = readFileSync(args.file, 'utf8').split('\n').filter((l) => l.length > 0);
+  } catch (err) {
+    process.stderr.write(`backfill-learnings: read failed: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const outputLines = [];
+  const counts = {
+    scanned: 0,
+    normalized: 0,
+    unchanged: 0,
+    parse_errors: 0,
+    invalid_after_migration: 0,
+  };
+
+  for (const line of lines) {
+    counts.scanned++;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      counts.parse_errors++;
+      outputLines.push(line); // byte-identical preservation — never drop
+      continue;
+    }
+
+    const { outcome, line: outLine } = processRecord(parsed, line);
+    if (outcome === 'invalid') counts.invalid_after_migration++;
+    else counts[outcome]++;
+    outputLines.push(outLine);
+  }
+
+  const summary = {
+    scanned: counts.scanned,
+    normalized: counts.normalized,
+    unchanged: counts.unchanged,
+    parse_errors: counts.parse_errors,
+    invalid_after_migration: counts.invalid_after_migration,
+    applied: false,
+    dry_run: !args.apply,
+    backup: null,
+    file: args.file,
+  };
+
+  if (!args.apply) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+    return;
+  }
+
+  // Apply path — POSIX atomic replace, self-contained (no io.mjs dependency).
+  //   1. copyFileSync: canonical → .bak-<ISO>   (backup; canonical still present)
+  //   2. writeFileSync: normalized → tmp        (new content; canonical still present)
+  //   3. renameSync: tmp → canonical            (atomic replace per POSIX)
+  // The canonical file exists at every step, holding old or new content.
+  const iso = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${args.file}.bak-${iso}`;
+  const tmpPath = join(dirname(args.file), `.${basename(args.file)}.tmp-${process.pid}`);
+  try {
+    copyFileSync(args.file, backupPath);
+    writeFileSync(tmpPath, outputLines.join('\n') + '\n', 'utf8');
+    renameSync(tmpPath, args.file);
+    summary.applied = true;
+    summary.backup = backupPath;
+  } catch (err) {
+    const recoveryHint = existsSync(backupPath)
+      ? `Canonical file is intact; backup at ${backupPath}.`
+      : 'Backup was not created.';
+    process.stderr.write(`backfill-learnings: write failed: ${err.message}. ${recoveryHint}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify(summary) + '\n');
+}
+
+main();

package/scripts/backfill-sessions.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * backfill-sessions.mjs — normalize legacy shapes in sessions.jsonl.
+ *
+ * Issue #249 follow-up. Reads a sessions.jsonl file and rewrites each line
+ * into the canonical schema_version=2 shape (bumped 1 -> 2 via #372) where a
+ * safe deterministic mapping exists. Entries that cannot be safely mapped are
+ * tagged `_deprecated: true` (preserved but flagged — never dropped).
+ *
+ * Usage:
+ *   node scripts/backfill-sessions.mjs [--file PATH] [--apply] [--mark-deprecated-only]
+ *
+ * Modes:
+ *   (default / --dry-run)   reports intended rewrites + deprecations per line;
+ *                           does not touch the file
+ *   --apply                 writes the rewritten file atomically via temp+rename;
+ *                           creates a `.bak-<ISO>` backup of the original
+ *   --mark-deprecated-only  same as --apply but only tags unmappable entries
+ *                           with `_deprecated: true`; leaves mappable entries
+ *                           untouched (conservative path)
+ *
+ * Exit codes:
+ *   0 — completed (dry-run or apply)
+ *   1 — I/O error (unreadable file, write failed)
+ *   2 — usage error
+ *
+ * Output: JSON summary on stdout
+ *   {"mode":"dry-run|apply|mark-deprecated-only","total":N,"rewritten":N,"deprecated":N,"unchanged":N,"backup":"<path>|null"}
+ */
+
+import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
+
+const DEFAULT_FILE = '.orchestrator/metrics/sessions.jsonl';
+
+/**
+ * Line numbers (1-indexed) known to be unmappable per D1 inventory. These
+ * entries have fundamentally divergent shape (e.g., `waves: null` scalar
+ * counts, alternative telemetry models) that cannot be deterministically
+ * converted without data loss. Marked `_deprecated: true` on apply.
+ *
+ * The logic below also independently detects unmappable entries by shape,
+ * so this list is informational — identification is structural, not
+ * positional. If the file is truncated or reordered, the shape-check still
+ * fires.
+ */
+const KNOWN_UNMAPPABLE_SHAPES = Object.freeze({
+  // `waves` is null (scalar counts via waves_completed/waves_total — array
+  // cannot be reconstructed):
+  wavesIsNull: (e) => e.waves === null,
+  // `waves` is a number (integer count, not an array):
+  wavesIsNumber: (e) => typeof e.waves === 'number',
+  // `waves_executed` scalar instead of `waves` array — array not reconstructible:
+  wavesExecutedScalar: (e) => typeof e.waves_executed === 'number' && !('waves' in e),
+  // head_ref + metrics-object variant (windows-native experiment) — no
+  // canonical mapping for the `metrics` bag:
+  metricsObjectShape: (e) => 'metrics' in e && !('agent_summary' in e),
+});
+
+/**
+ * Value-transforming aliases not safe for session-schema.mjs (which only
+ * does same-shape renames). Applied here because backfill has full context.
+ */
+function applyValueAliases(e) {
+  const next = { ...e };
+  // duration_min / duration_minutes → duration_seconds (multiply by 60)
+  if ('duration_min' in next && !('duration_seconds' in next)) {
+    if (typeof next.duration_min === 'number' && next.duration_min >= 0) {
+      next.duration_seconds = next.duration_min * 60;
+    }
+  }
+  if ('duration_minutes' in next && !('duration_seconds' in next)) {
+    if (typeof next.duration_minutes === 'number' && next.duration_minutes >= 0) {
+      next.duration_seconds = next.duration_minutes * 60;
+    }
+  }
+  // agent_summary reconstruction from agents_complete/partial/failed/dispatched
+  // ONLY when waves scalar does NOT indicate a fundamentally different shape.
+  // Ambiguous without `spiral` — synthesize as 0 if reconstruction is attempted.
+  if (
+    !('agent_summary' in next) &&
+    typeof next.agents_complete === 'number' &&
+    typeof next.agents_partial === 'number' &&
+    typeof next.agents_failed === 'number'
+  ) {
+    next.agent_summary = {
+      complete: next.agents_complete,
+      partial: next.agents_partial,
+      failed: next.agents_failed,
+      spiral: typeof next.agents_spiral === 'number' ? next.agents_spiral : 0,
+    };
+  }
+  // total_agents: derive from agents_dispatched if missing
+  if (!('total_agents' in next) && typeof next.agents_dispatched === 'number') {
+    next.total_agents = next.agents_dispatched;
+  }
+  // total_files_changed: derive from files_changed scalar (if a number)
+  if (!('total_files_changed' in next) && typeof next.files_changed === 'number') {
+    next.total_files_changed = next.files_changed;
+  }
+  // total_waves: derive from waves_total or waves_completed scalar
+  if (!('total_waves' in next)) {
+    if (typeof next.waves_total === 'number') next.total_waves = next.waves_total;
+    else if (typeof next.waves_completed === 'number') next.total_waves = next.waves_completed;
+  }
+  return next;
+}
+
+function detectUnmappableReason(entry) {
+  for (const [name, check] of Object.entries(KNOWN_UNMAPPABLE_SHAPES)) {
+    if (check(entry)) return name;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = { file: DEFAULT_FILE, mode: 'dry-run' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file') args.file = argv[++i];
+    else if (a === '--apply') args.mode = 'apply';
+    else if (a === '--dry-run') args.mode = 'dry-run';
+    else if (a === '--mark-deprecated-only') args.mode = 'mark-deprecated-only';
+    else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        'Usage: node scripts/backfill-sessions.mjs [--file PATH] [--apply|--dry-run|--mark-deprecated-only]\n' +
+          '  --file                   target sessions.jsonl (default: .orchestrator/metrics/sessions.jsonl)\n' +
+          '  --dry-run                report rewrites; do not modify file (default)\n' +
+          '  --apply                  rewrite file atomically with .bak-<ISO> backup\n' +
+          '  --mark-deprecated-only   tag only unmappable entries with _deprecated:true\n'
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`backfill-sessions: unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+/**
+ * Process a single entry. Returns { outcome, entry } where outcome is one
+ * of: 'unchanged' | 'rewritten' | 'deprecated'.
+ *
+ *   - 'unchanged': transforms are a no-op (entry already canonical byte-equivalent)
+ *   - 'rewritten': entry was transformed (safe aliases + value-transforming aliases)
+ *                  and the result validates as v1
+ *   - 'deprecated': structurally unmappable OR validation still fails after
+ *                   transforms; tagged with _deprecated:true
+ */
+function processEntry(raw) {
+  const structuralReason = detectUnmappableReason(raw);
+  if (structuralReason) {
+    return {
+      outcome: 'deprecated',
+      entry: { ...raw, _deprecated: true, _deprecation_reason: `structural: ${structuralReason}` },
+    };
+  }
+
+  // Always run the transform pipeline so value-alias reconstruction happens
+  // even on entries that would pass validation without it.
+  let transformed = normalizeSession(raw);
+  transformed = applyValueAliases(transformed);
+  // Drop normalizeSession's read-path schema_version:0 stamp so validateSession
+  // stamps the canonical 1 on successful rewrites.
+  if (transformed.schema_version === 0 && !('schema_version' in raw)) {
+    delete transformed.schema_version;
+  }
+
+  let validated;
+  try {
+    validated = validateSession(transformed);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      return {
+        outcome: 'deprecated',
+        entry: { ...raw, _deprecated: true, _deprecation_reason: err.message },
+      };
+    }
+    throw err;
+  }
+
+  // "Unchanged" means: the serialized form matches the serialized original.
+  // This preserves byte-identical behavior for already-canonical entries
+  // while still classifying entries that needed any transform as rewritten.
+  if (JSON.stringify(validated) === JSON.stringify(raw)) {
+    return { outcome: 'unchanged', entry: raw };
+  }
+  return { outcome: 'rewritten', entry: validated };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!existsSync(args.file)) {
+    process.stderr.write(`backfill-sessions: file not found: ${args.file}\n`);
+    process.exit(1);
+  }
+
+  let lines;
+  try {
+    lines = readFileSync(args.file, 'utf8').split('\n').filter((l) => l.length > 0);
+  } catch (err) {
+    process.stderr.write(`backfill-sessions: read failed: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const perLine = [];
+  const rewritten = [];
+  const counts = { unchanged: 0, rewritten: 0, deprecated: 0, parseError: 0 };
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    let raw;
+    try {
+      raw = JSON.parse(lines[i]);
+    } catch (err) {
+      counts.parseError++;
+      perLine.push({ line: lineNum, outcome: 'parse-error', reason: err.message });
+      rewritten.push(lines[i]); // preserve original line verbatim
+      continue;
+    }
+    const { outcome, entry } = processEntry(raw);
+    counts[outcome]++;
+    perLine.push({ line: lineNum, outcome, session_id: raw.session_id ?? null });
+    if (args.mode === 'mark-deprecated-only' && outcome === 'rewritten') {
+      // Conservative: leave mappable entries as-is.
+      rewritten.push(lines[i]);
+    } else {
+      rewritten.push(JSON.stringify(entry));
+    }
+  }
+
+  const summary = {
+    mode: args.mode,
+    file: args.file,
+    total: lines.length,
+    unchanged: counts.unchanged,
+    rewritten: counts.rewritten,
+    deprecated: counts.deprecated,
+    parse_errors: counts.parseError,
+    backup: null,
+  };
+
+  if (args.mode === 'dry-run') {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+    process.stdout.write(JSON.stringify({ detail: perLine }) + '\n');
+    return;
+  }
+
+  // Apply path — POSIX atomic replace (tmp → rename-over-canonical) preceded
+  // by a pre-write copy-to-backup. This eliminates the crash window where the
+  // canonical path could be briefly missing if the rename dance were split:
+  //   1. copyFileSync: canonical → .bak-<ISO>  (backup; canonical still present)
+  //   2. writeFileSync: rewritten → tmp        (new content; canonical still present)
+  //   3. renameSync: tmp → canonical           (atomic replace per POSIX)
+  // At every point between steps, the canonical file exists and holds either
+  // the old content or the new content. Recovery artifact: .bak-<ISO>.
+  const iso = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${args.file}.bak-${iso}`;
+  const tmpPath = join(dirname(args.file), `.${basename(args.file)}.tmp-${process.pid}`);
+  try {
+    copyFileSync(args.file, backupPath);
+    writeFileSync(tmpPath, rewritten.join('\n') + '\n', 'utf8');
+    renameSync(tmpPath, args.file);
+    summary.backup = backupPath;
+  } catch (err) {
+    const recoveryHint = existsSync(backupPath)
+      ? `Canonical file is intact; backup at ${backupPath}.`
+      : 'Backup was not created.';
+    process.stderr.write(`backfill-sessions: write failed: ${err.message}. ${recoveryHint}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify(summary) + '\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`backfill-sessions: unexpected error: ${err?.stack ?? err}\n`);
+  process.exit(1);
+});