session-orchestrator 5.9.0 → 5.11.0

package/scripts/fleet-checkin-audit.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/** Read-only CLI for explicitly supplied, stable snapshot copies (#1462). */
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+import { auditCheckins } from './lib/fleet-checkin-audit.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const HELP = `Usage: fleet-checkin-audit --input-root DIR --registry FILE --checkins FILE --repo KEY [--repo KEY] --at UTC [--json]
+All five input flags are required. --repo may repeat with distinct explicit keys.
+--at is an exact UTC instant (YYYY-MM-DDTHH:MM:SS[.sss]Z).
+--json emits one JSON report; --help and --version are standalone commands.
+Supply complete registry/check-in snapshot copies with capture times matching --at.
+Only explicit regular files inside --input-root are read; symlinks are refused.
+Use stable trusted copies: simultaneous parent-directory renames are not atomic.
+No discovery, live configuration, referenced-repo reads, events or input writes.
+Exit 0: measured, including findings; 1: invalid arguments, paths or JSON;
+2: unavailable inputs/system I/O; 3: incomplete or not-measurable snapshot evidence.
+stdout contains the report; stderr contains only diagnostics.
+`;
+const failure = (category, exit, errno) => Object.assign(new Error(category), { category, exit, errno });
+
+function argumentsFor(argv) {
+  const args = { repos: [], json: false };
+  const values = new Map([['--input-root', 'root'], ['--registry', 'registry'], ['--checkins', 'checkins'], ['--at', 'at']]);
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--json') { args.json = true; continue; }
+    if (flag === '--help' || flag === '--version') {
+      if (argv.length !== 1) throw failure('invalid-arguments', 1);
+      args.action = flag;
+      return args;
+    }
+    if (flag !== '--repo' && !values.has(flag)) throw failure('invalid-arguments', 1);
+    const value = argv[++i];
+    if (!value || value.startsWith('--')) throw failure('invalid-arguments', 1);
+    if (flag === '--repo') args.repos.push(value);
+    else {
+      const key = values.get(flag);
+      if (args[key] !== undefined) throw failure('duplicate-argument', 1);
+      args[key] = value;
+    }
+  }
+  if (!args.root || !args.registry || !args.checkins || !args.at || !args.repos.length) throw failure('missing-arguments', 1);
+  if (new Set(args.repos).size !== args.repos.length || args.repos.some((repo) => repo.trim() !== repo)) {
+    throw failure('invalid-repo-selection', 1);
+  }
+  const instant = Date.parse(args.at);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(args.at)
+    || !Number.isFinite(instant)
+    || new Date(instant).toISOString() !== args.at.replace(/Z$/, args.at.includes('.') ? 'Z' : '.000Z')) {
+    throw failure('invalid-measurement-time', 1);
+  }
+  return args;
+}
+
+/** Inspect every component before reading contents; parent rename races remain
+ * outside this portable path-based reader's guarantee (use stable copies). */
+async function inspect(root, name) {
+  const target = path.resolve(root, name);
+  const relative = path.relative(root, target);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw failure('path-outside-input-root', 1);
+  }
+  const parsed = path.parse(target);
+  let current = parsed.root;
+  let stat;
+  const components = target.slice(parsed.root.length).split(path.sep);
+  for (let i = 0; i < components.length; i++) {
+    current = path.join(current, components[i]);
+    stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) throw failure('symlink-input', 1);
+    if (i < components.length - 1 && !stat.isDirectory()) throw failure('non-directory-parent', 1);
+  }
+  if (!stat?.isFile()) throw failure('non-regular-input', 1);
+  return { target, stat };
+}
+
+async function readSnapshot({ target, stat }) {
+  // The parent check above and this open are not atomic: a same-user process can swap a parent
+  // directory in between. Fine while the operator names the snapshot files and the result grants
+  // nothing; revisit (#1549) once paths come from a foreign owner or the result gates a decision.
+  if (typeof constants.O_NOFOLLOW !== 'number' || typeof constants.O_NONBLOCK !== 'number') {
+    throw failure('unsupported-safe-open', 2);
+  }
+  const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let bytes;
+  try {
+    const actual = await handle.stat();
+    if (!actual.isFile() || actual.dev !== stat.dev || actual.ino !== stat.ino) throw failure('changed-input-file', 1);
+    bytes = await handle.readFile();
+  } finally { await handle.close(); }
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { throw failure('malformed-json-or-utf8', 1); }
+}
+
+function render(report) {
+  if (report.error) return `not-measurable: ${report.error.category}\n`;
+  return [`status: ${report.status}`, ...Object.entries(report.metrics).map(([key, metric]) =>
+    `${key}: ${metric.status === 'measured' ? metric.value : `not-measurable (${metric.reasons.join(', ')})`}`)].join('\n') + '\n';
+}
+
+/** The real CLI boundary; callers may route its output to their own streams. */
+export async function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let args;
+  try {
+    args = argumentsFor(argv);
+    if (args.action === '--help') { io.stdout.write(HELP); return 0; }
+    if (args.action === '--version') {
+      const manifest = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
+      io.stdout.write(`${manifest.version}\n`);
+      return 0;
+    }
+    const root = path.resolve(args.root);
+    // Inspect BOTH paths before opening either snapshot for content.
+    const registryFile = await inspect(root, args.registry);
+    const checkinFile = await inspect(root, args.checkins);
+    const registry = await readSnapshot(registryFile);
+    const checkins = await readSnapshot(checkinFile);
+    const report = auditCheckins({ registry, checkins, repos: args.repos, at: args.at });
+    io.stdout.write(args.json ? `${JSON.stringify(report)}\n` : render(report));
+    return report.status === 'measured' ? 0 : 3;
+  } catch (error) {
+    const category = error.category || 'input-io-error';
+    const errno = typeof error.code === 'string' && /^[A-Z0-9_]+$/.test(error.code) ? error.code : undefined;
+    const report = { version: 1, status: 'not-measurable', error: { category, ...(errno ? { errno } : {}) } };
+    io.stderr.write(`fleet-checkin-audit: ${category}${errno ? ` (${errno})` : ''}\n`);
+    io.stdout.write((args?.json || argv.includes('--json')) ? `${JSON.stringify(report)}\n` : render(report));
+    return error.exit || 2;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }, () => {
+    process.stderr.write('fleet-checkin-audit: output-io-error\n');
+    process.exitCode = 2;
+  });
+}

package/scripts/lib/common.mjs

@@ -12,7 +12,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { promises as fs, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+import { commandOnPath } from './native-command.mjs';
 
 // ---------------------------------------------------------------------------
 // Path helpers
@@ -182,9 +182,7 @@ export function warn(message) {
  * @throws {Error} when jq is not on PATH
  */
 export function requireJq() {
-  try {
-    execSync('command -v jq', { stdio: 'ignore', shell: true });
-  } catch {
+  if (!commandOnPath('jq')) {
     throw new Error('jq is required but not installed. Install via: brew install jq');
   }
 }

package/scripts/lib/context-overhead-format.mjs

@@ -0,0 +1,57 @@
+/** Format Claude JSON accounting without inventing a price or its provenance. */
+import { isMainModule } from './is-main-module.mjs';
+import { COST_BASIS } from './telemetry/pricing.mjs';
+
+export const CONTEXT_OVERHEAD_HEADER =
+  'LABEL\tCONTEXT_TOK\tcache_create\tcache_read\toutput\tUSD\tCOST_BASIS\n';
+
+/**
+ * @param {string} text JSON response text
+ * @param {string} label measurement label
+ * @returns {string} TSV row, or a recognizable PARSE-ERROR / NO-USAGE row
+ */
+export function formatContextOverhead(text, label) {
+  let response;
+  try {
+    response = JSON.parse(text);
+  } catch {
+    return `${label}\tPARSE-ERROR\n`;
+  }
+  const usage = response?.usage;
+  // An error reply (e.g. "Not logged in") carries no usage; 0 tokens would be invented (#1547).
+  if (typeof usage !== 'object' || usage === null || Array.isArray(usage)) {
+    return `${label}\tNO-USAGE\n`;
+  }
+  const context =
+    (usage.input_tokens || 0) +
+    (usage.cache_creation_input_tokens || 0) +
+    (usage.cache_read_input_tokens || 0);
+  const cost = response?.total_cost_usd;
+  const validCost = typeof cost === 'number' && Number.isFinite(cost) && cost >= 0;
+  // Native numbers alone do not establish billing or API-list provenance.
+  const basis = validCost && response.cost_basis === COST_BASIS
+    ? response.cost_basis
+    : 'unknown';
+  return [
+    label, context, usage.cache_creation_input_tokens || 0,
+    usage.cache_read_input_tokens || 0, usage.output_tokens || 0,
+    validCost ? cost.toFixed(4) : 'unknown', basis,
+  ].join('\t') + '\n';
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === '--header') {
+    process.stdout.write(CONTEXT_OVERHEAD_HEADER);
+  } else if (args.length === 2 && args[0] === '--') {
+    let text = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { text += chunk; });
+    process.stdin.on('end', () => {
+      process.stdout.write(formatContextOverhead(text, args[1]));
+    });
+  } else {
+    process.stderr.write('Usage: context-overhead-format.mjs --header | -- <label> (JSON on stdin)\n');
+    process.exitCode = 1;
+  }
+}

package/scripts/lib/fleet-checkin-audit.mjs

@@ -0,0 +1,244 @@
+/** Pure audit of explicitly complete, caller-supplied fleet snapshots (#1462). */
+import { validateCheckin } from './fleet-protocol.mjs';
+
+const THIRTY_MINUTES_MS = 30 * 60 * 1000;
+const FRESHNESS_MS = 15 * 60 * 1000;
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => typeof v === 'string' && v.length > 0 && v.trim() === v;
+
+// Require an unambiguous UTC instant and reject Date.parse's calendar rollover.
+function instant(v) {
+  if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(v)) return NaN;
+  const ms = Date.parse(v);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === v.replace(/Z$/, v.includes('.') ? 'Z' : '.000Z') ? ms : NaN;
+}
+
+/** Canonical issue IID, preserving the existing integer/string check-in contract. */
+export function normalizeCandidate(value) {
+  if (typeof value === 'number') return Number.isSafeInteger(value) && value >= 0 ? String(value) : null;
+  if (typeof value !== 'string' || !/^#?\d{1,9}$/.test(value)) return null;
+  return String(Number(value.replace(/^#/, '')));
+}
+
+const measurement = (value, reasons) => ({
+  status: reasons.length ? 'not-measurable' : 'measured',
+  value: reasons.length ? null : value,
+  reasons: [...new Set(reasons)],
+});
+
+function snapshotProblems(snapshot, name, at) {
+  const reasons = [];
+  if (!object(snapshot)) return [`${name}:missing-snapshot`];
+  if (snapshot.version !== 1) reasons.push(`${name}:unsupported-version`);
+  if (snapshot.complete !== true) reasons.push(`${name}:incomplete-population`);
+  if (!Array.isArray(snapshot.records)) reasons.push(`${name}:missing-records`);
+  if (!Number.isFinite(instant(snapshot.captured_at)) || instant(snapshot.captured_at) !== at) {
+    reasons.push(`${name}:capture-time-mismatch`);
+  }
+  return reasons;
+}
+
+function bindRepos(bindings, issues) {
+  const keys = new Set();
+  const hashes = new Map();
+  const names = new Map();
+  const reasons = [];
+  const fail = (index, code) => {
+    issues.push({ source: 'bindings', index, code });
+    reasons.push(`bindings:${code}`);
+  };
+  if (!Array.isArray(bindings)) {
+    fail(null, 'missing-bindings');
+    return { keys, hashes, names, reasons };
+  }
+  const insert = (map, value, key, index) => {
+    if (map.has(value)) fail(index, 'duplicate-identity');
+    else map.set(value, key);
+  };
+  bindings.forEach((binding, index) => {
+    if (!object(binding) || !text(binding.repo_key)
+      || !Array.isArray(binding.registry_hashes) || binding.registry_hashes.length === 0
+      || !binding.registry_hashes.every((v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v))
+      || !Array.isArray(binding.checkin_repos) || binding.checkin_repos.length === 0
+      || !binding.checkin_repos.every(text)) {
+      fail(index, 'invalid-binding');
+      return;
+    }
+    if (keys.has(binding.repo_key)) fail(index, 'duplicate-repo-key');
+    keys.add(binding.repo_key);
+    binding.registry_hashes.forEach((v) => insert(hashes, v, binding.repo_key, index));
+    binding.checkin_repos.forEach((v) => insert(names, v, binding.repo_key, index));
+  });
+  return { keys, hashes, names, reasons };
+}
+
+function duplicates(rows, field, source, issues) {
+  const counts = new Map();
+  for (const row of rows) {
+    const id = row.record?.[field];
+    if (text(id)) counts.set(id, (counts.get(id) || 0) + 1);
+  }
+  for (const row of rows) {
+    if (counts.get(row.record?.[field]) > 1) {
+      row.ambiguous = true;
+      issues.push({ source, index: row.index, code: 'duplicate-session' });
+    }
+  }
+}
+
+const usable = (row) => row.errors.length === 0 && !row.ambiguous;
+function summarize(rows, present) {
+  if (!present) return { raw: null, valid: null, invalid: null, ambiguous: null, stale: null };
+  return {
+    raw: rows.length,
+    valid: rows.filter(usable).length,
+    invalid: rows.filter((row) => row.errors.length > 0).length,
+    ambiguous: rows.filter((row) => row.ambiguous).length,
+    stale: rows.filter((row) => usable(row) && row.stale).length,
+  };
+}
+
+/**
+ * No filesystem, clock, environment, or input mutation. Repo bindings and history
+ * completeness are assertions of the caller, never independently discovered.
+ * @param {{registry?: object, checkins?: object, repos?: string[], at?: string}} input
+ */
+export function auditCheckins({ registry, checkins, repos, at } = {}) {
+  const now = instant(at);
+  const issues = [];
+  const common = [];
+  if (!Number.isFinite(now)) common.push('audit:invalid-measurement-time');
+  const binding = bindRepos(registry?.repo_bindings, issues);
+  common.push(...binding.reasons);
+  if (!Array.isArray(repos) || repos.length === 0 || !repos.every(text)
+    || new Set(repos).size !== repos.length) common.push('audit:invalid-repo-selection');
+  const selected = new Set(Array.isArray(repos) ? repos : []);
+  if ([...selected].some((repo) => !binding.keys.has(repo))) common.push('audit:unknown-selected-repo');
+
+  const registryReasons = [...common, ...snapshotProblems(registry, 'registry', now)];
+  const checkinReasons = [...snapshotProblems(checkins, 'checkins', now)];
+  const registryRows = (Array.isArray(registry?.records) ? registry.records : []).map((record, index) => {
+    const errors = [];
+    if (!object(record) || !text(record.session_id) || /[\\/]/.test(record.session_id) || record.session_id.includes('\x00')
+      || record.session_id === '.' || record.session_id === '..'
+      || ('mode' in record && record.mode !== null && typeof record.mode !== 'string')
+      || ('role' in record && record.role !== null && typeof record.role !== 'string')) errors.push('invalid-registry-record');
+    const repo = binding.hashes.get(record?.repo_path_hash);
+    if (!repo) errors.push('unknown-repo-identity');
+    const start = instant(record?.started_at);
+    const heartbeat = instant(record?.last_heartbeat);
+    if (!Number.isFinite(start) || !Number.isFinite(heartbeat) || start > heartbeat || heartbeat > now) errors.push('invalid-registry-time');
+    return { record, index, repo, start, heartbeat, errors, ambiguous: false, stale: now - heartbeat > FRESHNESS_MS };
+  });
+  duplicates(registryRows, 'session_id', 'registry', issues);
+  for (const row of registryRows) {
+    for (const code of row.errors) issues.push({ source: 'registry', index: row.index, code });
+    if (!usable(row)) registryReasons.push('registry:invalid-or-ambiguous-records');
+  }
+  const checkinRows = (Array.isArray(checkins?.records) ? checkins.records : []).map((record, index) => {
+    const errors = validateCheckin(record).length ? ['invalid-checkin-record'] : [];
+    const repo = binding.names.get(record?.repo);
+    if (!repo) errors.push('unknown-repo-identity');
+    const time = instant(record?.zeit);
+    if (!Number.isFinite(time) || time > now) errors.push('invalid-checkin-time');
+    const candidates = Array.isArray(record?.kandidaten) ? record.kandidaten.map(normalizeCandidate) : [];
+    if (candidates.includes(null)) errors.push('invalid-candidate');
+    const matches = registryRows.filter((r) => usable(r) && r.record.session_id === record?.session && r.repo === repo);
+    if (matches.length !== 1) errors.push('unmatched-session-identity');
+    else if (time < matches[0].start) errors.push('checkin-before-registration');
+    return { record, index, repo, time, candidates, errors, ambiguous: false, registry: matches[0], stale: false };
+  });
+  duplicates(checkinRows, 'session', 'checkins', issues);
+  for (const row of checkinRows) {
+    for (const code of row.errors) issues.push({ source: 'checkins', index: row.index, code });
+    if (!usable(row)) checkinReasons.push('checkins:invalid-or-ambiguous-records');
+  }
+
+  const population = registryRows.filter((row) => usable(row) && selected.has(row.repo));
+  const fresh = population.filter((row) => !row.stale);
+  const due = fresh.filter((row) => now - row.start >= THIRTY_MINUTES_MS);
+  const missing = due.filter((row) => !checkinRows.some((c) => usable(c) && c.registry === row));
+  const pointReasons = [...registryReasons, ...checkinReasons];
+
+  const coverage = checkins?.coverage;
+  const historyReasons = [...pointReasons];
+  const from = instant(coverage?.from);
+  const to = instant(coverage?.to);
+  if (!object(coverage) || coverage.complete !== true || !Number.isFinite(from)
+    || !Number.isFinite(to) || from >= to || to > now) historyReasons.push('history:missing-or-invalid-coverage');
+  if (!Array.isArray(checkins?.claims)) historyReasons.push('history:missing-claims');
+  const claims = (Array.isArray(checkins?.claims) ? checkins.claims : []).map((claim, index) => {
+    const errors = [];
+    const start = instant(claim?.from);
+    const end = instant(claim?.to);
+    const candidate = normalizeCandidate(claim?.candidate);
+    if (!object(claim) || !text(claim.session) || !text(claim.repo_key)
+      || !text(claim.evidence_ref) || candidate === null) errors.push('invalid-claim');
+    const matches = checkinRows.filter((c) => usable(c) && c.record.session === claim?.session
+      && c.repo === claim?.repo_key && c.candidates.includes(candidate));
+    if (matches.length !== 1) errors.push('unmatched-claim-identity');
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end || end > now
+      || start < from || end > to || (matches.length === 1 && start < matches[0].time)) errors.push('invalid-claim-interval');
+    for (const code of errors) issues.push({ source: 'claims', index, code });
+    if (errors.length) historyReasons.push('history:invalid-claims');
+    return { index, session: claim?.session, repo_key: claim?.repo_key, candidate, from: start, to: end, errors };
+  });
+  // Repeated/overlapping evidence for one session is ambiguous; do not multiply
+  // collision counts by silently treating those claims as independent starts.
+  for (let i = 0; i < claims.length; i++) {
+    for (let j = i + 1; j < claims.length; j++) {
+      const a = claims[i]; const b = claims[j];
+      if (!a.errors.length && !b.errors.length && a.session === b.session
+        && a.repo_key === b.repo_key && a.candidate === b.candidate
+        && Math.max(a.from, b.from) < Math.min(a.to, b.to)) {
+        historyReasons.push('history:duplicate-overlapping-claims');
+        issues.push({ source: 'claims', index: b.index, code: 'duplicate-overlapping-claims' });
+      }
+    }
+  }
+  const collisions = [];
+  for (let i = 0; i < claims.length; i++) {
+    for (let j = i + 1; j < claims.length; j++) {
+      const a = claims[i]; const b = claims[j];
+      if (!a.errors.length && !b.errors.length && a.session !== b.session
+        && selected.has(a.repo_key) && a.repo_key === b.repo_key && a.candidate === b.candidate
+        && Math.max(a.from, b.from) < Math.min(a.to, b.to)) {
+        collisions.push({ repo_key: a.repo_key, candidate: a.candidate, sessions: [a.session, b.session],
+          from: new Date(Math.max(a.from, b.from)).toISOString(), to: new Date(Math.min(a.to, b.to)).toISOString() });
+      }
+    }
+  }
+  const currentCandidates = [];
+  for (const row of checkinRows.filter((c) => usable(c) && selected.has(c.repo) && !c.registry.stale)) {
+    for (const candidate of new Set(row.candidates)) {
+      currentCandidates.push({ repo_key: row.repo, session: row.record.session, candidate });
+    }
+  }
+  const metrics = {
+    selected: measurement(population.length, registryReasons),
+    fresh: measurement(fresh.length, registryReasons),
+    due: measurement(due.length, registryReasons),
+    missing_after_30m: measurement(missing.length, pointReasons),
+    collisions: measurement(collisions.length, historyReasons),
+  };
+  return {
+    version: 1,
+    status: Object.values(metrics).every((metric) => metric.status === 'measured') ? 'measured' : 'not-measurable',
+    at: typeof at === 'string' ? at : null,
+    repos: [...selected],
+    snapshots: {
+      registry: summarize(registryRows, Array.isArray(registry?.records)),
+      checkins: summarize(checkinRows, Array.isArray(checkins?.records)),
+    },
+    metrics,
+    coverage: historyReasons.includes('history:missing-or-invalid-coverage') ? null : {
+      complete: true, from: new Date(from).toISOString(), to: new Date(to).toISOString(),
+    },
+    issues,
+    findings: {
+      missing_sessions: pointReasons.length ? [] : missing.map((row) => ({ repo_key: row.repo, session: row.record.session_id })),
+      collisions: historyReasons.length ? [] : collisions,
+      current_candidates: pointReasons.length ? [] : currentCandidates,
+    },
+  };
+}

package/scripts/lib/gates/gate-full.mjs

@@ -227,4 +227,10 @@ if (failed) {
   }
 }
 
+// stderr is asynchronous when piped (pre-push/offload capture). Drain queued
+// writes before the forced exit; natural exit would retain kill-ladder timers.
+await Promise.all([
+  new Promise((resolve) => process.stdout.write('', resolve)),
+  new Promise((resolve) => process.stderr.write('', resolve)),
+]);
 process.exit(failed ? 2 : 0);

package/scripts/lib/gates/gate-helpers.mjs

@@ -565,6 +565,8 @@ export function extractTestCounts(output) {
   const EMPTY = { passed: 0, failed: 0, total: 0, files: null };
   if (!output) return EMPTY;
 
+  // Colored Vitest labels must match the same summaries as piped plain text.
+  output = output.replace(ANSI_ESCAPE, '');
   const lines = output.split('\n');
   const summaryLines = lines.filter((line) => TEST_SUMMARY_LINE.test(line));
   const scope = summaryLines.length > 0 ? summaryLines[summaryLines.length - 1] : output;

package/scripts/lib/memory-proposals/sink.mjs

@@ -42,7 +42,7 @@
  */
 
 import { appendFile, mkdir, readdir, rm } from 'node:fs/promises';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, lstatSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { appendLearning } from '../learnings/io.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
@@ -64,6 +64,66 @@ const PROPOSALS_ARCHIVE_REL = path.join('.orchestrator', 'runtime', 'proposals-a
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Close the shared validator's ENOENT gap for sink targets (#1544).
+ * Resolve the nearest existing component, including dangling symlinks, before
+ * mkdir/append can follow it. Canonical roots permit root aliases and temporary
+ * directory aliases. Like the store guard, this is check-before-write: revisit
+ * if another principal can modify these parents between validation and writing.
+ */
+function validateSinkTarget(relPath, repoRoot) {
+  try {
+    let root = path.resolve(repoRoot);
+    for (let ancestor = root; ; ancestor = path.dirname(ancestor)) {
+      try {
+        lstatSync(ancestor);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw err;
+      }
+      try {
+        root = path.resolve(realpathSync(ancestor), path.relative(ancestor, root));
+      } catch (err) {
+        if (err?.code === 'ENOENT' || err?.code === 'ELOOP') return { ok: false, reason: 'symlink' };
+        throw err;
+      }
+      break;
+    }
+    const result = validatePathInsideProject(relPath, root, { canonicalizeRoot: true });
+    if (!result.ok || result.realPath !== undefined) return result;
+    const fold = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
+    const inside = (p) => {
+      const relative = path.relative(fold(root), fold(p));
+      return relative === '' || (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative));
+    };
+    for (let current = result.lexicalPath; inside(current); current = path.dirname(current)) {
+      try {
+        lstatSync(current);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw err;
+      }
+      try {
+        return inside(realpathSync(current)) ? result : { ok: false, reason: 'symlink' };
+      } catch (err) {
+        if (err?.code !== 'ENOENT' && err?.code !== 'ELOOP') throw err;
+        // A dangling link is an existing component whose resolution failed.
+        // A concurrently removed ordinary component can safely defer upward.
+        try {
+          lstatSync(current);
+        } catch (retryErr) {
+          if (retryErr?.code === 'ENOENT') continue;
+          throw retryErr;
+        }
+        return { ok: false, reason: 'symlink' };
+      }
+    }
+    return result; // A missing trusted root will be created as a plain tree.
+  } catch {
+    return { ok: false, reason: 'filesystem' };
+  }
+}
+
 /**
  * Build a learning record from an approved proposal.
  *
@@ -159,7 +219,7 @@ export async function writeApproved({ approved, repoRoot, sessionId, ...rest })
     return { written: 0, errors: [] };
   }
 
-  const learningsResult = validatePathInsideProject(LEARNINGS_REL, repoRoot, { canonicalizeRoot: true });
+  const learningsResult = validateSinkTarget(LEARNINGS_REL, repoRoot);
   if (!learningsResult.ok) {
     return { written: 0, errors: [`path-safety: ${learningsResult.reason} (${LEARNINGS_REL})`] };
   }
@@ -202,7 +262,7 @@ export async function archiveRejected({ rejected, repoRoot, reason }) {
     return { archived: 0, errors: [] };
   }
 
-  const rejectedResult = validatePathInsideProject(REJECTED_LOG_REL, repoRoot, { canonicalizeRoot: true });
+  const rejectedResult = validateSinkTarget(REJECTED_LOG_REL, repoRoot);
   if (!rejectedResult.ok) {
     return { archived: 0, errors: [`path-safety: ${rejectedResult.reason} (${REJECTED_LOG_REL})`] };
   }
@@ -260,8 +320,9 @@ export async function archiveRejected({ rejected, repoRoot, reason }) {
  *     call actually wrote anything, so a caller-side mistake (wrong arg name,
  *     partial write failure) no longer means the queued proposals are gone
  *     for good — they are recoverable from the archive sidecar. Best-effort:
- *     an archive failure never blocks the clear itself, and an empty/missing
- *     proposals.jsonl produces no archive append (nothing to preserve).
+ *     ordinary archive I/O failures do not block clear. An unsafe required
+ *     recovery target blocks clear and preserves the queue and summaries.
+ *     An empty/missing proposals.jsonl produces no archive append.
  *  1. Clear proposals.jsonl via tmp-file + rename (POSIX-atomic on the same
  *     filesystem) instead of an in-place `writeFileSync` truncate — this also
  *     brings the implementation in line with the documented contract in
@@ -282,30 +343,31 @@ export async function archiveRejected({ rejected, repoRoot, reason }) {
  *
  * @param {object} opts
  * @param {string} opts.repoRoot - absolute project root path
- * @returns {Promise<{ cleared: boolean, summariesCleared: number }>}
+ * @returns {Promise<{ cleared: boolean, summariesCleared: number, reason?: string }>}
  */
 export async function clearProposalsJsonl({ repoRoot }) {
-  const proposalsResult = validatePathInsideProject(PROPOSALS_REL, repoRoot, { canonicalizeRoot: true });
+  const proposalsResult = validateSinkTarget(PROPOSALS_REL, repoRoot);
   if (!proposalsResult.ok) {
-    return { cleared: false, summariesCleared: 0 };
+    return { cleared: false, summariesCleared: 0, reason: `path-safety: ${proposalsResult.reason}` };
   }
   const proposalsPath = proposalsResult.realPath ?? proposalsResult.lexicalPath;
   const metricsDirPath = path.dirname(proposalsPath);
 
   // Step 0 (#797): archive pre-clear content before truncating. Best-effort
-  // — never lets an archive-side failure block the clear (same never-throw
-  // contract as the rest of this function).
+  // — ordinary archive I/O failures do not block clear; an unsafe required
+  // recovery target does, preserving the queue and its summaries.
   if (existsSync(proposalsPath)) {
     try {
       const preClearContent = readFileSync(proposalsPath, 'utf8');
       if (preClearContent.length > 0) {
-        const archiveResult = validatePathInsideProject(PROPOSALS_ARCHIVE_REL, repoRoot, { canonicalizeRoot: true });
-        if (archiveResult.ok) {
-          const archivePath = archiveResult.realPath ?? archiveResult.lexicalPath;
-          await mkdir(path.dirname(archivePath), { recursive: true });
-          const normalized = preClearContent.endsWith('\n') ? preClearContent : `${preClearContent}\n`;
-          await appendFile(archivePath, normalized, 'utf8');
+        const archiveResult = validateSinkTarget(PROPOSALS_ARCHIVE_REL, repoRoot);
+        if (!archiveResult.ok) {
+          return { cleared: false, summariesCleared: 0, reason: `path-safety: ${archiveResult.reason}` };
         }
+        const archivePath = archiveResult.realPath ?? archiveResult.lexicalPath;
+        await mkdir(path.dirname(archivePath), { recursive: true });
+        const normalized = preClearContent.endsWith('\n') ? preClearContent : `${preClearContent}\n`;
+        await appendFile(archivePath, normalized, 'utf8');
       }
     } catch {
       // Best-effort — a read/append failure on the archive sidecar must not
@@ -501,6 +563,6 @@ export async function promoteAndClear({ approved, sessionId, repoRoot, ...rest }
     expected,
     cleared: c.cleared,
     summariesCleared: c.summariesCleared,
-    skippedReason: null,
+    skippedReason: c.cleared ? null : (c.reason ?? 'clear-failed'),
   };
 }