atris 3.82.4 → 3.82.7

package/bin/atris.js

@@ -634,6 +634,9 @@ function showHelpAll() {
   console.log('  slop       - Deterministic slop detector: frontend/prose tells, dead code (slop dead --exports)');
   console.log('  sentinel   - Security audit: engines hunt for holes, a different model verifies each one');
   console.log('               free checks: sentinel agents, sentinel watch, sentinel guard install');
+  console.log('               exam and self-improvement: sentinel bench, sentinel improve');
+  console.log('               fix a confirmed finding on its own branch: sentinel fix <id>');
+  console.log('               re-check old findings against today\'s code: sentinel recheck');
   console.log('  voice      - Scan binary voice tells or judge reply shape and plainness');
   console.log('  recover    - Explain stopped missions; --apply performs safe recovery only');
   console.log('  task       - Local agent task plane (atomic claims, TODO import)');

package/commands/security-review.js

@@ -457,13 +457,15 @@ function renderAuditLanding({ dir, meta, records }) {
     if (hunters < 1) L.push('  this budget is too small to send a hunter; try --budget 8 or more');
     else L.push(needed <= hunters ? '  one run can read every area' : `  about ${Math.ceil(needed / hunters)} runs to read every area`);
   } else {
-    L.push(`  ${confirmed.length} confirmed${sevText ? ` (${sevText})` : ''} · ${needs.length} need a fact from you · ${rejected.length} disproved`);
+    const waiting = require('../lib/security-audit').waitingOf(meta);
+    L.push(`  ${confirmed.length + waiting.length} confirmed${sevText ? ` (${sevText})` : ''} · ${needs.length} need a fact from you · ${rejected.length} disproved`);
     L.push(`  read ${cov.fresh} areas this run, ${cov.carried} carried unchanged, ${cov.deferred || 0} left for the next run`);
     L.push(`  found by ${meta.engines.hunter}, checked by ${meta.engines.verifier}${meta.engines.hunter === meta.engines.verifier ? ' (same engine)' : ''} · ${meta.invocations.used} engine calls of ${meta.budget}${meta.credits_used ? ` · ${meta.credits_used} credits used` : ''}`);
     for (const r of confirmed.slice(0, 6)) {
       const sink = r.trace[r.trace.length - 1];
       L.push(`    ${r.severity.overall.padEnd(8)} ${r.title} (${sink.file}:${sink.line})`);
     }
+    for (const w of waiting.slice(0, 6)) L.push(`    ${w.severity.padEnd(8)} ${w.title} (last seen at ${w.location}, still open: ${w.why})`);
     if (meta.run_status === 'incomplete') L.push(`  incomplete: ${String(meta.incomplete_reason).replace(/_/g, ' ')}`);
   }
   L.push(`  report: ${tildePath(path.join(dir, 'REPORT.md'))}`, '');
@@ -478,11 +480,28 @@ function askYesNo(question, { input = process.stdin, output = process.stdout } =
   });
 }
 
