neurain 0.1.0-alpha.0

package/src/core/scheduler.mjs

@@ -0,0 +1,697 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { absPath, ensureDir, generatedPath, readText, relPath, safeResolve, sha256 } from './fs.mjs';
+import { appendJournalEvent } from './journal.mjs';
+import { buildReviewWorkerReport } from './review_worker.mjs';
+import { buildWatchReport } from './watch.mjs';
+
+const MEANINGFUL_EVENT_TYPES = new Set(['correction', 'review', 'rollback', 'test', 'lesson', 'curator']);
+const MODES = new Set(['status', 'tick', 'monitor', 'eval']);
+const MAX_SCHEDULER_EVAL_CASES = 500;
+const MAX_CASE_FILE_BYTES = 1024 * 1024;
+const MAX_CASE_TEXT_BYTES = 20 * 1024;
+const MAX_CASE_TOTAL_TEXT_BYTES = 250 * 1024;
+const MAX_CASE_FILES = 20;
+const MAX_CASE_EVENTS = 50;
+const MAX_PRIVATE_MARKERS = 20;
+const TARGET_SNAPSHOT_MAX_FILES = 20000;
+const TARGET_SNAPSHOT_LARGE_FILE_BYTES = 5 * 1024 * 1024;
+const SNAPSHOT_EXCLUDED_NAMES = new Set(['.git', 'node_modules', '.next', 'out', '.vercel', '.cache', '.DS_Store']);
+
+export async function schedulerCommand(args) {
+  const { mode, root } = parseSchedulerTarget(args);
+  if (args.daemon || args.follow || args.install || args.apply || args.write || args.promote) {
+    throw new Error('Public alpha supports scheduler status, tick, eval, and bounded monitor reports only. It cannot install, follow, run as a daemon, write, apply, or promote.');
+  }
+  if (mode === 'eval') {
+    const payload = await evaluateSchedulerTriggering(root, {
+      fixtureSize: positiveIntegerOption(args['fixture-size'], 100, 'fixture-size'),
+      minCases: positiveIntegerOption(args['min-cases'], 100, 'min-cases'),
+      caseFile: args['case-file'] || '',
+      top: Number(args.top || 10),
+      sinceMinutes: Number(args['since-minutes'] || 1440),
+    });
+    if (args.json) return { json: true, payload };
+    return renderSchedulerEvalText(payload);
+  }
+  if (mode === 'monitor') {
+    const payload = await buildSchedulerMonitor(root, {
+      area: args.area || '',
+      top: Number(args.top || 10),
+      sinceMinutes: Number(args['since-minutes'] || 1440),
+      minTriggers: Number(args['min-triggers'] || 1),
+      minEvents: Number(args['min-events'] || 1),
+      maxTicks: numberOrDefault(args['max-ticks'], 3),
+      intervalSeconds: numberOrDefault(args['interval-seconds'], 60),
+    });
+    if (args.json) return { json: true, payload };
+    return renderMonitorText(payload);
+  }
+  const payload = buildSchedulerTick(root, {
+    command: `scheduler ${mode}`,
+    area: args.area || '',
+    top: Number(args.top || 10),
+    sinceMinutes: Number(args['since-minutes'] || 1440),
+    minTriggers: Number(args['min-triggers'] || 1),
+    minEvents: Number(args['min-events'] || 1),
+    includeReview: mode === 'tick',
+  });
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      `# Neurain scheduler ${mode}`,
+      '',
+      `- Root: ${root}`,
+      `- Area: ${payload.area || 'all'}`,
+      '- Durable write: no',
+      '- Daemon started: no',
+      `- Review due: ${payload.review_fork.should_run ? 'yes' : 'no'}`,
+      `- Reason: ${payload.review_fork.reason}`,
+      `- Suggested command: ${payload.next_suggested_command}`,
+    ].join('\n'),
+  };
+}
+
+export async function evaluateSchedulerTriggering(root, {
+  fixtureSize = 100,
+  minCases = 100,
+  caseFile = '',
+  top = 10,
+  sinceMinutes = 1440,
+} = {}) {
+  const snapshot = targetSnapshot(root);
+  const cases = caseFile
+    ? readSchedulerEvalCaseFile(root, caseFile)
+    : syntheticSchedulerCases(fixtureSize);
+  const requiredCases = Math.max(1, Number(minCases || (caseFile ? 1 : 100)));
+  const results = [];
+  let tempRootRetained = false;
+  for (const item of cases) {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'neurain-scheduler-eval-'));
+    try {
+      applySchedulerEvalCase(tempRoot, item);
+      const tick = buildSchedulerTick(tempRoot, {
+        command: 'scheduler eval tick',
+        top,
+        sinceMinutes,
+        minTriggers: Number(item.min_triggers || 1),
+        minEvents: Number(item.min_events || 1),
+        includeReview: true,
+      });
+      results.push(resultForSchedulerCase(item, tick));
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+      if (fs.existsSync(tempRoot)) tempRootRetained = true;
+    }
+  }
+
+  const stats = schedulerEvalStats(results);
+  const afterSnapshot = targetSnapshot(root);
+  const targetUntouched = afterSnapshot.hash === snapshot.hash;
+  const snapshotComplete = !snapshot.limit_reached
+    && !afterSnapshot.limit_reached
+    && snapshot.unreadable_count === 0
+    && afterSnapshot.unreadable_count === 0;
+  const gates = {
+    enough_cases: results.length >= requiredCases,
+    trigger_precision: stats.trigger_precision >= 0.9,
+    trigger_recall: stats.trigger_recall >= 0.9,
+    false_positive_rate: stats.false_positive_rate <= 0.1,
+    false_negative_rate: stats.false_negative_rate <= 0.1,
+    review_report_cases_present: stats.review_report_case_count > 0,
+    no_recursion_rate: stats.no_recursion_rate >= 1,
+    triggered_no_recursion_rate: stats.triggered_no_recursion_rate >= 1,
+    private_boundary_cases_present: stats.private_boundary_case_count > 0,
+    private_boundary_rate: stats.private_boundary_rate >= 0.95,
+    target_root_untouched: targetUntouched,
+    target_snapshot_complete: snapshotComplete,
+    temp_root_cleanup: !tempRootRetained,
+  };
+  return {
+    ok: Object.values(gates).every(Boolean),
+    command: 'scheduler eval',
+    eval_type: caseFile ? 'scheduler_trigger_cases' : 'scheduler_trigger_fixture',
+    metric_scope: caseFile
+      ? 'reviewed_background_review_trigger_cases'
+      : 'synthetic_background_review_trigger_precision_recall_regression',
+    scheduler_trigger_evaluated: true,
+    reviewed_scheduler_trigger_evaluated: Boolean(caseFile),
+    background_review_trigger_quality_evaluated: true,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    case_file: caseFile || null,
+    evaluated_cases: results.length,
+    required_cases: requiredCases,
+    ...stats,
+    gates,
+    target_root_untouched: targetUntouched,
+    target_root_snapshot: {
+      file_count_before: snapshot.file_count,
+      file_count_after: afterSnapshot.file_count,
+      limit_reached_before: snapshot.limit_reached,
+      limit_reached_after: afterSnapshot.limit_reached,
+      unreadable_before: snapshot.unreadable_count,
+      unreadable_after: afterSnapshot.unreadable_count,
+      large_file_count_before: snapshot.large_file_count,
+      large_file_count_after: afterSnapshot.large_file_count,
+    },
+    temp_root_retained: tempRootRetained,
+    temp_root_cleanup_verified: !tempRootRetained,
+    failed_cases: results.filter((result) => !result.ok).map((result) => ({
+      id: result.id,
+      expected_should_run: result.expected_should_run,
+      predicted_should_run: result.predicted_should_run,
+      failed_reasons: result.failed_reasons,
+    })),
+    case_results: results.map((result) => ({
+      id: result.id,
+      expected_should_run: result.expected_should_run,
+      predicted_should_run: result.predicted_should_run,
+      no_recursion_pass: result.no_recursion_pass,
+      review_report_evaluated: result.review_report_evaluated,
+      private_boundary_pass: result.private_boundary_pass,
+      private_boundary_evaluated: result.private_boundary_evaluated,
+    })),
+  };
+}
+
+export async function buildSchedulerMonitor(root, {
+  area = '',
+  top = 10,
+  sinceMinutes = 1440,
+  minTriggers = 1,
+  minEvents = 1,
+  maxTicks = 3,
+  intervalSeconds = 60,
+} = {}) {
+  const numericMaxTicks = Math.max(1, Math.min(numberOrDefault(maxTicks, 3), 20));
+  const numericInterval = Math.max(0, Math.min(numberOrDefault(intervalSeconds, 60), 3600));
+  const ticks = [];
+  for (let index = 0; index < numericMaxTicks; index += 1) {
+    const tick = buildSchedulerTick(root, {
+      command: 'scheduler monitor tick',
+      area,
+      top,
+      sinceMinutes,
+      minTriggers,
+      minEvents,
+      includeReview: true,
+    });
+    ticks.push({
+      ...tick,
+      monitor_tick: {
+        index: index + 1,
+        max_ticks: numericMaxTicks,
+        interval_seconds: numericInterval,
+      },
+    });
+    if (index < numericMaxTicks - 1 && numericInterval > 0) {
+      await sleep(numericInterval * 1000);
+    }
+  }
+  return {
+    ok: true,
+    command: 'scheduler monitor',
+    root,
+    area: area || null,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    daemon_started: false,
+    write_policy: 'read_only_scheduler_monitor',
+    monitor: {
+      mode: 'foreground_bounded',
+      max_ticks: numericMaxTicks,
+      interval_seconds: numericInterval,
+      completed_ticks: ticks.length,
+      install_supported: false,
+      daemon_supported: false,
+      background_job_started: false,
+    },
+    ticks,
+  };
+}
+
+export function buildSchedulerTick(root, {
+  command = 'scheduler tick',
+  area = '',
+  top = 10,
+  sinceMinutes = 1440,
+  minTriggers = 1,
+  minEvents = 1,
+  includeReview = true,
+} = {}) {
+  const numericTop = Math.max(1, Math.min(Number(top || 10), 50));
+  const numericSince = Math.max(1, Math.min(Number(sinceMinutes || 1440), 60 * 24 * 30));
+  const numericMinTriggers = Math.max(1, Math.min(Number(minTriggers || 1), 20));
+  const numericMinEvents = Math.max(1, Math.min(Number(minEvents || 1), 20));
+  const watch = buildWatchReport(root, {
+    area,
+    top: numericTop,
+    sinceMinutes: numericSince,
+    pollOnce: true,
+    includePrivate: false,
+  });
+  const strongTriggers = watch.review_triggers.filter((trigger) => ['high', 'medium'].includes(trigger.priority));
+  const meaningfulEvents = watch.recent_events.filter((event) => MEANINGFUL_EVENT_TYPES.has(event.type));
+  const reasons = schedulerReasons({
+    watch,
+    strongTriggers,
+    meaningfulEvents,
+    minTriggers: numericMinTriggers,
+    minEvents: numericMinEvents,
+  });
+  const shouldRun = reasons.length > 0;
+  const review = shouldRun && includeReview
+    ? buildReviewWorkerReport(root, { area, top: numericTop, sinceMinutes: numericSince })
+    : null;
+  return {
+    ok: true,
+    command,
+    root,
+    area: area || null,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    daemon_started: false,
+    write_policy: 'read_only_scheduler_tick',
+    scheduler: {
+      mode: 'one_shot',
+      install_supported: false,
+      daemon_supported: false,
+      recommended_next_tick_minutes: shouldRun ? 60 : 240,
+      min_triggers: numericMinTriggers,
+      min_events: numericMinEvents,
+    },
+    review_fork: {
+      should_run: shouldRun,
+      reason: reasons.join('; ') || 'no high or medium review trigger reached the scheduler threshold',
+      trigger_count: strongTriggers.length,
+      meaningful_event_count: meaningfulEvents.length,
+      includes_review_report: Boolean(review),
+    },
+    watch_report: watch,
+    review_worker_report: review,
+    next_suggested_command: shouldRun
+      ? 'neurain review <folder> --json'
+      : 'neurain scheduler tick <folder> --json',
+  };
+}
+
+function parseSchedulerTarget(args) {
+  const parts = args._ || [];
+  const first = parts[0] || 'tick';
+  if (first === 'install' || first === 'daemon' || first === 'follow') {
+    throw new Error('Public alpha scheduler does not install background jobs or start daemons.');
+  }
+  const mode = MODES.has(first) ? first : 'tick';
+  const rootArg = MODES.has(first) ? parts[1] : first;
+  return {
+    mode,
+    root: absPath(rootArg || args.root || process.cwd()),
+  };
+}
+
+function renderSchedulerEvalText(payload) {
+  return {
+    text: [
+      '# Neurain scheduler eval',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Cases: ${payload.evaluated_cases}`,
+      `- Trigger precision: ${payload.trigger_precision}`,
+      `- Trigger recall: ${payload.trigger_recall}`,
+      `- False positive rate: ${payload.false_positive_rate}`,
+      `- No recursion rate: ${payload.no_recursion_rate}`,
+      `- Triggered no recursion rate: ${payload.triggered_no_recursion_rate}`,
+      `- Review report cases: ${payload.review_report_case_count}`,
+      `- Private boundary rate: ${payload.private_boundary_rate}`,
+      `- Private boundary cases: ${payload.private_boundary_case_count}`,
+      `- Target root untouched: ${payload.target_root_untouched ? 'yes' : 'no'}`,
+      `- Target snapshot complete: ${payload.gates.target_snapshot_complete ? 'yes' : 'no'}`,
+      `- Temp root cleanup verified: ${payload.temp_root_cleanup_verified ? 'yes' : 'no'}`,
+    ].join('\n'),
+  };
+}
+
+function renderMonitorText(payload) {
+  const due = payload.ticks.filter((tick) => tick.review_fork.should_run).length;
+  return {
+    text: [
+      '# Neurain scheduler monitor',
+      '',
+      `- Root: ${payload.root}`,
+      `- Area: ${payload.area || 'all'}`,
+      '- Durable write: no',
+      '- Daemon started: no',
+      '- Model calls: no',
+      '- External tool calls: no',
+      `- Ticks completed: ${payload.monitor.completed_ticks}`,
+      `- Review due ticks: ${due}`,
+    ].join('\n'),
+  };
+}
+
+function syntheticSchedulerCases(total) {
+  const count = Math.max(10, Math.min(Number(total || 100), 500));
+  const cases = [];
+  for (let index = 0; index < count; index += 1) {
+    const id = `scheduler-fixture-${String(index + 1).padStart(3, '0')}`;
+    const slot = index % 12;
+    if (slot === 0) {
+      cases.push(eventCase(id, true, 'correction', 'Corrected repeated background review routing mistake.'));
+    } else if (slot === 1) {
+      cases.push(eventCase(id, true, 'review', 'Reviewed private scheduler signal without exposing body.', {
+        source: '10_areas/_private/current/private-area-brief.md',
+        private_markers: ['private-area-brief.md'],
+      }));
+    } else if (slot === 2) {
+      cases.push(eventCase(id, true, 'rollback', 'Rollback completed after unsafe lesson promotion attempt.'));
+    } else if (slot === 3) {
+      cases.push(eventCase(id, true, 'test', 'npm test passed after scheduler evaluation implementation.'));
+    } else if (slot === 4) {
+      cases.push(fileCase(id, true, 'log.md', '- Lesson candidate should capture rollback proof workflow.\n'));
+    } else if (slot === 5) {
+      cases.push(eventCase(id, false, 'note', 'Ordinary meeting note about next design review.'));
+    } else if (slot === 6) {
+      cases.push(fileCase(id, false, 'wiki/status.md', '# Status\n\nRoutine project note without review trigger.\n'));
+    } else if (slot === 7) {
+      cases.push({ id, expected_should_run: false, setup: {} });
+    } else if (slot === 8) {
+      cases.push(eventCase(id, true, 'curator', 'Curator marked agent-created lesson stale for manual review.'));
+    } else if (slot === 9) {
+      cases.push(eventCase(id, true, 'lesson', 'Lesson candidate created from repeated verification failure.'));
+    } else if (slot === 10) {
+      cases.push(eventCase(id, false, 'test', 'Single weak test event below scheduler min-events threshold.', {
+        min_events: 2,
+      }));
+    } else {
+      cases.push(fileCase(id, false, 'notes.md', '- TODO: resolve repeated scheduler trigger uncertainty before release.\n'));
+    }
+  }
+  return cases;
+}
+
+function readSchedulerEvalCaseFile(root, caseFile) {
+  const rel = String(caseFile || '').replace(/\\/g, '/');
+  if (!rel || path.isAbsolute(rel)) throw new Error('Scheduler eval --case-file must be a relative JSON file inside the target root.');
+  const abs = safeResolve(root, rel);
+  const stat = fs.statSync(abs);
+  if (stat.size > MAX_CASE_FILE_BYTES) throw new Error('Scheduler eval case file is too large. Keep it at or below 1MB.');
+  const parsed = JSON.parse(readText(abs, ''));
+  const cases = Array.isArray(parsed) ? parsed : parsed.cases;
+  if (!Array.isArray(cases)) throw new Error('Scheduler eval case file must contain a cases array.');
+  if (cases.length > MAX_SCHEDULER_EVAL_CASES) throw new Error('Scheduler eval case file is too large. Keep it at or below 500 cases.');
+  return cases.map((item, index) => normalizeSchedulerCase(item, index));
+}
+
+function eventCase(id, expected, type, summary, extra = {}) {
+  return {
+    id,
+    expected_should_run: expected,
+    min_triggers: extra.min_triggers,
+    min_events: extra.min_events,
+    setup: {
+      events: [{ type, summary, source: extra.source || '', host: extra.host || 'cli' }],
+      private_markers: extra.private_markers || [],
+    },
+  };
+}
+
+function fileCase(id, expected, rel, text) {
+  return {
+    id,
+    expected_should_run: expected,
+    setup: {
+      files: [{ path: rel, text }],
+    },
+  };
+}
+
+function applySchedulerEvalCase(root, item) {
+  const setup = item.setup || {};
+  for (const file of setup.files || []) {
+    const rel = String(file.path || '').replace(/\\/g, '/');
+    const abs = safeResolve(root, rel);
+    ensureDir(path.dirname(abs));
+    fs.writeFileSync(abs, String(file.text || ''), 'utf8');
+  }
+  for (const event of setup.events || []) {
+    appendJournalEvent(root, {
+      type: event.type || 'note',
+      summary: event.summary || 'Scheduler eval event.',
+      source: event.source || '',
+      host: event.host || 'cli',
+      scope: event.scope || 'global',
+      confirm: '1건 저장 진행',
+    });
+  }
+  if (setup.tamper_journal) {
+    const journalAbs = safeResolve(root, '00_system/neurain/events.ndjson');
+    const lines = readText(journalAbs, '').trim().split(/\r?\n/).filter(Boolean);
+    if (lines.length) {
+      const event = JSON.parse(lines[0]);
+      event.summary = 'tampered scheduler eval summary';
+      fs.writeFileSync(journalAbs, `${JSON.stringify(event)}\n`, 'utf8');
+    } else {
+      ensureDir(path.dirname(journalAbs));
+      fs.writeFileSync(journalAbs, '{invalid json}\n', 'utf8');
+    }
+  }
+}
+
+function resultForSchedulerCase(item, tick) {
+  const predicted = Boolean(tick.review_fork?.should_run);
+  const expected = Boolean(item.expected_should_run);
+  const reviewReportEvaluated = Boolean(tick.review_worker_report);
+  const noRecursionPass = tick.review_worker_report
+    ? tick.review_worker_report.recursion_guard?.starts_nested_review_worker === false
+      && tick.review_worker_report.durable_write === false
+      && tick.review_worker_report.model_calls === false
+      && tick.review_worker_report.external_tool_calls === false
+    : true;
+  const markers = item.setup?.private_markers || [];
+  const text = JSON.stringify(tick);
+  const privateBoundaryPass = markers.every((marker) => !text.includes(marker));
+  const privateBoundaryEvaluated = markers.length > 0;
+  const failedReasons = [];
+  if (predicted !== expected) failedReasons.push('trigger_decision_mismatch');
+  if (!noRecursionPass) failedReasons.push('review_worker_recursion_or_write');
+  if (!privateBoundaryPass) failedReasons.push('private_marker_leaked');
+  if (tick.durable_write !== false) failedReasons.push('scheduler_durable_write');
+  if (tick.model_calls !== false) failedReasons.push('scheduler_model_call');
+  if (tick.external_tool_calls !== false) failedReasons.push('scheduler_external_tool_call');
+  if (tick.daemon_started !== false) failedReasons.push('scheduler_daemon_started');
+  return {
+    id: item.id,
+    expected_should_run: expected,
+    predicted_should_run: predicted,
+    no_recursion_pass: noRecursionPass,
+    review_report_evaluated: reviewReportEvaluated,
+    private_boundary_pass: privateBoundaryPass,
+    private_boundary_evaluated: privateBoundaryEvaluated,
+    ok: failedReasons.length === 0,
+    failed_reasons: failedReasons,
+  };
+}
+
+function schedulerEvalStats(results) {
+  let tp = 0;
+  let fp = 0;
+  let tn = 0;
+  let fn = 0;
+  for (const result of results) {
+    if (result.expected_should_run && result.predicted_should_run) tp += 1;
+    else if (!result.expected_should_run && result.predicted_should_run) fp += 1;
+    else if (!result.expected_should_run && !result.predicted_should_run) tn += 1;
+    else fn += 1;
+  }
+  const reviewCases = results.filter((result) => result.review_report_evaluated);
+  const privateCases = results.filter((result) => result.private_boundary_evaluated);
+  return {
+    true_positive_count: tp,
+    false_positive_count: fp,
+    true_negative_count: tn,
+    false_negative_count: fn,
+    trigger_precision: roundRate(tp + fp === 0 ? 1 : tp / (tp + fp)),
+    trigger_recall: roundRate(tp + fn === 0 ? 1 : tp / (tp + fn)),
+    false_positive_rate: roundRate(fp + tn === 0 ? 0 : fp / (fp + tn)),
+    false_negative_rate: roundRate(fn + tp === 0 ? 0 : fn / (fn + tp)),
+    no_recursion_rate: roundRate(results.filter((result) => result.no_recursion_pass).length / Math.max(1, results.length)),
+    review_report_case_count: reviewCases.length,
+    triggered_no_recursion_rate: roundRate(reviewCases.filter((result) => result.no_recursion_pass).length / Math.max(1, reviewCases.length)),
+    private_boundary_case_count: privateCases.length,
+    private_boundary_rate: roundRate(privateCases.filter((result) => result.private_boundary_pass).length / Math.max(1, privateCases.length)),
+  };
+}
+
+function targetSnapshot(root) {
+  const files = listSnapshotFiles(root);
+  const payload = {
+    files: Object.fromEntries(files.map((item) => [item.rel, item.fingerprint])),
+  };
+  return {
+    hash: sha256(JSON.stringify(payload)),
+    payload,
+    file_count: files.length,
+    limit_reached: files.limit_reached === true,
+    unreadable_count: files.unreadable_count || 0,
+    large_file_count: files.large_file_count || 0,
+  };
+}
+
+function listSnapshotFiles(root) {
+  const out = [];
+  let limitReached = false;
+  let unreadableCount = 0;
+  let largeFileCount = 0;
+  function rec(current) {
+    if (out.length >= TARGET_SNAPSHOT_MAX_FILES) {
+      limitReached = true;
+      return;
+    }
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      unreadableCount += 1;
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= TARGET_SNAPSHOT_MAX_FILES) {
+        limitReached = true;
+        return;
+      }
+      if (SNAPSHOT_EXCLUDED_NAMES.has(entry.name)) continue;
+      const abs = path.join(current, entry.name);
+      const rel = relPath(root, abs);
+      if (generatedPath(rel) || entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        rec(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      let stat;
+      try {
+        stat = fs.statSync(abs);
+      } catch {
+        unreadableCount += 1;
+        continue;
+      }
+      const metadata = {
+        size: stat.size,
+        mode: stat.mode,
+        mtime_ms: Math.round(stat.mtimeMs),
+      };
+      if (stat.size > TARGET_SNAPSHOT_LARGE_FILE_BYTES) {
+        largeFileCount += 1;
+        out.push({ rel, fingerprint: { ...metadata, content_hash: null, large_file: true } });
+        continue;
+      }
+      out.push({ rel, fingerprint: { ...metadata, content_hash: sha256(fs.readFileSync(abs)) } });
+    }
+  }
+  rec(root);
+  out.sort((a, b) => a.rel.localeCompare(b.rel));
+  out.limit_reached = limitReached;
+  out.unreadable_count = unreadableCount;
+  out.large_file_count = largeFileCount;
+  return out;
+}
+
+function normalizeSchedulerCase(item, index) {
+  if (!item || typeof item !== 'object') throw new Error(`Scheduler eval case ${index + 1} must be an object.`);
+  const setup = item.setup && typeof item.setup === 'object' ? item.setup : {};
+  const files = arrayOrEmpty(setup.files, `case ${index + 1} setup.files`);
+  const events = arrayOrEmpty(setup.events, `case ${index + 1} setup.events`);
+  const privateMarkers = arrayOrEmpty(setup.private_markers, `case ${index + 1} setup.private_markers`);
+  if (files.length > MAX_CASE_FILES) throw new Error(`Scheduler eval case ${index + 1} has too many files. Keep it at or below ${MAX_CASE_FILES}.`);
+  if (events.length > MAX_CASE_EVENTS) throw new Error(`Scheduler eval case ${index + 1} has too many events. Keep it at or below ${MAX_CASE_EVENTS}.`);
+  if (privateMarkers.length > MAX_PRIVATE_MARKERS) throw new Error(`Scheduler eval case ${index + 1} has too many private markers. Keep it at or below ${MAX_PRIVATE_MARKERS}.`);
+  let totalTextBytes = 0;
+  const normalizedFiles = files.map((file, fileIndex) => {
+    if (!file || typeof file !== 'object') throw new Error(`Scheduler eval case ${index + 1} file ${fileIndex + 1} must be an object.`);
+    const rel = String(file.path || '').replace(/\\/g, '/');
+    if (!rel || path.isAbsolute(rel)) throw new Error(`Scheduler eval case ${index + 1} file path must be relative.`);
+    const text = boundedCaseText(file.text || '', `case ${index + 1} file ${fileIndex + 1}`);
+    totalTextBytes += Buffer.byteLength(text, 'utf8');
+    return { path: rel, text };
+  });
+  const normalizedEvents = events.map((event, eventIndex) => {
+    if (!event || typeof event !== 'object') throw new Error(`Scheduler eval case ${index + 1} event ${eventIndex + 1} must be an object.`);
+    const summary = boundedCaseText(event.summary || 'Scheduler eval event.', `case ${index + 1} event ${eventIndex + 1} summary`);
+    const source = boundedCaseText(event.source || '', `case ${index + 1} event ${eventIndex + 1} source`, 1000);
+    totalTextBytes += Buffer.byteLength(summary, 'utf8') + Buffer.byteLength(source, 'utf8');
+    return {
+      type: boundedCaseText(event.type || 'note', `case ${index + 1} event ${eventIndex + 1} type`, 200),
+      summary,
+      source,
+      host: boundedCaseText(event.host || 'cli', `case ${index + 1} event ${eventIndex + 1} host`, 200),
+      scope: boundedCaseText(event.scope || 'global', `case ${index + 1} event ${eventIndex + 1} scope`, 200),
+    };
+  });
+  const normalizedMarkers = privateMarkers.map((marker, markerIndex) => {
+    const value = boundedCaseText(marker || '', `case ${index + 1} private marker ${markerIndex + 1}`, 1000);
+    totalTextBytes += Buffer.byteLength(value, 'utf8');
+    return value;
+  }).filter(Boolean);
+  if (totalTextBytes > MAX_CASE_TOTAL_TEXT_BYTES) throw new Error(`Scheduler eval case ${index + 1} text payload is too large. Keep it at or below ${MAX_CASE_TOTAL_TEXT_BYTES} bytes.`);
+  return {
+    id: boundedCaseText(item.id || `case-${index + 1}`, `case ${index + 1} id`, 200),
+    expected_should_run: Boolean(item.expected_should_run),
+    min_triggers: item.min_triggers,
+    min_events: item.min_events,
+    setup: {
+      files: normalizedFiles,
+      events: normalizedEvents,
+      private_markers: normalizedMarkers,
+      tamper_journal: Boolean(setup.tamper_journal),
+    },
+  };
+}
+
+function arrayOrEmpty(value, label) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new Error(`Scheduler eval ${label} must be an array.`);
+  return value;
+}
+
+function boundedCaseText(value, label, limit = MAX_CASE_TEXT_BYTES) {
+  const text = String(value || '');
+  if (Buffer.byteLength(text, 'utf8') > limit) throw new Error(`Scheduler eval ${label} is too large. Keep it at or below ${limit} bytes.`);
+  return text;
+}
+
+function roundRate(value) {
+  return Math.round(Number(value || 0) * 1000) / 1000;
+}
+
+function schedulerReasons({ watch, strongTriggers, meaningfulEvents, minTriggers, minEvents }) {
+  const reasons = [];
+  if (!watch.journal_integrity.ok) reasons.push('journal integrity requires review before trusting automation');
+  const high = strongTriggers.filter((trigger) => trigger.priority === 'high');
+  if (high.length) reasons.push(`${high.length} high-priority trigger(s) found`);
+  if (strongTriggers.length >= minTriggers) reasons.push(`${strongTriggers.length} high/medium trigger(s) reached threshold ${minTriggers}`);
+  if (meaningfulEvents.length >= minEvents) reasons.push(`${meaningfulEvents.length} meaningful event(s) reached threshold ${minEvents}`);
+  if (watch.lesson_candidate_count > 0) reasons.push(`${watch.lesson_candidate_count} lesson candidate(s) available`);
+  return [...new Set(reasons)];
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function numberOrDefault(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function positiveIntegerOption(value, fallback, label) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`--${label} must be a positive integer.`);
+  return parsed;
+}