atris 3.82.7 → 3.82.9

package/bin/atris.js

@@ -144,7 +144,8 @@ const jsonRequested = process.argv.slice(2).includes('--json');
 const dryRunRequested = updateArgs.includes('--dry-run');
 const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested || jsonRequested);
 // Local-only commands make no registry call and start no background install.
-if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update', 'mcp', 'recap', '99'].includes(updateCommand)))) {
+// sentinel prints its own one-line notice at the end of the run instead.
+if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update', 'mcp', 'recap', '99', 'sentinel'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
       if (updateInfo) {
@@ -3378,8 +3379,10 @@ if (command === 'guide') {
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'sentinel') {
   // Sentinel: the full security audit (engines hunt, another model verifies). Same as `security-review audit`.
+  // A stale install gets one plain upgrade line at the end of every sentinel command.
+  const sentinelNotice = require('../commands/sentinel-powers').startUpdateNotice(process.argv.slice(3));
   Promise.resolve().then(() => require('../commands/security-review').securityReviewCommand(['audit', ...process.argv.slice(3)]))
-    .then((code) => exitAfterStdoutDrain(typeof code === 'number' ? code : 0))
+    .then(async (code) => { try { await sentinelNotice.print(); } catch {} exitAfterStdoutDrain(typeof code === 'number' ? code : 0); })
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'security-review' || command === 'secure') {
   // Security review: deterministic secrets/PII/code-risk scan (no LLM). Exit 1 = HIGH finding,

package/commands/security-review.js

@@ -859,6 +859,7 @@ function printAuditHelp() {
     atris sentinel agents --home                also check ~/.claude and ~/.codex
     atris sentinel watch [path]                 known attacks in your dependencies (osv database)
     atris sentinel watch --fix                  update affected packages on a new branch, never pushed
+    atris sentinel watch --fix --allow-major    also take fixes that jump to a new major version
     atris sentinel guard install [--global]     stop risky agent commands before they run
     atris sentinel guard test                   see which sample commands the guard stops
 

package/commands/sentinel-bench.js

@@ -4,7 +4,8 @@
 //
 //   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 [--engine claude] [--focus exfil|destroy|disarm|agents] [--offline] [--json]
+//   atris sentinel improve --rounds N --parallel K --review codex [--max-minutes 120] [--max-calls N] [--push]
 //   atris sentinel improve --schedule [--every 24] [--engine claude] | --unschedule
 
 const path = require('path');
@@ -51,12 +52,21 @@ function benchHelp() {
 
 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; }
+  try { checkFlags(argv, ['--summary', '--json', '--review'], ['--split', '--set', '--sets', '--target', '--seen', '--hunter', '--verifier', '--budget', '--screen']); } 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 screen = readFlag(argv, '--screen');
+  if (screen) {
+    // Internal to the night run: refused ids only, as json.
+    let candidates;
+    try { candidates = JSON.parse(require('fs').readFileSync(path.resolve(screen), 'utf8')); } catch (e) { console.error(`  could not read the items to screen: ${e.message}`); return 1; }
+    if (!Array.isArray(candidates)) { console.error('  the items to screen must be a json list'); return 1; }
+    console.log(JSON.stringify({ ok: true, ...bench.screenItems(candidates, { holdoutDir, env }) }));
+    return 0;
+  }
   const split = readFlag(argv, '--split');
   if (split) {
     const set = readFlag(argv, '--set');
@@ -97,26 +107,49 @@ function improveHelp() {
   atris sentinel improve, one exam-checked change to the sentinel
 
     atris sentinel improve [--engine claude]   propose one change and judge it
+    atris sentinel improve --focus exfil       point the proposer at one area:
+                                               exfil, destroy, disarm or agents
     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
 
+  a night run, many changes in one sitting:
+
+    atris sentinel improve --rounds 4 --parallel 3 --review codex
+        --rounds N        up to N rounds. each starts from what shipped before
+        --parallel K      K proposers at once, each on its own area (up to 4)
+        --review codex    codex reviews every change the exam keeps. SHIP keeps
+                          it. FIX rejects it and its examples join the exam
+        --max-minutes M   stop after M minutes (120 by default)
+        --max-calls C     stop after C proposer and reviewer calls
+        --push            push the two night branches by name when done
+    atris sentinel improve --break-lock    clear a night run lock whose run is gone
+
+  shipped rules land on sentinel-improve/night-<date>. new exam items land
+  apart on sentinel-exam/<date>. you can review them on their own. the
+  run stops early after two rounds with nothing shipped or no held-out gain.
+
   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.
+  its branch for you. nothing is merged or released. nothing is pushed without --push.
 `);
   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; }
+  try { checkFlags(argv, ['--json', '--offline', '--schedule', '--unschedule', '--push', '--break-lock'], ['--engine', '--every', '--focus', '--rounds', '--parallel', '--review', '--max-minutes', '--max-calls']); } catch (e) { console.error(`  ${e.message}`); return 2; }
   const improve = require('../lib/sentinel-improve');
   const env = deps.env || process.env;
+  if (argv.includes('--break-lock')) {
+    const res = require('../lib/sentinel-night').breakLock(env);
+    (res.refused ? console.error : console.log)(`  ${res.message}`);
+    return res.refused ? 1 : 0;
+  }
   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);
@@ -148,9 +181,14 @@ async function improveCommand(argv, deps = {}) {
     console.log('  each run leaves a receipt in ~/.atris/sentinel-improve/receipts. kept changes wait on their branch for you');
     return 0;
   }
+  const focus = readFlag(argv, '--focus');
+  if (argv.includes('--focus') && !focus) { console.error('  --focus needs exfil, destroy, disarm or agents'); return 2; }
+  if (focus && !improve.FOCI.includes(focus)) { console.error(`  unknown focus: ${focus}. use exfil, destroy, disarm or agents`); return 2; }
+  const nightFlags = ['--rounds', '--parallel', '--review', '--max-minutes', '--max-calls', '--push'];
+  if (argv.some((a) => nightFlags.includes(String(a).split('=')[0]))) return nightCommand(argv, { root, engine, env, focus, deps });
   let res;
   try {
-    res = await improve.improve({ root, engine, env, offline: argv.includes('--offline'), log: argv.includes('--json') ? () => {} : (m) => console.log(`  ${m}`), ...(deps.improveOpts || {}) });
+    res = await improve.improve({ root, engine, env, focus, 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));
@@ -169,4 +207,44 @@ async function improveCommand(argv, deps = {}) {
   return res.error ? 1 : 0;
 }
 
+function numFlag(argv, name) {
+  const v = readFlag(argv, name);
+  if (v === null) return argv.includes(name) ? NaN : undefined;
+  return Number(v);
+}
+
+async function nightCommand(argv, { root, engine, env, focus, deps }) {
+  const improve = require('../lib/sentinel-improve');
+  const review = readFlag(argv, '--review');
+  if (argv.includes('--review') && !review) { console.error('  --review needs codex'); return 2; }
+  if (review && review !== 'codex') { console.error('  --review takes codex only'); return 2; }
+  const opts = { root, engine, env, focus, review, push: argv.includes('--push'), offline: argv.includes('--offline') };
+  for (const [flag, key] of [['--rounds', 'rounds'], ['--parallel', 'parallel'], ['--max-minutes', 'maxMinutes'], ['--max-calls', 'maxCalls']]) {
+    const n = numFlag(argv, flag);
+    if (n === undefined) continue;
+    if (!Number.isFinite(n) || n <= 0) { console.error(`  ${flag} needs a number above 0`); return 2; }
+    if (key !== 'maxMinutes' && !Number.isInteger(n)) { console.error(`  ${flag} needs a whole number`); return 2; }
+    if (key === 'parallel' && n > improve.FOCI.length) { console.error(`  --parallel goes up to ${improve.FOCI.length}, one proposer per focus area`); return 2; }
+    opts[key] = n;
+  }
+  const json = argv.includes('--json');
+  let res;
+  try {
+    res = await require('../lib/sentinel-night').night({ ...opts, log: json ? () => {} : (m) => console.log(`  ${m}`), ...(deps.nightOpts || {}) });
+  } catch (e) { console.error(`  improve did not run: ${e.message}`); return 1; }
+  if (json) {
+    console.log(JSON.stringify({ ok: !res.error, shipped: res.landed, stop: res.stop, night_branch: res.night_branch, exam_branch: res.exam_branch, exam_added: res.exam_added, calls: res.calls, minutes: res.minutes, pushed: res.pushed, error: res.error || null, receipt: res.receipt }, null, 2));
+    return res.error ? 1 : 0;
+  }
+  const home = require('os').homedir();
+  console.log('');
+  console.log(`  ${res.landed} ${res.landed === 1 ? 'change' : 'changes'} shipped in ${res.rounds.length} ${res.rounds.length === 1 ? 'round' : 'rounds'}. stopped because ${res.stop}`);
+  if (res.night_branch) console.log(`  rules wait on ${res.night_branch}`);
+  if (res.exam_branch) console.log(`  ${res.exam_added} new exam items wait on ${res.exam_branch}`);
+  if (res.pushed.length) console.log(`  pushed: ${res.pushed.join(', ')}`);
+  console.log(`  used ${res.calls} engine calls in ${res.minutes} minutes`);
+  console.log(`  receipt: ${res.receipt.replace(home, '~')}\n`);
+  return res.error ? 1 : 0;
+}
+
 module.exports = { benchCommand, improveCommand };

package/commands/sentinel-powers.js

@@ -5,7 +5,7 @@
 //
 //   atris sentinel agents [path] [--home]        check an agent setup
 //   atris sentinel guard install|uninstall|status|test [--global]
-//   atris sentinel watch [path] [--fix]          known attacks in dependencies
+//   atris sentinel watch [path] [--fix] [--allow-major]  known attacks in dependencies
 //   atris sentinel flush                         send queued guard events
 //
 // An upload problem is a warning line. It never changes the exit code.
@@ -50,6 +50,34 @@ function uploadLine(res, what) {
   return `  sent ${res.sent - (res.resolved || 0)} ${what} to your atris dashboard${resolved}. no file contents or secret values were sent`;
 }
 
+// ---------------------------------------------------------------- update
+
+// A stale global install misses sentinel fixes. Every sentinel command
+// ends with one line when npm has a newer atris. The check starts with the
+// command and gets a short wait at the end. It never blocks or fails a run.
+function startUpdateNotice(argv = [], { env = process.env, check, timeoutMs = 1500, packageRoot = path.join(__dirname, '..') } = {}) {
+  const off = env.ATRIS_SKIP_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER
+    || argv.some((a) => ['--json', '--help', '-h', 'help', '--quiet'].includes(a));
+  if (off) return { print: async () => null };
+  const updates = require('../utils/update-check');
+  let pending;
+  try { pending = Promise.resolve((check || updates.checkForUpdates)()).catch(() => null); } catch { pending = Promise.resolve(null); }
+  return {
+    async print(log = console.log) {
+      let timer;
+      const late = new Promise((r) => { timer = setTimeout(() => r(null), timeoutMs); if (timer.unref) timer.unref(); });
+      const info = await Promise.race([pending, late]);
+      clearTimeout(timer);
+      if (!info || !info.needsUpdate) return null;
+      let how = 'npm install -g atris@latest';
+      try { if (updates.isGitCheckout(packageRoot)) how = 'atris upgrade'; } catch {}
+      const line = `  a newer atris is out: ${info.latest}. this one is ${info.installed}. update with: ${how}`;
+      log(line);
+      return line;
+    },
+  };
+}
+
 // ---------------------------------------------------------------- agents
 
 async function runAgents(root, { home = false, upload = true, deps = {} } = {}) {
@@ -83,37 +111,92 @@ async function agentsCommand(argv, deps = {}) {
 
 // ---------------------------------------------------------------- watch
 
+// A threat that is gone here counts as fixed only on the repo's default
+// branch, or when the default branch no longer holds the affected version.
+// On a side branch it stays open on the dashboard.
+function holdForBranch(branch) {
+  if (!branch || branch.onDefault) return null;
+  const live = branch.liveFingerprints;
+  if (!live) return () => true;
+  return (fp) => live.has(fp);
+}
+
 async function runWatchCheck(root, { upload = true, deps = {} } = {}) {
   const watch = require('../lib/sentinel-watch');
   const events = require('../lib/sentinel-events');
-  const result = await watch.runWatch(root, { base: deps.osvBase || process.env.ATRIS_OSV_BASE || watch.OSV_BASE, ...(deps.request ? { request: deps.request } : {}) });
+  const result = await watch.runWatch(root, { base: deps.osvBase || process.env.ATRIS_OSV_BASE || watch.OSV_BASE, ...(deps.request ? { request: deps.request } : {}), ...(deps.maxLockfileBytes ? { maxBytes: deps.maxLockfileBytes } : {}) });
   const evs = watch.toEvents(result, { repo: deps.repo });
+  let branch = null;
+  try { branch = watch.branchState(root, { run: deps.run }); } catch { branch = { git: true, onDefault: false, liveFingerprints: null }; }
   let res;
   if (result.offline) res = { ok: true, skipped: 'offline', sent: 0 };
   else {
     try {
-      res = await events.reportFindings(root, 'threat', evs, { token: upload ? tokenFor(deps) : '', base: deps.base, env: deps.env || process.env, upload });
+      // Per lockfile: an earlier threat is fixed only when every lockfile it
+      // was found in was read this time and none of them holds it now. One
+      // whose lockfile was not read (depth, cap, size, error, moved or
+      // deleted) stays open. An old record with no lockfile list needs a
+      // complete scan.
+      const read = new Set(result.lockfiles.map((l) => l.file));
+      const branchHold = holdForBranch(branch);
+      const why = { unread: 0, branch: 0 };
+      // Locations not read this run are kept by reportFindings itself. Here:
+      // an old record with no lockfile list plus the branch rule.
+      const hold = (fp, prev) => {
+        const lfs = prev && Array.isArray(prev.lockfiles) && prev.lockfiles.length ? prev.lockfiles : null;
+        if (!lfs && result.incomplete) { why.unread += 1; return true; }
+        if (branchHold && branchHold(fp)) { why.branch += 1; return true; }
+        return false;
+      };
+      res = await events.reportFindings(root, 'threat', evs, { token: upload ? tokenFor(deps) : '', base: deps.base, env: deps.env || process.env, upload, hold, meta: watch.lockfilesByFingerprint(result), read });
+      res.heldUnread = why.unread + (res.heldLocations || 0);
+      res.heldBranch = why.branch;
     } catch (e) { res = { ok: false, reason: e.message }; }
   }
-  return { result, events: evs, upload: res };
+  return { result, events: evs, upload: res, branch };
+}
+
+function heldLines(upload, branch) {
+  const L = [];
+  const u = (upload && upload.heldUnread) || 0;
+  const b = (upload && upload.heldBranch) || 0;
+  if (u) L.push(`  ${u} earlier threat${u === 1 ? ' was' : 's were'} in a lockfile this check did not read. ${u === 1 ? 'it stays' : 'they stay'} open on your dashboard`);
+  if (b) {
+    const target = (branch && branch.defaultBranch) || 'the default branch';
+    L.push(`  fixed on this branch, not yet live: ${b} threat${b === 1 ? '' : 's'}. ${b === 1 ? 'it stays' : 'they stay'} open on your dashboard until the fix is merged into ${target}`);
+  }
+  return L;
+}
+
+// One or two lines per package left for a person. Never cut short.
+function manualLines(manual) {
+  const L = [];
+  if (!manual || !manual.length) return L;
+  L.push(`  left for you to update (${manual.length}):`);
+  for (const a of manual) {
+    const to = a.fixed ? ` to ${a.fixed}` : '';
+    L.push(`    ${a.name} ${a.version}${to} in ${a.lockfile || a.ecosystem}: ${a.why || 'not updated'}`);
+  }
+  return L;
 }
 
 async function watchCommand(argv, deps = {}) {
   let opts;
-  try { opts = parseFlags(argv, ['fix', 'json', 'no-upload']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  try { opts = parseFlags(argv, ['fix', 'json', 'no-upload', 'allow-major']); } catch (e) { console.error(`  ${e.message}`); return 2; }
   let root;
   try { root = resolveRoot(opts, deps); } catch (e) { console.error(`  ${e.message}`); return 2; }
   const watch = require('../lib/sentinel-watch');
-  const { result, upload } = await runWatchCheck(root, { upload: !opts.noUpload, deps });
+  const { result, upload, branch } = await runWatchCheck(root, { upload: !opts.noUpload, deps });
   let fix = null;
   if (opts.fix && !result.offline && result.affected.length) {
-    try { fix = watch.applyFix(root, result, { log: (m) => console.error(`  ${m}`) }); } catch (e) { fix = { ok: false, reason: String(e.message || e).split('\n')[0] }; }
+    try { fix = watch.applyFix(root, result, { run: deps.run, allowMajor: Boolean(opts.allowMajor) }); } catch (e) { fix = { ok: false, reason: String(e.message || e).split('\n')[0] }; }
   }
   if (opts.json) {
-    console.log(JSON.stringify({ ok: !result.affected.some((a) => a.severity === 'critical' || a.severity === 'high'), ...result, upload, fix }, null, 2));
+    console.log(JSON.stringify({ ok: !result.affected.some((a) => a.severity === 'critical' || a.severity === 'high'), ...result, upload, branch: branch ? { ...branch, liveFingerprints: undefined } : null, fix }, null, 2));
   } else {
     console.log(watch.renderReport(result));
     if (upload.skipped !== 'offline') console.log(uploadLine(upload, 'the threats'));
+    for (const l of heldLines(upload, branch)) console.log(l);
     if (fix) {
       console.log('');
       if (!fix.ok) console.log(`  the fix did not run: ${fix.reason}`);
@@ -124,9 +207,12 @@ async function watchCommand(argv, deps = {}) {
         console.log(`  go back with: git checkout ${fix.from || 'main'}`);
         console.log('  nothing was pushed');
       }
-      if (fix.manual && fix.manual.length) {
-        console.log(`  update these yourself: ${fix.manual.map((a) => `${a.name} to ${a.fixed}`).join(', ')}`);
+      for (const te of fix.toolErrors || []) {
+        console.log(`  ${te.tool} could not update ${te.lockfile}. it said:`);
+        for (const l of te.lines) console.log(`    ${l}`);
+        if (te.hint) console.log(`  ${te.hint}`);
       }
+      for (const l of manualLines(fix.manual)) console.log(l);
     }
     console.log('');
   }
@@ -281,4 +367,4 @@ async function runScheduledFreeChecks(root, deps = {}) {
   return out;
 }
 
-module.exports = { agentsCommand, guardCommand, watchCommand, flushCommand, runScheduledFreeChecks, runAgents, runWatchCheck };
+module.exports = { agentsCommand, guardCommand, watchCommand, flushCommand, runScheduledFreeChecks, runAgents, runWatchCheck, startUpdateNotice };

package/lib/sentinel-bench.js

@@ -158,12 +158,18 @@ function keyFromKeychain() {
   return add.status === 0 ? read() : null;
 }
 
+// Where the last key came from: 'keychain' or 'file'. The night run asks
+// for this in the report and refuses a file key: a reviewer that can read
+// files could read a key file too.
+let lastKeySource = null;
+
 function holdoutKey(env = process.env) {
-  if (env.ATRIS_SENTINEL_KEY_FILE) return keyFromFile(env.ATRIS_SENTINEL_KEY_FILE);
+  if (env.ATRIS_SENTINEL_KEY_FILE) { lastKeySource = 'file'; return keyFromFile(env.ATRIS_SENTINEL_KEY_FILE); }
   if (process.platform === 'darwin' && env.ATRIS_SENTINEL_KEYCHAIN !== '0') {
     const k = keyFromKeychain();
-    if (k) return k;
+    if (k) { lastKeySource = 'keychain'; return k; }
   }
+  lastKeySource = 'file';
   return keyFromFile(path.join(homeDir(env), '.atris', 'sentinel-judge', 'holdout.key'));
 }
 
@@ -416,9 +422,47 @@ async function runBench({ target, seenDir, holdoutDir, sets = ['guard', 'agents'
       report[half][set] = score;
     }
   }
+  report.key_source = lastKeySource;
   return report;
 }
 
+// ---------------------------------------------------------------- screen
+
+// Lowercase with whitespace collapsed, for overlap checks.
+function normalizeText(v) {
+  return String(v || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function itemTexts(set, item) {
+  if (set === 'guard') return [item.command !== undefined ? item.command : JSON.stringify(item.input || '')];
+  return Object.entries(item.files || {}).map(([f, c]) => `${f} ${typeof c === 'string' ? c : JSON.stringify(c)}`).concat(Object.values(item.files || {}).map((c) => (typeof c === 'string' ? c : JSON.stringify(c))));
+}
+
+// New seen items proposed from outside (the night reviewer) checked against
+// the held-out half. This runs in the judge, the one process that holds it. An item
+// whose normalized text equals, contains or sits inside any held-out item's
+// text is refused. Only the refused ids leave this function, never a
+// held-out item. A held-out set that cannot be read refuses everything.
+function screenItems(candidates, { holdoutDir, env = process.env } = {}) {
+  const held = path.resolve(holdoutDir || defaultHoldoutDir(env));
+  const texts = [];
+  let unreadable = false;
+  for (const set of ['guard', 'agents']) {
+    try {
+      const loaded = loadSet(held, set, { held: true, env });
+      for (const item of loaded.items) for (const t of itemTexts(set, item)) { const n = normalizeText(t); if (n) texts.push(n); }
+    } catch { unreadable = true; }
+  }
+  const refused = [];
+  for (const c of candidates) {
+    if (!c || typeof c.id !== 'string' || (c.set !== 'guard' && c.set !== 'agents')) continue;
+    if (unreadable) { refused.push(c.id); continue; }
+    const mine = itemTexts(c.set, c.item || {}).map(normalizeText).filter(Boolean);
+    if (!mine.length || mine.some((m) => texts.some((h) => h === m || h.includes(m) || m.includes(h)))) refused.push(c.id);
+  }
+  return { refused, key_source: lastKeySource, unreadable };
+}
+
 // What may leave this module: held-out totals only, never an item. With
 // summary, seen items are dropped too.
 function publicReport(report, { summary = false } = {}) {
@@ -437,6 +481,8 @@ function publicReport(report, { summary = false } = {}) {
     holdout_dir: report.holdout_dir,
     // Sealed split sources, paths only. The improver uses them to deny reads.
     sealed_sources: report.sealed_sources || [],
+    // How the judge got the held-out key: 'keychain' or 'file'. Never the key.
+    key_source: report.key_source || null,
   };
 }
 
@@ -541,6 +587,8 @@ module.exports = {
   SETS,
   readHeldText,
   readSealedSources,
+  normalizeText,
+  screenItems,
   FAKE,
   defaultHoldoutDir,
   expand,

package/lib/sentinel-events.js

@@ -225,31 +225,53 @@ function writeState(root, kind, open, env) {
 }
 
 // The open events of this run, plus a resolved copy of each finding the
-// last upload reported open that is gone now.
-function withResolved(root, kind, openEvents, { env = process.env, now = new Date() } = {}) {
+// last upload reported open that is gone now. hold(fp) true keeps a gone
+// finding open: it is not sent as resolved and stays in the state. A
+// later run can resolve it (a fix that is only on a side branch).
+//
+// read: the locations (lockfiles) this run read. A finding's recorded
+// locations are merged, never replaced: one leaves the set only when this
+// run read it and it no longer holds the finding. A finding resolves only
+// when its set is empty.
+function withResolved(root, kind, openEvents, { env = process.env, now = new Date(), hold = null, meta = null, read = null } = {}) {
   const before = readState(root, kind, env);
   const current = new Set(openEvents.map((e) => e.fingerprint));
   const resolved = [];
+  const held = [];
+  const heldLocations = [];
+  const next = {};
+  const unreadOf = (prev) => (read && prev && Array.isArray(prev.lockfiles) ? prev.lockfiles.filter((l) => !read.has(l)) : []);
   for (const [fp, prev] of Object.entries(before)) {
     if (current.has(fp)) continue;
+    const left = unreadOf(prev);
+    if (left.length) { held.push(fp); heldLocations.push(fp); next[fp] = { ...prev, lockfiles: left }; continue; }
+    if (hold && hold(fp, prev)) { held.push(fp); next[fp] = prev; continue; }
     resolved.push(makeEvent({ kind, repo: prev.repo, severity: prev.severity, title: prev.title, detail: prev.detail, status: 'resolved', fingerprint: fp, occurredAt: now }));
   }
-  const next = {};
-  for (const e of openEvents) next[e.fingerprint] = { repo: e.repo, severity: e.severity, title: e.title, detail: e.detail || '' };
-  return { events: [...openEvents, ...resolved], resolved, commit: () => writeState(root, kind, next, env) };
+  // meta: local-only facts kept beside a finding (never uploaded), like
+  // which lockfiles held it.
+  for (const e of openEvents) {
+    const m = (meta && meta.get(e.fingerprint)) || {};
+    const entry = { repo: e.repo, severity: e.severity, title: e.title, detail: e.detail || '', ...m };
+    if (Array.isArray(m.lockfiles)) entry.lockfiles = [...new Set([...m.lockfiles, ...unreadOf(before[e.fingerprint])])];
+    next[e.fingerprint] = entry;
+  }
+  return { events: [...openEvents, ...resolved], resolved, held, heldLocations, commit: () => writeState(root, kind, next, env) };
 }
 
 // Upload one run's findings of one kind and move the state on success.
-async function reportFindings(root, kind, openEvents, { token, base, env = process.env, upload = true, extra = [] } = {}) {
-  const plan = withResolved(root, kind, openEvents, { env });
-  if (!upload) return { ok: true, skipped: 'no-upload', sent: 0, resolved: plan.resolved.length };
-  if (!token) return { ok: false, skipped: 'not-logged-in', reason: 'not logged in', sent: 0, resolved: plan.resolved.length };
+async function reportFindings(root, kind, openEvents, { token, base, env = process.env, upload = true, extra = [], hold = null, meta = null, read = null } = {}) {
+  const plan = withResolved(root, kind, openEvents, { env, hold, meta, read });
+  const held = plan.held.length;
+  const heldLocations = plan.heldLocations.length;
+  if (!upload) return { ok: true, skipped: 'no-upload', sent: 0, resolved: plan.resolved.length, held, heldLocations };
+  if (!token) return { ok: false, skipped: 'not-logged-in', reason: 'not logged in', sent: 0, resolved: plan.resolved.length, held, heldLocations };
   const res = await postEvents([...extra, ...plan.events], { token, base });
   if (res.ok) {
     try { plan.commit(); } catch {}
     try { await flushQueue({ token, base, env }); } catch {}
   }
-  return { ...res, sent: res.ok ? plan.events.length + extra.length : 0, resolved: plan.resolved.length };
+  return { ...res, sent: res.ok ? plan.events.length + extra.length : 0, resolved: plan.resolved.length, held, heldLocations };
 }
 
 // ---------------------------------------------------------------- review fixes

package/lib/sentinel-guard.js

@@ -704,13 +704,26 @@ const BLOCK_REASON = {
   disarm: ['blocked: this command matches a known way to turn off a protection.', 'An agent ran a command that matches a known way to turn off a protection. Nothing changed.'],
 };
 
-// Literal command blocks from the rules file. Each block reads the whole
-// command with plain substring checks, limited to commands that run one of
-// its programs when it lists any. Linear time, no regular expression.
+// Literal command blocks from the rules file, matched with plain substring
+// checks in linear time, never a regular expression. A block that lists
+// programs reads only the words of each piece of the command that runs one of
+// them, so harmless pieces chained with && or ; never add up to a match. A
+// block with no programs reads the whole command. Fail closed: when a piece can
+// receive code from elsewhere (a pipe, any redirect or file write, a heredoc or
+// here-string, a command substitution, a shell variable, eval, source or a shell
+// string), every block reads the whole command. Per-piece matching is only for
+// plain chains that pass nothing between pieces.
+// Accepted limit: the guard judges one command at a time, so a script written by
+// one command and run by a later, separate command is not connected by any rule.
+const FEEDS_CODE = ['|', '<', '>', '`', '$', 'tee ', 'eval', 'source ', 'sh -c', 'bash -c', 'zsh -c'];
 function checkBlocks(command, cmds) {
+  const whole = FEEDS_CODE.some((t) => command.includes(t));
   for (const b of R().commandBlocks) {
+    const texts = b.programs && !whole
+      ? cmds.filter((c) => b.programs.has(c.name)).map((c) => (c.words || [c.name, ...(c.args || [])]).join(' '))
+      : [command];
     if (b.programs && !cmds.some((c) => b.programs.has(c.name))) continue;
-    if (!b.all.every((sub) => command.includes(sub))) continue;
+    if (!texts.some((t) => b.all.every((sub) => t.includes(sub)))) continue;
     const [reason, detail] = BLOCK_REASON[b.category];
     return block(`${b.category}-block`, b.category === 'disarm' ? 'high' : 'critical', reason, detail);
   }