atris 3.63.0 → 3.65.0

package/lib/engine-registry.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { stateHome } = require('./state-home');
 const childProcess = require('child_process');
 const crypto = require('crypto');
 const {
@@ -155,7 +156,10 @@ const ENGINE_SEED_META = Object.freeze({
   agy: Object.freeze({
     tier: 'pro',
     roles: Object.freeze(['executor']),
+    // The plain flash name takes its effort from --effort; the -high names
+    // bake the effort into the model.
     models: Object.freeze([
+      'gemini-3.8-flash',
       'gemini-3.8-flash-high',
       'gemini-3.7-flash-high',
       'gemini-3.1-pro-high',
@@ -402,6 +406,15 @@ const MACHINE_ROSTER_SCHEMA = 'atris.machine_roster.v1';
 // The owner's own job for small, tightly specified builds. A build resolved
 // with lowStakes checks this pick first, then the plain build pick.
 const SMALL_BUILD_JOB = 'small-build';
+// Jobs any engine may fill, keyed to the kind they count as when assign is
+// not told one. YouTube notes are plain read-only text, so agy (build-only)
+// and haiku (search and review) can both write them. Every other job keeps
+// its kind check.
+const ANY_ENGINE_JOBS = Object.freeze({ notes: 'search' });
+
+function jobTakesAnyEngine(key) {
+  return Object.prototype.hasOwnProperty.call(ANY_ENGINE_JOBS, String(key || ''));
+}
 
 function rosterJob(name) {
   const job = String(name || '').trim().toLowerCase();
@@ -472,10 +485,10 @@ function customRosterJobKeys(roster) {
 // an engine and model that can run, and that engine (or its backup) is ready.
 // A pick that cannot run never sets the job's kind, so it cannot block a
 // ready all-projects pick of another kind.
-function rosterPickLive(pick, now, registry) {
+function rosterPickLive(pick, now, registry, key) {
   const role = customPickRole(pick);
   if (!role || !canonicalEngineName(pick.engine)) return false;
-  return Boolean(rosterChoiceForPick(pick, role, registry, { label: rosterJobLabel(role), now }));
+  return Boolean(rosterChoiceForPick(pick, role, registry, { label: rosterJobLabel(role), now, anyEngine: jobTakesAnyEngine(key) }));
 }
 
 // The role a job name resolves as: a built-in job's own role, else the kind
@@ -491,7 +504,7 @@ function rosterJobRole(name, root = process.cwd(), options = {}) {
   const machine = options.machineRosterPicks || readMachineRoster(options);
   const picks = [session && session[key], project && project[key], machine && machine[key]].map(rosterPickObject).filter(Boolean);
   const registry = options.registry || readEngineRegistry(root, { persist: false });
-  const live = picks.find((pick) => rosterPickLive(pick, options.now, registry));
+  const live = picks.find((pick) => rosterPickLive(pick, options.now, registry, key));
   if (live) return customPickRole(live);
   const kind = inferJobKind(name);
   if (kind) return ENGINE_JOBS[kind];
@@ -612,7 +625,7 @@ function routerSkipsRole(engine, role) {
 function machineRosterFile(options = {}) {
   return options.machineRosterFile
     || process.env.ATRIS_MACHINE_ROSTER_PATH
-    || path.join(os.homedir(), '.atris', 'roster.json');
+    || path.join(stateHome(), '.atris', 'roster.json');
 }
 
 // The all-projects ROSTER.md. A scratch roster.json path (tests, sandboxes)
@@ -624,7 +637,7 @@ function machineRosterMarkdownFile(options = {}) {
   if (options.machineRosterFile || process.env.ATRIS_MACHINE_ROSTER_PATH) {
     return path.join(path.dirname(machineRosterFile(options)), 'ROSTER.md');
   }
-  return path.join(os.homedir(), '.atris', 'ROSTER.md');
+  return path.join(stateHome(), '.atris', 'ROSTER.md');
 }
 
 function projectRosterFile(root = process.cwd()) {
@@ -902,7 +915,7 @@ function rosterPickFromValue(value, role, options = {}) {
     extras = [inlineMax[1], ...extras];
   }
   const primary = resolveRosterWords(main);
-  if (!engineCanTake(primary.engine, role)) throw new Error(`${primary.engine} cannot do ${kind} work`);
+  if (!options.anyEngine && !engineCanTake(primary.engine, role)) throw new Error(`${primary.engine} cannot do ${kind} work`);
   let backup = null;
   let until = '';
   let untilYearless = '';
@@ -910,16 +923,25 @@ function rosterPickFromValue(value, role, options = {}) {
   let namedModel = false;
   let namedEffort = false;
   let prep = '';
+  let verified = '';
   for (const raw of extras) {
-    // "max: 20 min" and "until: 2026-10-24" read like "max 20 min".
-    const part = raw.replace(/^(max|until)\s*:\s*/i, '$1 ');
+    // "max: 20 min", "until: 2026-10-24", and "verified: 2026-09-30" read
+    // like "max 20 min".
+    const part = raw.replace(/^(max|until|verified)\s*:\s*/i, '$1 ');
     const backupMatch = /^backup\s+(.+)$/i.exec(part);
     const untilMatch = /^until\s+(.+)$/i.exec(part);
     const maxMatch = /^max\b/i.test(part) && !/^max$/i.test(part);
     const modelMatch = /^model\s*(?::\s*|\s+)(.+)$/i.exec(part);
     const effortMatch = /^effort\s*(?::\s*|\s+)(.+)$/i.exec(part);
     const prepMatch = /^prep\s*(?::\s*|\s+)(.+)$/i.exec(part);
-    if (prepMatch && !prep) {
+    const verifiedMatch = /^verified\s+(.+)$/i.exec(part);
+    if (verifiedMatch && !verified) {
+      // "verified 2026-09-30": the day a person last saw this model answer.
+      // The roster flags a pin whose newest proof is over 30 days old.
+      const words = verifiedMatch[1].trim();
+      verified = parseRosterUntilWords(words);
+      if (!verified) throw new Error(`"verified ${words}" is not a date; use verified 2026-09-30`);
+    } else if (prepMatch && !prep) {
       // "prep: search": that job's lead reads the task first and hands this
       // worker a trimmed brief. Whether it names this same job is checked
       // where the job is known.
@@ -946,7 +968,7 @@ function rosterPickFromValue(value, role, options = {}) {
       throw new Error('a worker line takes no backup; put the backup on the next line');
     } else if (backupMatch && !backup) {
       backup = resolveRosterWords(backupMatch[1]);
-      if (!engineCanTake(backup.engine, role)) throw new Error(`the backup ${backup.engine} cannot do ${kind} work`);
+      if (!options.anyEngine && !engineCanTake(backup.engine, role)) throw new Error(`the backup ${backup.engine} cannot do ${kind} work`);
     } else if (untilMatch && !until) {
       const words = untilMatch[1].trim();
       until = parseRosterUntilWords(words);
@@ -975,6 +997,7 @@ function rosterPickFromValue(value, role, options = {}) {
     until,
     ...(until ? {} : { never_expires: true }),
     ...(untilYearless ? { until_needs_year: untilYearless } : {}),
+    ...(verified ? { verified } : {}),
   };
 }
 
@@ -1017,6 +1040,7 @@ function rosterWorkerFromValue(value, role, options = {}) {
     until: pick.until,
     ...(pick.never_expires ? { never_expires: true } : {}),
     ...(pick.until_needs_year ? { until_needs_year: pick.until_needs_year } : {}),
+    ...(pick.verified ? { verified: pick.verified } : {}),
   };
 }
 
@@ -1065,6 +1089,7 @@ function pickWorkers(pick) {
     ...(pick.prep ? { prep: pick.prep } : {}),
     until: pick.until,
     ...(pick.never_expires ? { never_expires: true } : {}),
+    ...(pick.verified ? { verified: pick.verified } : {}),
     ...(pick.line ? { line: pick.line } : {}),
   }];
   if (pick.backup) {
@@ -1112,7 +1137,7 @@ function parseRosterMarkdown(text, file, options = {}) {
     const workers = [];
     for (const entry of lines) {
       try {
-        const worker = rosterWorkerFromValue(entry.value, ENGINE_JOBS[kind], options);
+        const worker = rosterWorkerFromValue(entry.value, ENGINE_JOBS[kind], { ...options, anyEngine: jobTakesAnyEngine(key) });
         const selfPrep = selfPrepWarning(worker, key, label);
         if (selfPrep) warn(entry, selfPrep);
         workers.push({ ...worker, line: entry.lineNumber, text: entry.raw });
@@ -1184,7 +1209,7 @@ function parseRosterMarkdown(text, file, options = {}) {
       continue;
     }
     try {
-      const pick = rosterPickFromValue(entry.value, ENGINE_JOBS[kind], options);
+      const pick = rosterPickFromValue(entry.value, ENGINE_JOBS[kind], { ...options, anyEngine: jobTakesAnyEngine(key) });
       const selfPrep = selfPrepWarning(pick, key, label);
       if (selfPrep) warn(entry, selfPrep);
       picks[key] = { ...pick, ...(builtIn ? {} : { like: kind }), file: display, line: entry.lineNumber };
@@ -1264,7 +1289,7 @@ function sessionRosterDir(options = {}) {
   if (options.sessionRosterDir) return options.sessionRosterDir;
   if (process.env.ATRIS_ROSTER_SESSIONS_DIR) return process.env.ATRIS_ROSTER_SESSIONS_DIR;
   if (options.machineRosterFile || process.env.ATRIS_MACHINE_ROSTER_PATH) return path.join(path.dirname(machineRosterFile(options)), 'sessions');
-  return path.join(os.homedir(), '.atris', 'sessions');
+  return path.join(stateHome(), '.atris', 'sessions');
 }
 
 // Like the all-projects roster: off in test runs unless a test points the
@@ -1370,6 +1395,7 @@ function workerLineText(worker) {
   if (Number(worker.max_seconds) > 0) parts.push(`max: ${rosterMaxText(worker.max_seconds).replace(/^max /, '')}`);
   if (worker.prep) parts.push(`prep: ${rosterJobLabel(worker.prep)}`);
   if (worker.until) parts.push(`until ${worker.until}`);
+  if (worker.verified) parts.push(`verified ${worker.verified}`);
   return `- ${parts.join(', ')}`;
 }
 
@@ -1531,13 +1557,14 @@ function assignedWorkerLines(key, engineName, options, context) {
   if (likeName && !likeKind) throw new Error(`unknown kind "${likeName}". use --like search, build, or review`);
   if (builtIn && likeKind && ENGINE_JOBS[likeKind] !== key) throw new Error(`${label} is a built-in job; --like is only for your own jobs`);
   const savedKind = builtIn ? '' : Object.keys(ENGINE_JOBS).find((kind) => ENGINE_JOBS[kind] === customPickRole(savedPick)) || '';
-  const kind = builtIn ? label : likeKind || inferJobKind(jobName) || savedKind;
+  const kind = builtIn ? label : likeKind || inferJobKind(jobName) || savedKind || ANY_ENGINE_JOBS[key] || '';
   if (!kind) throw new Error(`say what kind of job "${label}" is: add --like search, --like build, or --like review`);
   const role = ENGINE_JOBS[kind];
   const engineId = rosterToolName(engineName);
   const engine = registry.engines.find((entry) => entry.id === engineId);
   if (!engine) throw new Error(`unknown engine "${engineName}"`);
-  if (!engineHasRole(engine, role)) throw new Error(`${engine.id} cannot do ${builtIn ? label : `${kind} work, so it cannot take ${label}`}`);
+  const anyEngine = jobTakesAnyEngine(key);
+  if (!anyEngine && !engineHasRole(engine, role)) throw new Error(`${engine.id} cannot do ${builtIn ? label : `${kind} work, so it cannot take ${label}`}`);
   // --backup takes engine words with an optional model and effort, the
   // same as a written line: --backup "claude opus 5.5".
   const backupName = String(options.backup || '').trim();
@@ -1552,7 +1579,7 @@ function assignedWorkerLines(key, engineName, options, context) {
   }
   const backup = backupRead ? registry.engines.find((entry) => entry.id === backupRead.engine) : null;
   if (backupName && !backup) throw new Error(`unknown backup engine "${backupName}"`);
-  if (backup && !engineHasRole(backup, role)) throw new Error(`${backup.id} cannot do ${builtIn ? label : `${kind} work, so it cannot back up ${label}`}`);
+  if (backup && !anyEngine && !engineHasRole(backup, role)) throw new Error(`${backup.id} cannot do ${builtIn ? label : `${kind} work, so it cannot back up ${label}`}`);
   // No --days means the worker holds until someone changes the line.
   const days = options.days === undefined ? null : Number(options.days);
   if (days !== null && (!Number.isSafeInteger(days) || days < 1)) throw new Error('days must be a positive whole number');
@@ -1745,11 +1772,12 @@ const ROSTER_LAYERS = Object.freeze(['session', 'project', 'machine']);
 
 // A pick's workers, each with the engine it would run (model, effort, and
 // time cap pinned) or the reason it is skipped: bad line, expired, bad model,
-// or not ready (down, or it cannot do this kind of work).
-function rosterWorkerWalk(pick, role, registry, now) {
+// or not ready (down, or it cannot do this kind of work). anyEngine drops
+// the kind check for a job any engine may fill (see ANY_ENGINE_JOBS).
+function rosterWorkerWalk(pick, role, registry, now, { anyEngine = false } = {}) {
   const ready = registry.engines
     .filter((engine) => engineReadyAt(engine, now))
-    .filter((engine) => engineHasRole(engine, role));
+    .filter((engine) => anyEngine || engineHasRole(engine, role));
   return pickWorkers(pick).map((worker) => {
     if (worker.error) return { worker, skip: 'bad line', engine: null, raw: null };
     if (rosterPickExpired(worker, now)) return { worker, skip: 'expired', engine: null, raw: null };
@@ -1784,10 +1812,10 @@ function rosterWorkerWalk(pick, role, registry, now) {
 // leads; null means the next pick in line decides. A custom pick only counts
 // when its kind matches the role being resolved. team is every worker that
 // can run, lead first.
-function rosterChoiceForPick(pick, role, registry, { key, label, source, scopeText = '', now } = {}) {
+function rosterChoiceForPick(pick, role, registry, { key, label, source, scopeText = '', now, anyEngine } = {}) {
   if (!pick || !pick.engine) return null;
   if (key !== undefined && pickRoleForKey(key, pick) !== role) return null;
-  const walk = rosterWorkerWalk(pick, role, registry, now);
+  const walk = rosterWorkerWalk(pick, role, registry, now, { anyEngine: anyEngine === undefined ? jobTakesAnyEngine(key) : anyEngine });
   const leadIndex = walk.findIndex((step) => !step.skip);
   if (leadIndex === -1) return null;
   const lead = walk[leadIndex];
@@ -1942,6 +1970,55 @@ function resolveJobTeam(job, root = process.cwd(), options = {}) {
   return { job: label, key, role, source: resolved.source, lead: resolved.engine || null, team, reason: resolved.reason };
 }
 
+// Who writes YouTube notes when no roster layer names a notes job: agy on
+// its plain flash model at low effort, then haiku. Low effort is what keeps a
+// notes run near 8 seconds of writer time. Each model is a name from that
+// engine's seed catalog above. Change the default here and only here.
+const NOTES_DEFAULT_WORKERS = Object.freeze([
+  Object.freeze({ engine: 'agy', model: 'gemini-3.8-flash', effort: 'low' }),
+  Object.freeze({ engine: 'haiku', model: 'haiku', effort: null }),
+]);
+
+// The notes job answered from saved state only: the roster layers in order
+// (this session, this project, all projects), each job's workers in order
+// with the roster's own skip rules (expired, cooling, not ready), else the
+// built-in default. installed comes from the registry's saved policy, so
+// this never probes the machine on a settled registry. A roster pick with
+// no usable worker falls through to the next layer, then to the default.
+function resolveNotesJob(root = process.cwd(), options = {}) {
+  const key = 'notes';
+  const registry = readEngineRegistry(root, { now: options.now });
+  const state = options.rosterState || readRosterState(root, { now: options.now, registry });
+  const installedOf = (id) => {
+    const engine = registry.engines.find((entry) => entry.id === id);
+    return Boolean(engine && engine.installed === true);
+  };
+  const named = [];
+  for (const scope of ROSTER_LAYERS) {
+    const pick = rosterPickObject(state[scope] && state[scope].picks && state[scope].picks[key]);
+    if (!pick) continue;
+    named.push(scope);
+    const role = customPickRole(pick) || ENGINE_JOBS[ANY_ENGINE_JOBS[key]];
+    const usable = rosterWorkerWalk(pick, role, registry, options.now, { anyEngine: true }).filter((step) => !step.skip);
+    if (!usable.length) continue;
+    const [lead, ...rest] = usable.map((step) => ({
+      engine: step.engine.id,
+      model: step.engine.roster_model || null,
+      effort: step.engine.roster_effort || null,
+      installed: step.raw.installed === true,
+    }));
+    return { job: key, ...lead, backup: rest, source: 'roster', from: ROSTER_SOURCES[scope] };
+  }
+  const [lead, ...rest] = NOTES_DEFAULT_WORKERS.map((worker) => ({ ...worker, installed: installedOf(worker.engine) }));
+  return {
+    job: key,
+    ...lead,
+    backup: rest,
+    source: 'default',
+    ...(named.length ? { skipped: `the notes roster pick (${named.map((scope) => ROSTER_SOURCES[scope]).join(', ')}) has no worker ready now` } : {}),
+  };
+}
+
 // True when a roster line (not the router) decided.
 function rosterDecided(source) {
   return ROSTER_LAYERS.includes(source);
@@ -2136,6 +2213,9 @@ module.exports = {
   rosterToolLabel,
   rosterWorkerWalk,
   resolveJobTeam,
+  resolveNotesJob,
+  NOTES_DEFAULT_WORKERS,
+  jobTakesAnyEngine,
   rosterSessionKey,
   clearSessionRoster,
   NO_SESSION_MESSAGE,

package/lib/first-minute.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { stateHome } = require('./state-home');
 const { spawnSync } = require('child_process');
 const { isGenericScratchRoot } = require('./scratch-root');
 
@@ -57,8 +58,7 @@ function unixUser(env = process.env) {
 
 function loadSavedAccount() {
   try {
-    const home = process.env.HOME || os.homedir();
-    const file = path.join(home, '.atris', 'credentials.json');
+    const file = path.join(stateHome(), '.atris', 'credentials.json');
     if (!fs.existsSync(file)) return null;
     const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
     return parsed && typeof parsed === 'object' ? parsed : null;

package/lib/fleet.js

@@ -36,11 +36,13 @@ const { listWorktrees, defaultMainlineBase } = require('../commands/worktree');
 const { isConductorStatusLine } = require('./conductor-artifacts');
 const { matchLessons } = require('./lesson-preflight');
 const { sleepSync } = require('./sleep-sync');
+const { trackedSandboxPidsSync } = require('./sandbox-pids');
 const { ownerIdentity } = require('../utils/owner-identity');
 const { matchTaste } = require('./taste-lessons');
 const { buildVerifiedScoutPack, appendVerifiedScoutPack } = require('./dispatch-scout');
 const { runPrepPass, withPrepBrief, prepRecordFields } = require('./roster-prep');
 const { mapNotesPath } = require('./map-refs');
+const { SHARED_BRIEF_RULES } = require('./brief-rules');
 const {
   applySecretGrantEnvironment,
   buildGatewaySupervisorScript,
@@ -117,7 +119,7 @@ function buildFleetPrompt(task, { worktreePath, yolo = false } = {}) {
     mapNotesPath(worktreePath || process.cwd())
       ? '- Read atris/MAP.md first to locate the code, then atris/refs/MAP-NOTES.md for exact file:line refs; never guess file locations.'
       : '- Read atris/MAP.md first to locate the code; never guess file locations.',
-    '- Keep one concern per PR; split anything larger into separate PRs because git history guides future agents and small PRs are cheap to revert and bisect.',
+    ...SHARED_BRIEF_RULES,
     '- Run git status first. Stage ONLY files you changed. Never revert or touch files another agent modified.',
     '- Include or update a focused regression test; run it with npm run test:fast && node --test <focused files> before committing.',
     `- ${commitRule}`,
@@ -284,31 +286,11 @@ function buildEngineCommand(engineName, promptFile, { yolo = false, sealed = fal
 }
 
 function trackedSandboxPids(stateFile, leaseFile) {
-  const pids = new Set();
   let state = {};
   try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch {}
   const pgid = Number(state.pgid);
-  if (Number.isInteger(pgid) && pgid > 0) {
-    const grouped = spawnSync('/usr/bin/pgrep', ['-g', String(pgid)], { encoding: 'utf8' });
-    for (const value of String(grouped.stdout || '').trim().split(/\s+/)) {
-      const pid = Number(value);
-      if (Number.isInteger(pid) && pid > 0) pids.add(pid);
-    }
-  }
-  const leased = spawnSync('/usr/sbin/lsof', ['-t', leaseFile], { encoding: 'utf8' });
-  for (const value of String(leased.stdout || '').trim().split(/\s+/)) {
-    const pid = Number(value);
-    if (Number.isInteger(pid) && pid > 0) pids.add(pid);
-  }
-  if (state.cwd) {
-    const rooted = spawnSync('/usr/sbin/lsof', ['-a', '-d', 'cwd', '+D', String(state.cwd), '-t'], { encoding: 'utf8' });
-    for (const value of String(rooted.stdout || '').trim().split(/\s+/)) {
-      const pid = Number(value);
-      if (Number.isInteger(pid) && pid > 0) pids.add(pid);
-    }
-  }
-  pids.delete(process.pid);
-  return { pgid, pids: [...pids] };
+  const pids = trackedSandboxPidsSync({ pgid, leaseFile, cwd: state.cwd ? String(state.cwd) : '' });
+  return { pgid, pids };
 }
 
 function terminateTrackedSandbox(stateFile, leaseFile) {
@@ -480,6 +462,7 @@ function runInReapedProcessGroup(executable, args, options, controlDir, statusFi
       "'use strict';",
       "const fs = require('node:fs');",
       "const { spawn, spawnSync } = require('node:child_process');",
+      `const sandboxPids = require(${JSON.stringify(require.resolve('./sandbox-pids'))});`,
       "const [stateFile, leaseFile, statusFile, executable, ...args] = process.argv.slice(2);",
       "const leaseFd = fs.openSync(leaseFile, 'w', 0o600);",
       "const statusFd = fs.openSync(statusFile, 'w', 0o600);",
@@ -489,18 +472,7 @@ function runInReapedProcessGroup(executable, args, options, controlDir, statusFi
       "fs.writeFileSync(stateFile, JSON.stringify({ pgid: child.pid, cwd: process.cwd() }) + '\\n', { mode: 0o600 });",
       "let stopping = false;",
       "const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));",
-      "function trackedPids() {",
-      "  const pids = new Set();",
-      "  for (const [bin, argv] of [['/usr/bin/pgrep', ['-g', String(child.pid)]], ['/usr/sbin/lsof', ['-t', leaseFile]], ['/usr/sbin/lsof', ['-a', '-d', 'cwd', '+D', process.cwd(), '-t']]]) {",
-      "    const found = spawnSync(bin, argv, { encoding: 'utf8' });",
-      "    for (const value of String(found.stdout || '').trim().split(/\\s+/)) {",
-      "      const pid = Number(value);",
-      "      if (Number.isInteger(pid) && pid > 0) pids.add(pid);",
-      "    }",
-      "  }",
-      "  pids.delete(process.pid);",
-      "  return [...pids];",
-      "}",
+      "const trackedPids = () => sandboxPids.trackedSandboxPids({ pgid: child.pid, leaseFile, cwd: process.cwd() });",
       "async function stop(code) {",
       "  if (stopping) return;",
       "  stopping = true;",
@@ -509,7 +481,7 @@ function runInReapedProcessGroup(executable, args, options, controlDir, statusFi
       "  }",
       "  for (const [signal, delay] of [['SIGTERM', 100], ['SIGKILL', 100], ['SIGKILL', 100]]) {",
       "    try { process.kill(-child.pid, signal); } catch {}",
-      "    for (const pid of trackedPids()) { try { process.kill(pid, signal); } catch {} }",
+      "    for (const pid of await trackedPids()) { try { process.kill(pid, signal); } catch {} }",
       "    await wait(delay);",
       "  }",
       "  let exitCode = Number.isInteger(code) ? code : 128;",

package/lib/git-spawn.js

@@ -4,8 +4,11 @@ const { spawnSync } = require('child_process');
 
 // One synchronous git runner for commands that shell out to git.
 // check: true throws on a non-zero exit; check: false hands back the raw result.
-function runGit(args, { cwd = process.cwd(), check = true, maxBuffer } = {}) {
-  const result = spawnSync('git', args, { cwd, encoding: 'utf8', ...(maxBuffer ? { maxBuffer } : {}) });
+// input, when given, is written to git's stdin (for --stdin batch reads).
+function runGit(args, { cwd = process.cwd(), check = true, maxBuffer, input } = {}) {
+  const result = spawnSync('git', args, {
+    cwd, encoding: 'utf8', ...(maxBuffer ? { maxBuffer } : {}), ...(input !== undefined ? { input } : {}),
+  });
   if (check && result.status !== 0) {
     throw new Error(`git ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}`);
   }

package/lib/ignored-cache.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Speed caches that must never be committed. They live in .atris/cache, a
+// folder that carries its own .gitignore of `*`, so a project with no ignore
+// rule for .atris still never stages them with `git add -A`. Caches are only
+// kept in folders that already have .atris; elsewhere nothing is written.
+
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_DIR = path.join('.atris', 'cache');
+
+function cacheEnabled(root) {
+  try {
+    return fs.statSync(path.join(root, '.atris')).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function cachePath(root, name) {
+  return path.join(root, CACHE_DIR, name);
+}
+
+// The parsed cache file, or null when it is missing or unreadable.
+function readCacheJson(root, name) {
+  try {
+    return JSON.parse(fs.readFileSync(cachePath(root, name), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Returns false when the write failed; a cache is only a speedup.
+function writeCacheJson(root, name, value) {
+  const dir = path.join(root, CACHE_DIR);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const ignore = path.join(dir, '.gitignore');
+    if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n');
+    const file = cachePath(root, name);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value)}\n`);
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { CACHE_DIR, cacheEnabled, cachePath, readCacheJson, writeCacheJson };

package/lib/known-commands.js

@@ -4,7 +4,7 @@ const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'work
                        'activate', '_activate', 'agent', 'team', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'taste', 'teach', 'plugin', 'experiments', 'bench', 'router', 'tree', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube', 'x-search',
                        'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'decide', 'agents', 'probe', 'worktree', 'land', 'caretaker', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
-                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'topup', 'buy', 'transactions', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'topup', 'buy', 'transactions', 'hire', 'hires', 'mail', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'pack', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'fleet-report', 'loops', 'self-improve', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'playbook', 'feed', 'brief', 'social', 'host', 'people', 'follow', 'unfollow', 'friends', 'msg', 'inbox', 'invite', 'join', 'rsi'];
 
 // Damerau-Levenshtein edit distance between two short strings. Counts an

package/lib/manifest.js

@@ -1,7 +1,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
+const { stateHome } = require('./state-home');
 const { computeContentHash } = require('./journal');
 
 /**
@@ -9,7 +9,7 @@ const { computeContentHash } = require('./journal');
  * Stored at ~/.atris/businesses/{slug}/manifest.json
  */
 function getManifestPath(slug) {
-  return path.join(os.homedir(), '.atris', 'businesses', slug, 'manifest.json');
+  return path.join(stateHome(), '.atris', 'businesses', slug, 'manifest.json');
 }
 
 /**

package/lib/map-refs.js

@@ -6,8 +6,10 @@
 // A name elsewhere in the sentence never binds: map sentences often name a helper
 // the ref does not point at, and binding it would move the ref to the wrong place.
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const ignoredCache = require('./ignored-cache');
 
 const WINDOW = 3;
 const IDENT = /^[A-Za-z_$][\w$]*$/;
@@ -123,6 +125,14 @@ function classify(ref, file) {
 }
 
 function checkMapRefs(root, mapText) {
+  const parsed = parseRefs(mapText);
+  const results = classifyRefs(root, parsed);
+  return summarize(parsed.map((ref, i) => ({ ...ref, ...results[i] })));
+}
+
+// What the code says about each parsed ref: its status, plus the line it moved
+// to or why it is missing. Each file a ref points at is read once.
+function classifyRefs(root, parsed) {
   const cache = new Map();
   const linesOf = file => {
     if (!cache.has(file)) {
@@ -144,11 +154,10 @@ function checkMapRefs(root, mapText) {
     }
     return cache.get(file);
   };
-  const refs = parseRefs(mapText).map(ref => {
+  return parsed.map(ref => {
     const file = linesOf(ref.path);
-    return { ...ref, ...(file ? classify(ref, file) : { status: 'missing-file' }) };
+    return file ? classify(ref, file) : { status: 'missing-file' };
   });
-  return summarize(refs);
 }
 
 function summarize(refs) {
@@ -197,13 +206,70 @@ function existingMapDocs(root) {
   });
 }
 
+// Boot scores the docs every session, and checking every ref means reading
+// every file the map points at (megabytes on this repo). The result for each
+// map file is saved in the ignored .atris/cache and reused only while the map
+// text and the stat stamp of every file it points at are unchanged.
+const REFS_CACHE_NAME = 'map-refs.json';
+
+// Size, modified time, change time, and inode of a file a ref points at; null
+// when it is not there. Change time moves on every write and cannot be set
+// back by hand, so an edit that keeps size and modified time still misses.
+function fileStamp(full) {
+  try {
+    const stat = fs.statSync(full);
+    return `${stat.isFile() ? 'f' : 'o'}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.ino}`;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+function refsCacheKey(root, text, parsed) {
+  const files = [...new Set(parsed.map(ref => ref.path))];
+  const stamps = files.map(file => [file, fileStamp(path.resolve(root, file))]);
+  return crypto.createHash('sha1').update(JSON.stringify([text, stamps])).digest('hex');
+}
+
+function loadRefsCache(root) {
+  const cache = { root, docs: {}, dirty: false, writable: ignoredCache.cacheEnabled(root) };
+  if (!cache.writable) return cache;
+  const parsed = ignoredCache.readCacheJson(root, REFS_CACHE_NAME);
+  if (parsed && parsed.version === 1 && parsed.docs && typeof parsed.docs === 'object') cache.docs = parsed.docs;
+  return cache;
+}
+
+function saveRefsCache(cache) {
+  if (!cache.writable || !cache.dirty) return;
+  ignoredCache.writeCacheJson(cache.root, REFS_CACHE_NAME, { version: 1, docs: cache.docs });
+}
+
+function cachedMapRefs(root, doc, text, cache) {
+  const parsed = parseRefs(text);
+  const key = cache.writable ? refsCacheKey(root, text, parsed) : '';
+  const hit = key && cache.docs[doc];
+  let results;
+  if (hit && hit.key === key && Array.isArray(hit.results) && hit.results.length === parsed.length) {
+    results = hit.results;
+  } else {
+    results = classifyRefs(root, parsed);
+    if (key) {
+      cache.docs[doc] = { key, results };
+      cache.dirty = true;
+    }
+  }
+  return parsed.map((ref, i) => ({ ...ref, ...results[i] }));
+}
+
 // mapText is the already-read atris/MAP.md, so boot does not read it twice.
 function checkMapDocs(root, mapText) {
+  const cache = loadRefsCache(root);
   const refs = existingMapDocs(root).flatMap(doc => {
     const text = doc === MAP_REF_DOCS[0] && typeof mapText === 'string'
       ? mapText : fs.readFileSync(path.resolve(root, doc), 'utf8');
-    return checkMapRefs(root, text).refs.map(ref => ({ doc, ...ref }));
+    return cachedMapRefs(root, doc, text, cache).map(ref => ({ doc, ...ref }));
   });
+  saveRefsCache(cache);
   return summarize(refs);
 }