-async function uploadAfterRun(dir, { token, quiet, cloud }) {
+async function uploadAfterRun(dir, { token, quiet, cloud, root = null, env = process.env }) {
   const res = await cloud.uploadRun(dir, { token });
   const say = quiet ? (m) => console.error(m) : (m) => console.log(m);
   if (res.ok) say('  saved the summary to your atris account (no source code was sent)');
   else say(`  warning: could not save the summary to your atris account: ${res.reason}. the review itself is done`);
+  if (res.ok && res.body) await sendFixedEvents(dir, res.body, { token, root, env, say });
+  return res;
+}
+
+// Fixed findings also go to the events feed. The overview counts them as
+// fixed today. A failure here never undoes the saved review.
+async function sendFixedEvents(dir, body, { token, root, env, say }) {
+  if (!body.findings.some((f) => f.status === 'fixed')) return null;
+  let meta = null;
+  try { meta = JSON.parse(fs.readFileSync(path.join(dir, 'run-metadata.json'), 'utf8')); } catch {}
+  const target = root || (meta && meta.target) || process.cwd();
+  let res;
+  try {
+    res = await require('../lib/sentinel-events').reportReviewFixes(target, body, { token, env, foundAt: meta && meta.prior_finished_at });
+  } catch (e) { res = { ok: false, reason: e.message }; }
+  if (res.ok && res.fixed) say(`  marked ${res.fixed} finding${res.fixed === 1 ? '' : 's'} fixed on your dashboard`);
+  else if (!res.ok) say(`  warning: could not mark the fixed findings on your dashboard: ${res.reason}. run atris sentinel upload to try again`);
   return res;
 }
 
@@ -502,6 +521,7 @@ async function auditUploadCommand(argv, deps) {
   const res = await cloud.uploadRun(dir, { token });
   if (!res.ok) { console.error(`  could not save ${path.basename(dir)}: ${res.reason}`); return 1; }
   console.log(`  saved ${path.basename(dir)} to your atris account (no source code was sent)`);
+  if (res.body) await sendFixedEvents(dir, res.body, { token, root: null, env: deps.env || process.env, say: (m) => console.log(m) });
   return 0;
 }
 
@@ -598,6 +618,119 @@ async function auditScheduleCommand(argv, deps) {
   return 0;
 }
 
+// The quote-and-confirm step every run on atris models goes through: price
+// the estimate and set the cap. Then a yes, --yes or a scheduled approval.
+function spendConfirmer({ cloud, token, spend, capOverride, opts, deps, tell }) {
+  return async (estimate) => {
+    const quote = await cloud.quoteEstimate(estimate, { token });
+    spend.max = capOverride || quote.credits;
+    spend.limits = quote.limits;
+    tell(`\n  ${cloud.describeQuote(quote)}\n`);
+    if (capOverride) tell(`  this scheduled run may spend at most ${capOverride} credits, as approved`);
+    if (opts.yes) return true;
+    const input = deps.input || process.stdin;
+    if (!input.isTTY && !deps.input) { console.error('  nothing was spent. add --yes to run without this question'); return false; }
+    const yes = await (deps.ask || askYesNo)('  spend these credits? (y/N) ', { input, output: opts.json ? process.stderr : process.stdout });
+    if (!yes) tell('  nothing was spent');
+    return yes;
+  };
+}
+
+function parseRecheckArgs(argv) {
+  const opts = { json: false, verifier: null, engine: null, yes: false, upload: true, timeoutMs: null, budget: null, target: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, null];
+    const value = () => {
+      if (inline !== null) return inline;
+      if (!argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error(`${flag} needs a value`);
+      return argv[++i];
+    };
+    if (flag === '--json') opts.json = true;
+    else if (flag === '--verifier') opts.verifier = value();
+    else if (flag === '--engine') opts.engine = value();
+    else if (flag === '--yes' || flag === '-y') opts.yes = true;
+    else if (flag === '--no-upload') opts.upload = false;
+    else if (flag === '--timeout') opts.timeoutMs = Number(value()) * 1000;
+    else if (flag === '--budget') opts.budget = Number(value());
+    else if (arg.startsWith('-')) throw new Error(`unknown flag: ${arg}`);
+    else if (opts.target) throw new Error('give one folder to re-check');
+    else opts.target = arg;
+  }
+  if (opts.engine !== null && !['atris', 'local'].includes(opts.engine)) throw new Error('--engine must be atris or local');
+  if (opts.budget !== null && (!Number.isInteger(opts.budget) || opts.budget < 1 || opts.budget > 500)) throw new Error('--budget must be a whole number from 1 to 500');
+  if (opts.timeoutMs !== null && (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs < 10000)) throw new Error('--timeout is in seconds, at least 10');
+  return opts;
+}
+
+const OUTCOME_WORDS = { fixed: 'fixed', open: 'still open', moved: 'still open, moved', unsure: 'unsure, kept open', held: 'kept open' };
+
+function renderRecheckLanding(result) {
+  const { meta, records, dir } = result;
+  const a = meta.audit;
+  const byFp = new Map(records.map((r) => [r.fingerprint, r]));
+  const L = ['', `  ◉ sentinel re-check · ${meta.repo}`, ''];
+  L.push(`  re-checked ${a.checked} open finding${a.checked === 1 ? '' : 's'} from ${path.basename(meta.prior_run)}`);
+  L.push(`  ${a.fixed} fixed · ${a.open} still open · ${a.unchanged} unchanged with no call`);
+  for (const n of a.notes) {
+    const r = byFp.get(n.fingerprint);
+    const held = (a.held || []).find((h) => h.fingerprint === n.fingerprint);
+    const title = r ? r.title : held ? held.title : n.fingerprint;
+    const sev = r && r.severity ? r.severity.overall : held ? held.severity : '';
+    L.push(`    ${(OUTCOME_WORDS[n.outcome] || n.outcome).padEnd(18)} ${sev ? `${sev} ` : ''}${title}`);
+    L.push(`    ${''.padEnd(18)} ${n.why}`);
+  }
+  L.push(`  checked by ${meta.engines.verifier} · ${meta.invocations.used} engine call${meta.invocations.used === 1 ? '' : 's'}${meta.credits_used ? ` · ${meta.credits_used} credits used` : ''}`);
+  if (meta.run_status === 'incomplete') L.push('  some findings got no answer. they stay open and wait for the next run');
+  L.push(`  report: ${tildePath(path.join(dir, 'REPORT.md'))}`, '');
+  return L.join('\n');
+}
+
+// atris sentinel recheck [path]: only the auditor, on the last review's open
+// findings. Same engine rules, same price question and cap on atris models,
+// same plain-sentence upload.
+async function auditRecheckCommand(argv, deps = {}) {
+  const audit = require('../lib/security-audit');
+  const cloud = deps.cloud || require('../lib/sentinel-cloud');
+  let opts;
+  try { opts = parseRecheckArgs(argv); } catch (e) { console.error(`sentinel recheck: ${e.message}`); return 2; }
+  const root = path.resolve(opts.target || deps.root || process.cwd());
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) { console.error(`sentinel recheck: ${root} is not a folder`); return 2; }
+  const token = deps.token !== undefined ? deps.token : cloud.authToken();
+  let engines;
+  try { engines = cloud.resolveEngines({ engine: opts.engine, verifier: opts.verifier, token, env: deps.env || process.env }); } catch (e) { console.error(`sentinel recheck: ${e.message}`); return 2; }
+  const verifier = engines.verifier || undefined;
+  const hosted = audit.isHostedEngine(verifier);
+  if (hosted && !token) { console.error('sentinel recheck: re-checks on atris models need a login; run atris login first'); return 2; }
+  const tell = opts.json ? (m) => console.error(m) : (m) => console.log(m);
+  if (hosted && engines.chosen === 'no_local_engine') tell('  no codex or claude found on this machine. this re-check runs on atris models');
+  const spend = hosted ? cloud.spendGuard({ quoteCall: deps.quoteCall }) : null;
+  let runJobs = deps.runJobs;
+  if (!runJobs && hosted) runJobs = cloud.atrisJobRunner({ token, spend });
+  const confirmSpend = hosted ? spendConfirmer({ cloud, token, spend, capOverride: null, opts, deps, tell }) : null;
+  let result;
+  try {
+    result = await audit.runRecheck({ root, verifier, runJobs, confirmSpend, budget: opts.budget ?? undefined, timeoutMs: opts.timeoutMs || undefined, log: opts.json ? () => {} : (m) => console.log(`  · ${m}`) });
+  } catch (e) {
+    console.error(`sentinel recheck: ${e.message}`);
+    return 2;
+  }
+  if (result.nothing) {
+    if (opts.json) console.log(JSON.stringify({ ok: true, nothing: result.nothing }, null, 2));
+    else console.log(`\n  ${result.nothing}. nothing to do\n`);
+    return 0;
+  }
+  if (result.declined) return 1;
+  const fail = audit.shouldFailRun(result.dir, result.records);
+  if (opts.json) console.log(JSON.stringify({ ok: !fail, dir: result.dir, meta: result.meta, findings: result.records }, null, 2));
+  else console.log(renderRecheckLanding(result));
+  if (spend && spend.blocked) tell(`  stopped at the approved limit of ${spend.max} credits. ${spend.blocked} model call${spend.blocked === 1 ? '' : 's'} did not run. those findings stay open`);
+  if (opts.upload && token) {
+    try { await uploadAfterRun(result.dir, { token, quiet: opts.json, cloud, root, env: deps.env || process.env }); } catch (e) { tell(`  warning: could not save the summary to your atris account: ${e.message}. the re-check itself is done`); }
+  }
+  return fail ? 1 : 0;
+}
+
 async function auditCommand(argv, deps = {}) {
   if (argv[0] === 'help' || argv.includes('-h') || argv.includes('--help')) return printAuditHelp();
   const audit = require('../lib/security-audit');
@@ -614,7 +747,13 @@ async function auditCommand(argv, deps = {}) {
     const run = { agents: powers.agentsCommand, guard: powers.guardCommand, watch: powers.watchCommand, flush: powers.flushCommand }[argv[0]];
     return run(argv.slice(1), deps);
   }
+  if (argv[0] === 'bench' || argv[0] === 'improve') {
+    const sb = require('./sentinel-bench');
+    return (argv[0] === 'bench' ? sb.benchCommand : sb.improveCommand)(argv.slice(1), deps);
+  }
+  if (argv[0] === 'fix') return require('./sentinel-fix').fixCommand(argv.slice(1), deps);
   if (argv[0] === 'upload') return auditUploadCommand(argv.slice(1), deps);
+  if (argv[0] === 'recheck') return auditRecheckCommand(argv.slice(1), deps);
   if (argv[0] === 'schedule') return auditScheduleCommand(argv.slice(1), deps);
   let opts;
   try { opts = parseAuditArgs(argv); } catch (e) { console.error(`security-review audit: ${e.message}`); return 2; }
@@ -647,19 +786,7 @@ async function auditCommand(argv, deps = {}) {
   let runJobs = deps.runJobs;
   const spend = hosted ? cloud.spendGuard({ quoteCall: deps.quoteCall }) : null;
   if (!runJobs && hosted) runJobs = cloud.atrisJobRunner({ token, spend });
-  const confirmSpend = async (estimate) => {
-    const quote = await cloud.quoteEstimate(estimate, { token });
-    spend.max = capOverride || quote.credits;
-    spend.limits = quote.limits;
-    tell(`\n  ${cloud.describeQuote(quote)}\n`);
-    if (capOverride) tell(`  this scheduled run may spend at most ${capOverride} credits, as approved`);
-    if (opts.yes) return true;
-    const input = deps.input || process.stdin;
-    if (!input.isTTY && !deps.input) { console.error('  nothing was spent. add --yes to run without this question'); return false; }
-    const yes = await (deps.ask || askYesNo)('  spend these credits? (y/N) ', { input, output: opts.json ? process.stderr : process.stdout });
-    if (!yes) tell('  nothing was spent');
-    return yes;
-  };
+  const confirmSpend = spendConfirmer({ cloud, token, spend, capOverride, opts, deps, tell });
   let result;
   try {
     result = await audit.runAudit({
@@ -672,12 +799,12 @@ async function auditCommand(argv, deps = {}) {
     return 2;
   }
   if (result.declined) return 1;
-  const fail = audit.shouldFailAudit(result.records);
+  const fail = !opts.planOnly && audit.shouldFailRun(result.dir, result.records);
   if (opts.json) console.log(JSON.stringify({ ok: !fail, dir: result.dir, meta: result.meta, findings: result.records }, null, 2));
   else console.log(renderAuditLanding(result));
   if (spend && spend.blocked) tell(`  stopped at the approved limit of ${spend.max} credits. ${spend.blocked} model call${spend.blocked === 1 ? '' : 's'} did not run and wait for the next run`);
   if (opts.upload && token && !opts.planOnly) {
-    try { await uploadAfterRun(result.dir, { token, quiet: opts.json, cloud }); } catch (e) { tell(`  warning: could not save the summary to your atris account: ${e.message}. the review itself is done`); }
+    try { await uploadAfterRun(result.dir, { token, quiet: opts.json, cloud, root, env: deps.env || process.env }); } catch (e) { tell(`  warning: could not save the summary to your atris account: ${e.message}. the review itself is done`); }
   }
   return fail ? 1 : 0;
 }
@@ -714,6 +841,15 @@ function printAuditHelp() {
     atris sentinel --no-upload                  keep this run on this machine only
     atris sentinel upload [run-folder]          save a past run (default: the last one)
 
+  re-checking old findings (every review does this first):
+
+    atris sentinel recheck [path]               only re-check the last review's open findings
+    atris sentinel recheck --engine atris       re-check on atris models, price shown first
+
+  a finding whose code did not change stays open without a call. a changed
+  one goes to the verifier, never the engine that found it. it is marked
+  fixed only with a yes and the line that now closes it. unsure stays open.
+
   only the summary is saved: plain sentences, file:line locations and counts.
   source code and code lines never leave in an upload.
 
@@ -729,6 +865,18 @@ function printAuditHelp() {
   results go to your atris dashboard when you are logged in. add --no-upload
   to keep them on this machine. secret values and file contents never leave.
 
+  the exam and the loop that improves the sentinel (in an atris checkout):
+
+    atris sentinel bench [--summary]            score the guard and agent check on a seen and a held-out half
+    atris sentinel improve [--engine claude]    one engine proposes a change, the exam decides if it stays
+    atris sentinel improve --schedule           run the improve loop nightly
+
+  turning a confirmed finding into a fix:
+
+    atris sentinel fix                          list confirmed findings you can fix
+    atris sentinel fix <id> [path]              smallest fix plus a regression test on a new branch
+    atris sentinel fix help                     how a fix is proved before it is committed
+
   reviews on a timer:
 
     atris sentinel schedule --every day [path]  quick review once a day, saved to your account

package/commands/sentinel-bench.js

@@ -0,0 +1,172 @@
+'use strict';
+
+// atris sentinel bench and atris sentinel improve.
+//
+//   atris sentinel bench [--summary] [--json] [--review] [--sets guard,agents]
+//   atris sentinel bench --split <file> --set guard|agents|review
+//   atris sentinel improve [--engine claude] [--offline] [--json]
+//   atris sentinel improve --schedule [--every 24] [--engine claude] | --unschedule
+
+const path = require('path');
+
+function readFlag(argv, name) {
+  const i = argv.indexOf(name);
+  if (i !== -1 && argv[i + 1] !== undefined && !String(argv[i + 1]).startsWith('--')) return argv[i + 1];
+  const inline = argv.find((a) => String(a).startsWith(`${name}=`));
+  return inline ? inline.slice(name.length + 1) : null;
+}
+
+function checkFlags(argv, flags, values) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    const name = a.split('=')[0];
+    if (values.includes(name)) { if (!a.includes('=')) i += 1; continue; }
+    if (flags.includes(a)) continue;
+    throw new Error(`unknown option: ${a}`);
+  }
+}
+
+function benchHelp() {
+  console.log(`
+  atris sentinel bench, a fixed exam for the sentinel
+
+    atris sentinel bench                 score the guard and the agent check
+    atris sentinel bench --summary       totals only, no item lines
+    atris sentinel bench --review        also run the review set on engines (costs engine time)
+    atris sentinel bench --json          raw numbers for scripts
+    atris sentinel bench --split <file> --set guard|agents|review
+                                         split new items into the seen half (in the repo)
+                                         and the sealed held-out half (on this machine).
+                                         the plaintext input is replaced with an encrypted copy
+
+  the seen half lives in atris/sentinel-bench. the held-out half lives in
+  ~/.atris/sentinel-holdout, encrypted with a key in your keychain. its
+  items are never printed. only lib/sentinel-rules.json of the checkout is
+  judged, always with this atris's own code. every number
+  is raw: attacks blocked, everyday commands wrongly blocked, problems
+  found, false alarms. there is no blended score.
+`);
+  return 0;
+}
+
+async function benchCommand(argv, deps = {}) {
+  if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') return benchHelp();
+  try { checkFlags(argv, ['--summary', '--json', '--review'], ['--split', '--set', '--sets', '--target', '--seen', '--hunter', '--verifier', '--budget']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  const bench = require('../lib/sentinel-bench');
+  const env = deps.env || process.env;
+  const root = path.resolve(readFlag(argv, '--target') || deps.root || process.cwd());
+  const seenDir = path.resolve(readFlag(argv, '--seen') || bench.seenDirOf(root));
+  const holdoutDir = bench.defaultHoldoutDir(env);
+  const split = readFlag(argv, '--split');
+  if (split) {
+    const set = readFlag(argv, '--set');
+    if (!set) { console.error('  --split needs --set guard, agents or review'); return 2; }
+    let res;
+    try { res = bench.splitCorpus(path.resolve(split), set, { seenDir, holdoutDir, env }); } catch (e) { console.error(`  could not split: ${e.message}`); return 1; }
+    if (argv.includes('--json')) { console.log(JSON.stringify({ ok: true, ...res }, null, 2)); return 0; }
+    console.log(`\n  ${res.seen} items went to the seen half: ${path.relative(process.cwd(), res.seen_file) || res.seen_file}`);
+    console.log(`  ${res.holdout} items went to the held-out half on this machine`);
+    if (res.skipped) console.log(`  ${res.skipped} items were already in a half and were skipped`);
+    if (res.invalid) console.log(`  ${res.invalid} lines were not valid items and were skipped`);
+    console.log(`  the plaintext input was replaced with an encrypted copy at ${res.sealed_source}. no readable held-out item is left behind\n`);
+    return 0;
+  }
+  const review = argv.includes('--review');
+  const setsRaw = readFlag(argv, '--sets');
+  const sets = setsRaw ? setsRaw.split(',').map((s) => s.trim()).filter(Boolean) : ['guard', 'agents', ...(review ? ['review'] : [])];
+  const bad = sets.filter((s) => !bench.SETS.includes(s));
+  if (bad.length) { console.error(`  unknown set: ${bad.join(', ')}. use guard, agents or review`); return 2; }
+  const budget = readFlag(argv, '--budget');
+  const reviewOpts = review ? {
+    hunter: readFlag(argv, '--hunter') || 'codex',
+    verifier: readFlag(argv, '--verifier') || 'claude',
+    ...(budget ? { budget: Number(budget) } : {}),
+    log: argv.includes('--json') ? () => {} : (m) => console.error(`  ${m}`),
+    ...(deps.runJobs ? { runJobs: deps.runJobs } : {}),
+  } : null;
+  let report;
+  try { report = await bench.runBench({ target: root, seenDir, sets, review: reviewOpts, env }); } catch (e) { console.error(`  the exam did not run: ${e.message}`); return 1; }
+  const pub = bench.publicReport(report, { summary: argv.includes('--summary') });
+  if (argv.includes('--json')) console.log(JSON.stringify({ ok: true, ...pub }, null, 2));
+  else console.log(bench.renderReport(pub, { holdoutDir: holdoutDir.replace(require('os').homedir(), '~') }));
+  return 0;
+}
+
+function improveHelp() {
+  console.log(`
+  atris sentinel improve, one exam-checked change to the sentinel
+
+    atris sentinel improve [--engine claude]   propose one change and judge it
+    atris sentinel improve --offline           skip the published advisory lookup
+    atris sentinel improve --schedule [--every 24] [--engine claude]
+                                               run it on a timer, nightly by default
+    atris sentinel improve --unschedule        turn the timer off
+
+  claude proposes one change to lib/sentinel-rules.json on a new branch,
+  sealed off from the held-out exam. the sentinel bench, fixed code with no
+  model, scores it before and after. it is kept only when
+  held-out attack catch holds or rises, wrong blocks and false alarms do
+  not rise and no seen item that passed now fails. a kept change waits on
+  its branch for you. nothing is merged, pushed or released.
+`);
+  return 0;
+}
+
+async function improveCommand(argv, deps = {}) {
+  if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') return improveHelp();
+  try { checkFlags(argv, ['--json', '--offline', '--schedule', '--unschedule'], ['--engine', '--every']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  const improve = require('../lib/sentinel-improve');
+  const env = deps.env || process.env;
+  const engine = readFlag(argv, '--engine') || 'claude';
+  if (!/^[a-z][a-z0-9:_-]{0,30}$/.test(engine)) { console.error(`  unknown engine: ${engine}`); return 2; }
+  const refused = require('../lib/sentinel-improve').refusedEngine(engine);
+  if (refused && !argv.includes('--unschedule')) { console.error(`  ${refused}`); return 2; }
+  const root = deps.root || process.cwd();
+  if (argv.includes('--schedule') || argv.includes('--unschedule')) {
+    const { installKeep, removeKeep } = require('../lib/campaign-keep');
+    const everyHours = Number(readFlag(argv, '--every') || 24);
+    if (!Number.isFinite(everyHours) || everyHours <= 0) { console.error('  --every needs a number of hours'); return 2; }
+    let top;
+    try { top = require('child_process').execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { console.error('  run this inside the atris checkout the loop should improve'); return 2; }
+    const plan = improve.schedulePlan({ root: top, engine, everyHours, env, atrisBin: deps.atrisBin });
+    if (argv.includes('--unschedule')) {
+      const removed = (deps.removeKeep || removeKeep)(plan);
+      if (!removed.ok) { console.error(`  could not turn the timer off: ${removed.error}`); return 1; }
+      console.log(`  sentinel improve timer: ${removed.removed === false ? 'was not on' : 'off'} for ${top}`);
+      return 0;
+    }
+    const space = require('../lib/worktree-space');
+    const bin = deps.atrisBin || path.join(__dirname, '..', 'bin', 'atris.js');
+    if (!deps.atrisBin && (space.isAgentCopyPath(bin) || space.isScratchPath(bin) || space.isAgentCopyPath(top))) {
+      console.error('  refusing: this atris or this checkout lives in a folder that gets removed. install the timer from a lasting checkout');
+      return 2;
+    }
+    const installed = (deps.installKeep || installKeep)(plan);
+    if (!installed.ok) { console.error(`  could not turn the timer on: ${installed.error}`); return 1; }
+    console.log(`  sentinel improve timer: on for ${top}, every ${everyHours} ${everyHours === 1 ? 'hour' : 'hours'} with ${engine}`);
+    console.log(`  log: ${plan.log_path}`);
+    console.log('  each run leaves a receipt in ~/.atris/sentinel-improve/receipts. kept changes wait on their branch for you');
+    return 0;
+  }
+  let res;
+  try {
+    res = await improve.improve({ root, engine, env, offline: argv.includes('--offline'), log: argv.includes('--json') ? () => {} : (m) => console.log(`  ${m}`), ...(deps.improveOpts || {}) });
+  } catch (e) { console.error(`  improve did not run: ${e.message}`); return 1; }
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify({ ok: !res.error, kept: res.kept, branch: res.branch, error: res.error || null, decision: res.decision, receipt: res.receipt }, null, 2));
+    return res.error ? 1 : 0;
+  }
+  console.log('');
+  if (res.error) console.log(`  stopped: ${res.error}`);
+  else if (res.kept) console.log(`  kept. the change waits on branch ${res.branch} for your review`);
+  else console.log('  rejected. the branch was removed');
+  if (res.decision) {
+    for (const g of res.decision.gains) console.log(`  gain: ${g}`);
+    for (const n of res.decision.notes || []) console.log(`  note: ${n}`);
+    for (const r of res.decision.reasons) console.log(`  stop: ${r}`);
+  }
+  console.log(`  receipt: ${res.receipt.replace(require('os').homedir(), '~')}\n`);
+  return res.error ? 1 : 0;
+}
+
+module.exports = { benchCommand, improveCommand };