atris 3.63.0 → 3.64.0

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);
 }
 

package/lib/pack-capabilities.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { stateHome } = require('./state-home');
 const dns = require('dns').promises;
 const net = require('net');
 const { randomUUID, createHash } = require('crypto');
@@ -250,7 +251,7 @@ function buildClaudeCapabilityArgs(policy, options = {}) {
 function receiptDirectory(options = {}) {
   if (options.receiptDir) return path.resolve(options.receiptDir);
   if (process.env.ATRIS_PACK_RUNS_DIR) return path.resolve(process.env.ATRIS_PACK_RUNS_DIR);
-  return path.join(os.homedir(), '.atris', 'runs', 'packs');
+  return path.join(stateHome(), '.atris', 'runs', 'packs');
 }
 
 function appendReceiptEvent(eventsPath, event) {

package/lib/permission-grants.js

@@ -8,8 +8,8 @@
 // Design brief: atris/designs/permission-grants-cli-831.md
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
+const { stateHome } = require('./state-home');
 const crypto = require('crypto');
 
 const GRANTS_SCHEMA = 'atris.permission_grants.v1';
@@ -39,7 +39,7 @@ const NEVER_GRANTABLE = [
 
 function grantsFilePath() {
   return process.env.ATRIS_PERMISSION_GRANTS_FILE
-    || path.join(os.homedir(), '.atris', 'permission-grants.json');
+    || path.join(stateHome(), '.atris', 'permission-grants.json');
 }
 
 function parseArgv(command) {

package/lib/pulse.js

@@ -14,8 +14,8 @@
 
 const fs = require('fs');
 const crypto = require('crypto');
-const os = require('os');
 const path = require('path');
+const { stateHome: userStateHome } = require('./state-home');
 const { DEFAULT_CLAUDE_RUNNER_MODEL } = require('./runner-command');
 const { readOrbScorecard } = require('./orb-scorecard');
 
@@ -69,7 +69,7 @@ function pulseRepoSlug(root) {
   return `${base}-${hash}`;
 }
 
-function pulseStateHome(root, homeDir = os.homedir()) {
+function pulseStateHome(root, homeDir = userStateHome()) {
   return path.join(homeDir, '.atris', 'overnight', `pulse-${pulseRepoSlug(root)}`);
 }
 
@@ -77,7 +77,7 @@ function pulseMarker(root) {
   return `ATRIS_PULSE_${pulseRepoSlug(root).toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
 }
 
-function legacyPulseStateHome(homeDir = os.homedir()) {
+function legacyPulseStateHome(homeDir = userStateHome()) {
   return path.join(homeDir, '.atris', 'overnight', LEGACY_STATE_DIRNAME);
 }
 
@@ -92,7 +92,7 @@ function readTickScriptRoot(stateHome) {
   }
 }
 
-function legacyPulseStateMatchesRoot(root, homeDir = os.homedir()) {
+function legacyPulseStateMatchesRoot(root, homeDir = userStateHome()) {
   const legacyStateHome = legacyPulseStateHome(homeDir);
   const scriptRoot = readTickScriptRoot(legacyStateHome);
   if (!scriptRoot) return false;
@@ -100,7 +100,7 @@ function legacyPulseStateMatchesRoot(root, homeDir = os.homedir()) {
 }
 
 function resolvePulseSlot(root, options = {}) {
-  const homeDir = options.homeDir || os.homedir();
+  const homeDir = options.homeDir || userStateHome();
   const stateHome = pulseStateHome(root, homeDir);
   const marker = pulseMarker(root);
   const legacyStateHome = legacyPulseStateHome(homeDir);

package/lib/roster-runs.js

@@ -29,14 +29,25 @@ const TAIL_BYTES = 512 * 1024;
 const RUNS_ROTATE_BYTES = 2 * 1024 * 1024;
 const JOB_ALIASES = Object.freeze({ navigator: 'search', executor: 'build', builder: 'build', validator: 'review', reviewer: 'review' });
 
+// The record belongs to the project, not to the scratch checkout a run
+// happened in. A fleet build, a mission, or an ask run inside a git worktree
+// writes to the main checkout, so the history survives when the worktree is
+// reaped and `atris engine roster --runs` reads the same file from either
+// place. Same pointer-file lookup the roster and member cards use.
+function runsRoot(root = process.cwd()) {
+  const { mainCheckoutRoot } = require('./engine-registry');
+  const main = mainCheckoutRoot(root);
+  return main && fs.existsSync(main) ? main : root;
+}
+
 function rosterRunsPath(root = process.cwd()) {
-  return path.join(root, RUNS_FILE);
+  return path.join(runsRoot(root), RUNS_FILE);
 }
 
 // Rotated logs, oldest name first; the stamp in each name makes name order
 // the order they were renamed in.
 function rotatedRunsPaths(root = process.cwd()) {
-  const dir = path.dirname(path.join(root, RUNS_FILE));
+  const dir = path.dirname(rosterRunsPath(root));
   let names;
   try {
     names = fs.readdirSync(dir);

package/lib/runner-command.js

@@ -87,9 +87,11 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
   }),
   // No hard pin: a pinned grok-4.6 went stale when the grok CLI moved its
   // own default to grok-4.7-build-fast, so an unpinned run rides the CLI.
+  // Grok runs only xAI models, so a claude model name never reaches it.
   grok: Object.freeze({
     bin: 'grok',
     model: '',
+    ownModelsOnly: true,
     commandTemplate: '{bin} --always-approve {pinnedModelFlag} {pinnedEffortFlag} -p {prompt}',
     effortFlag: '--reasoning-effort',
     efforts: Object.freeze(['low', 'medium', 'high']),
@@ -213,6 +215,17 @@ function resolvePinnedRunnerModel(mission) {
   return explicit || runnerProfileValue('model');
 }
 
+// The own-models-only engine a runner bin launches ("codex", "/opt/bin/grok"),
+// or '' when the program is not one of them.
+function ownModelsOnlyEngineForBin(bin) {
+  const name = String(bin || '').split(/[\\/]/).pop().replace(/\.exe$/i, '').toLowerCase();
+  if (!name) return '';
+  return Object.keys(RUNNER_PROFILE_DEFS).find((id) => {
+    const def = RUNNER_PROFILE_DEFS[id];
+    return def.ownModelsOnly && def.bin === name;
+  }) || '';
+}
+
 // The model an engine is launched with. An engine that runs only its own
 // vendor's models drops a claude model name (a mission's stored default, a
 // claude env pin) and rides its own default instead.
@@ -321,12 +334,13 @@ function buildRunnerCommand({ promptFile, allowedTools, model, effort } = {}) {
   }
   const resolved = resolveClaudeRunnerModel({ model });
   const template = resolveClaudeRunnerCommandTemplate();
+  // Both the profile and the program that actually runs count: a runner bin
+  // named codex or grok (or a path ending in one) is that engine under any
+  // profile, with or without a template.
+  const profile = resolveRunnerProfileName();
+  const binEngine = ownModelsOnlyEngineForBin(resolveClaudeRunnerBin());
+  const modelFor = (value) => runnerModelFor(binEngine, runnerModelFor(profile, value));
   if (template) {
-    // Both the profile and the program that actually runs count: a runner
-    // bin named codex (or a path ending in it) is codex under any profile.
-    const profile = resolveRunnerProfileName();
-    const binName = String(resolveClaudeRunnerBin()).split(/[\\/]/).pop();
-    const modelFor = (value) => runnerModelFor(binName, runnerModelFor(profile, value));
     return renderRunnerCommandTemplate(template, {
       promptFile,
       allowedTools,
@@ -336,7 +350,9 @@ function buildRunnerCommand({ promptFile, allowedTools, model, effort } = {}) {
     });
   }
   const safePath = String(promptFile).replace(/'/g, "'\\''");
-  let cmd = `${shellWord(resolveClaudeRunnerBin())} -p "$(cat '${safePath}')" --model ${shellWord(resolved)}`;
+  const launchModel = modelFor(resolved);
+  let cmd = `${shellWord(resolveClaudeRunnerBin())} -p "$(cat '${safePath}')"`;
+  if (launchModel) cmd += ` --model ${shellWord(launchModel)}`;
   const effortFlag = runnerEffortFlag(effort);
   if (effortFlag) cmd += ` ${effortFlag}`;
   if (allowedTools) {

package/lib/sandbox-pids.js

@@ -0,0 +1,113 @@
+'use strict';
+
+// Find every process a sealed run may have left behind: members of its
+// process group, holders of its lease file, and anything whose cwd sits in its
+// worktree. Each lsof scan walks the whole process table (about 300 to 500ms on
+// a busy mac), and the reaper repeats the sweep six times per sealed run, so
+// the three scans run side by side instead of one after another. They run from
+// "/" so a scan never finds its own siblings through the worktree cwd.
+
+const { spawn, spawnSync } = require('node:child_process');
+
+function sandboxPidQueries({ pgid, leaseFile, cwd }) {
+  const queries = [];
+  const group = Number(pgid);
+  if (Number.isInteger(group) && group > 0) queries.push(['/usr/bin/pgrep', ['-g', String(group)]]);
+  queries.push(['/usr/sbin/lsof', ['-t', String(leaseFile)]]);
+  if (cwd) queries.push(['/usr/sbin/lsof', ['-a', '-d', 'cwd', '+D', String(cwd), '-t']]);
+  return queries;
+}
+
+function collectPids(outputs, excluded) {
+  const pids = new Set();
+  for (const output of outputs) {
+    for (const value of String(output || '').trim().split(/\s+/)) {
+      const pid = Number(value);
+      if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+    }
+  }
+  for (const pid of excluded) pids.delete(pid);
+  return [...pids];
+}
+
+// pgrep and lsof both exit 1 when nothing matches. Anything else (another
+// status, a signal, a spawn error, no stdout pipe) means the scan did not run,
+// which is not the same as finding nothing.
+function runScan(bin, argv) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let settled = false;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve({ ok, stdout: ok ? stdout : '' });
+    };
+    let child;
+    try {
+      child = spawn(bin, argv, { cwd: '/', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch {
+      finish(false);
+      return;
+    }
+    child.once('error', () => finish(false));
+    if (!child.stdout) {
+      finish(false);
+      return;
+    }
+    child.stdout.on('error', () => finish(false));
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.once('close', (status, signal) => finish(!signal && (status === 0 || status === 1)));
+  });
+}
+
+function sequentialOutputs(query) {
+  return sandboxPidQueries(query).map(([bin, argv]) => {
+    try {
+      return spawnSync(bin, argv, { cwd: '/', encoding: 'utf8' }).stdout;
+    } catch {
+      return '';
+    }
+  });
+}
+
+// If any side-by-side scan fails, run the whole sweep again one by one and
+// keep every pid either pass saw.
+async function trackedSandboxPids(query, { excluded = [process.pid], scan = runScan } = {}) {
+  const scans = await Promise.all(sandboxPidQueries(query).map(([bin, argv]) => scan(bin, argv)));
+  const outputs = scans.map((result) => result.stdout);
+  if (scans.some((result) => !result.ok)) outputs.push(...sequentialOutputs(query));
+  return collectPids(outputs, excluded);
+}
+
+// Synchronous callers get the same parallel sweep through one short node
+// helper. If the helper cannot answer, fall back to the one-by-one sweep so
+// the reaper never runs blind.
+function trackedSandboxPidsSync(query) {
+  const excluded = [process.pid];
+  const helper = spawnSync(process.execPath, [__filename, JSON.stringify(query)], {
+    cwd: '/',
+    encoding: 'utf8',
+  });
+  if (helper.status === 0) {
+    try {
+      const parsed = JSON.parse(helper.stdout);
+      if (Array.isArray(parsed)) {
+        return collectPids([parsed.join(' ')], [...excluded, helper.pid]);
+      }
+    } catch {}
+  }
+  return collectPids(sequentialOutputs(query), excluded);
+}
+
+if (require.main === module) {
+  trackedSandboxPids(JSON.parse(process.argv[2] || '{}'))
+    .then((pids) => { process.stdout.write(JSON.stringify(pids) + '\n'); })
+    .catch(() => { process.exitCode = 1; });
+}
+
+module.exports = {
+  runScan,
+  trackedSandboxPids,
+  trackedSandboxPidsSync,
+};

package/lib/secret-gateway.js

@@ -393,6 +393,7 @@ function buildGatewaySupervisorScript(gatewayModulePath) {
     "const fs = require('node:fs');",
     "const { spawn, spawnSync } = require('node:child_process');",
     `const sg = require(${JSON.stringify(gatewayModulePath)});`,
+    `const sandboxPids = require(${JSON.stringify(require.resolve('./sandbox-pids'))});`,
     "const [exitFile, stateFile, leaseFile, statusFile, executable, ...args] = process.argv.slice(2);",
     "const leaseFd = fs.openSync(leaseFile, 'w', 0o600);",
     "const statusFd = fs.openSync(statusFile, 'w', 0o600);",
@@ -413,18 +414,7 @@ function buildGatewaySupervisorScript(gatewayModulePath) {
     "  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;',
@@ -433,7 +423,7 @@ function buildGatewaySupervisorScript(gatewayModulePath) {
     '    }',
     "    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);',
     '    }',
     '    try { await gateway.close(); } catch {}',

package/lib/state-home.js

@@ -0,0 +1,106 @@
+// Where ~/.atris state lives, with a fence for test runs.
+//
+// The node test runner sets NODE_TEST_CONTEXT in every test-file process, and
+// CLI subprocesses spawned by tests inherit it. A test that forgets to point
+// ATRIS_TASKS_DB or HOME at a temp dir used to write the user's real task
+// database. Under the test runner, when HOME is still the real user home, we
+// hand back a throwaway home instead, so forgetting the override is safe.
+//
+// Explicit choices still win: a temp HOME keeps its own .atris, and
+// ATRIS_TEST_REAL_HOME=1 opts a test back into the real home on purpose.
+// Outside the test runner nothing changes.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function normalizedPath(p) {
+  let resolved;
+  try { resolved = fs.realpathSync(p); } catch (_) { resolved = path.resolve(p); }
+  const foldCase = process.platform === 'darwin' || process.platform === 'win32';
+  return foldCase ? resolved.toLowerCase() : resolved;
+}
+
+// Same folder under any spelling: symlinks, letter case, and macOS firmlinks
+// (the home folder seen through /System/Volumes/Data), which realpath leaves
+// alone but which share the device and inode of the usual path.
+function samePath(a, b) {
+  if (!a || !b) return false;
+  if (normalizedPath(a) === normalizedPath(b)) return true;
+  try {
+    const sa = fs.statSync(a);
+    const sb = fs.statSync(b);
+    return sa.ino !== 0 && sa.dev === sb.dev && sa.ino === sb.ino;
+  } catch (_) {
+    return false;
+  }
+}
+
+// The account's home from the user database, not HOME. Read once per
+// process: it cannot change while we run, and callers resolve paths often.
+let realUserHome;
+function realHomeOnce() {
+  if (realUserHome === undefined) {
+    try { realUserHome = os.userInfo().homedir || null; } catch (_) { realUserHome = null; }
+  }
+  return realUserHome;
+}
+
+function protectedHomes(env) {
+  const homes = [];
+  if (realHomeOnce()) homes.push(realHomeOnce());
+  // Test seam that can only widen the fence: marks one more folder as a
+  // real home, so a test can prove the fence without touching the real one.
+  if (env.ATRIS_TEST_PROTECTED_HOME) homes.push(env.ATRIS_TEST_PROTECTED_HOME);
+  return homes;
+}
+
+realHomeOnce();
+
+function underTest(env) {
+  return Boolean(env.NODE_TEST_CONTEXT || env.ATRIS_TEST_STATE_DIR);
+}
+
+// os.homedir() follows HOME and any test mock of it; a caller-supplied env
+// with its own HOME (like a spawned child's env) takes that instead.
+function currentHome(env) {
+  return (env !== process.env && env.HOME) || os.homedir();
+}
+
+function testStateFenced(env = process.env) {
+  if (env.ATRIS_TEST_REAL_HOME === '1') return false;
+  if (!underTest(env)) return false;
+  const home = currentHome(env);
+  const real = protectedHomes(env);
+  // If we cannot tell who the real user is, assume HOME is real.
+  if (real.length === 0) return true;
+  return real.some((h) => samePath(home, h));
+}
+
+// One fence folder per OS user, shared by every test run. Tests that need
+// isolation already set their own paths; tests that did not were sharing the
+// real db, so sharing one throwaway db keeps that behavior without the damage.
+// The choice is exported through the env so children that lose
+// NODE_TEST_CONTEXT still stay fenced.
+function fenceDir(env) {
+  if (env.ATRIS_TEST_STATE_DIR) return env.ATRIS_TEST_STATE_DIR;
+  let user = typeof process.getuid === 'function' ? process.getuid() : null;
+  if (user === null) {
+    try { user = os.userInfo().username; } catch (_) { user = 'user'; }
+  }
+  const dir = path.join(os.tmpdir(), `atris-test-home-${user}`);
+  if (env === process.env) process.env.ATRIS_TEST_STATE_DIR = dir;
+  return dir;
+}
+
+// The folder that holds .atris: the real home normally, a throwaway one when
+// a test run would otherwise reach the real home.
+function stateHome(env = process.env) {
+  if (testStateFenced(env)) return fenceDir(env);
+  return currentHome(env);
+}
+
+function atrisHome(env = process.env) {
+  return path.join(stateHome(env), '.atris');
+}
+
+module.exports = { stateHome, atrisHome, testStateFenced };

package/lib/task-db.js

@@ -24,7 +24,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const crypto = require('crypto');
 const { DatabaseSync } = require('node:sqlite');
 const reviewIntegrity = require('./review-integrity');
@@ -35,8 +34,8 @@ const { parseVerifyCommand } = require('./auto-accept-certified');
 const { taskExplanation } = require('./task-explanation');
 const { treeHashFor } = require('./tree-hash');
 const { sleepSync } = require('./sleep-sync');
+const { atrisHome } = require('./state-home');
 
-const DEFAULT_DB_PATH = path.join(os.homedir(), '.atris', 'tasks.db');
 const TASK_EPISODES_FILE = path.join('.atris', 'state', 'task_episodes.jsonl');
 const TODO_RENDER_DONE_LIMIT = 8;
 const TODO_RENDER_FAILED_LIMIT = 12;
@@ -188,8 +187,10 @@ CREATE UNIQUE INDEX IF NOT EXISTS uq_tasks_source ON tasks(workspace_root, sourc
 let _cachedDb = null;
 let _cachedPath = null;
 
+// Default is ~/.atris/tasks.db, resolved per call so a test run that forgets
+// ATRIS_TASKS_DB lands in a throwaway db instead of the real one.
 function getDbPath() {
-  return process.env.ATRIS_TASKS_DB || DEFAULT_DB_PATH;
+  return process.env.ATRIS_TASKS_DB || path.join(atrisHome(), 'tasks.db');
 }
 
 function open(dbPath) {