atris 3.58.7 → 3.59.0

package/commands/mission.js

@@ -13,6 +13,7 @@ const {
   printCliJson,
 } = require('../lib/cli-json');
 const escapeRegExp = require('../lib/escape-regexp');
+const { sleepSync } = require('../lib/sleep-sync');
 const {
   appendBriefRecord,
   stampBriefOutcome,
@@ -20,6 +21,7 @@ const {
 } = require('../lib/brief-ledger');
 const {
   resolveClaudeRunnerModel,
+  resolvePinnedRunnerModel,
   resolveClaudeRunnerBin,
   resolveClaudeRunnerCommandTemplate,
   buildRunnerCommand,
@@ -384,13 +386,59 @@ function resolveMissionRunnerSelection(value, options = {}) {
   exitMissionError(`Unknown ${noun} "${raw}". ${knownMissionRunnerText()}.`, 2, asJson);
 }
 
-function resolveMissionTickRunner(mission, root = process.cwd()) {
+// The roster line's effort and time cap for this tick, when it sets them.
+function rosterTickPins(engine) {
+  return {
+    ...(engine && engine.roster_effort ? { roster_effort: engine.roster_effort } : {}),
+    ...(engine && engine.roster_max_seconds ? { roster_max_seconds: engine.roster_max_seconds } : {}),
+  };
+}
+
+// A tick's time limit: the time left on the mission, capped by the roster
+// line's "max 20 min" when it sets one, else by the default tick cap.
+function missionTickTimeoutMs(mission, remainingMs) {
+  const cap = Number(mission && mission.roster_max_seconds) > 0
+    ? Number(mission.roster_max_seconds) * 1000
+    : MISSION_RUN_DEFAULTS.claudeTimeoutMs;
+  return clampTimeoutMs(remainingMs, cap);
+}
+
+function resolveMissionTickRunner(mission, root = process.cwd(), options = {}) {
   if (String(mission && mission.runner || '').trim().toLowerCase() !== MISSION_AUTO_RUNNER) {
     return { mission, engine_id: null, requested_engine: null, engine_fallback_reason: null };
   }
-  const resolved = resolveEngineForRoleWithPreference('executor', root, mission.preferred_engine);
+  // A mission owned by a team member runs on that member's roster pick. An
+  // explicit preferred engine (or a run's --engine) still wins, and with no
+  // roster line behind the member, routing stays exactly as it was.
+  if (!String(mission.preferred_engine || '').trim() && mission.owner) {
+    const { memberRosterEngine } = require('../lib/member-engine');
+    const member = memberRosterEngine(mission.owner, root, options);
+    if (member) {
+      if (process.env.ATRIS_ROUTER_EXPLAIN !== '0') console.error(member.reason);
+      return {
+        mission: {
+          ...mission,
+          runner: member.engine.id,
+          runner_kind: 'engine',
+          ...(!mission.model && member.model ? { model: member.model } : {}),
+          ...rosterTickPins(member.engine),
+        },
+        engine_id: member.engine.id,
+        requested_engine: null,
+        engine_fallback_reason: null,
+        member_engine_reason: member.reason,
+      };
+    }
+  }
+  const resolved = resolveEngineForRoleWithPreference('executor', root, mission.preferred_engine, options);
   return {
-    mission: resolved.engine ? { ...mission, runner: resolved.engine.id, runner_kind: 'engine' } : mission,
+    mission: resolved.engine ? {
+      ...mission,
+      runner: resolved.engine.id,
+      runner_kind: 'engine',
+      ...(!mission.model && resolved.engine.roster_model ? { model: resolved.engine.roster_model } : {}),
+      ...rosterTickPins(resolved.engine),
+    } : mission,
     engine_id: resolved.engine ? resolved.engine.id : null,
     requested_engine: resolved.requested_engine,
     engine_fallback_reason: resolved.engine_fallback_reason,
@@ -443,6 +491,20 @@ function applyMissionRunnerProfile(runner) {
   };
 }
 
+// Claude-family engines share the claude CLI, so they keep the resolved
+// default model pin. Every other engine's CLI rejects a claude model name, so
+// it only ever takes an explicit pin (the mission's model or the roster
+// line's); '' lets the engine ride its own default.
+const CLAUDE_FAMILY_RUNNER_ENGINES = new Set(['claude', 'fable', 'haiku']);
+
+function resolveMissionTickRunnerModel(mission) {
+  const engine = canonicalEngineName(mission && mission.runner);
+  if (!engine || CLAUDE_FAMILY_RUNNER_ENGINES.has(engine)) {
+    return resolveClaudeRunnerModel(mission);
+  }
+  return resolvePinnedRunnerModel(mission);
+}
+
 function exitMissionError(message, code = 1, asJson = false) {
   if (asJson) {
     printCliJson(
@@ -3568,8 +3630,8 @@ function readTasteReviewHistory(root, limit = 4) {
 
 function missionTasteMemorySignals(text) {
   const definitions = [
-    ['plain_language', 'Keshav asks for plain English', /\b(plain|jargon|feynman|understand|simple|clarify|clarity)\b/i],
-    ['proof_gate', 'Keshav wants proof before accept', /\b(proof|receipt|verify|verified|checked|tested|accept|approval)\b/i],
+    ['plain_language', 'the operator asks for plain English', /\b(plain|jargon|feynman|understand|simple|clarify|clarity)\b/i],
+    ['proof_gate', 'the operator wants proof before accept', /\b(proof|receipt|verify|verified|checked|tested|accept|approval)\b/i],
     ['runway_revenue', 'runway pushes user or revenue work', /\b(runway|revenue|cash|user|users|customer|demo|adoption|retention)\b/i],
     ['technical_ambition', 'technical advancement still matters', /\b(technical|homerun|research|runtime|architecture|model|benchmark|agent)\b/i],
     ['trust_boundary', 'trust and approval boundaries matter', /\b(security|safe|safety|trust|privacy|approval|permission|gmail|email|connector)\b/i],
@@ -3668,9 +3730,9 @@ function missionPlainTaskPreview(title) {
 function missionTasteMemoryReason(tasteMemory, signals) {
   const candidateIds = new Set((signals || []).map((signal) => signal.id));
   const memoryIds = new Set((tasteMemory?.signals || []).map((signal) => signal.id));
-  if (memoryIds.has('runway_revenue') && candidateIds.has('users_revenue')) return 'Keshav has been steering toward user/revenue proof because runway is tight.';
-  if (memoryIds.has('plain_language') && candidateIds.has('usability')) return 'Keshav keeps asking for plain-English, understandable work.';
-  if (memoryIds.has('proof_gate') && (candidateIds.has('trust') || candidateIds.has('technical'))) return 'Keshav wants proof and receipts before serious work is accepted.';
+  if (memoryIds.has('runway_revenue') && candidateIds.has('users_revenue')) return 'the operator has been steering toward user/revenue proof because runway is tight.';
+  if (memoryIds.has('plain_language') && candidateIds.has('usability')) return 'the operator keeps asking for plain-English, understandable work.';
+  if (memoryIds.has('proof_gate') && (candidateIds.has('trust') || candidateIds.has('technical'))) return 'the operator wants proof and receipts before serious work is accepted.';
   if (memoryIds.has('working_memory')) return 'Recent logs are being used as working memory for what matters now.';
   if (memoryIds.has('technical_ambition') && candidateIds.has('technical')) return 'The member memory still values technical advancement when it has proof.';
   return '';
@@ -4160,14 +4222,61 @@ function startMission(args, options = {}) {
   // checkout's dirt never reaches the mission baseline.
   if (hasFlag(args, '--worktree')) {
     let created;
+    const sourceTop = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8' });
+    const sourceCheckout = sourceTop.status === 0 ? String(sourceTop.stdout).trim() : process.cwd();
+    let nodeModulesSource = null;
     try {
       const { createAgentWorktree } = require('./worktree');
       const base = readFlag(args, '--base', '') || inheritedWorktreeBase(process.cwd());
       created = createAgentWorktree({ member: mission.owner, task: mission.objective, ...(base ? { base } : {}) });
+      const packageFile = path.join(sourceCheckout, 'package.json');
+      const sourceModules = path.join(sourceCheckout, 'node_modules');
+      const targetModules = path.join(created.path, 'node_modules');
+      try {
+        let targetExists = false;
+        try {
+          fs.lstatSync(targetModules);
+          targetExists = true;
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+        if (fs.existsSync(packageFile) && fs.existsSync(sourceModules) && !targetExists) {
+          const manifest = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+          const hasDependencies = ['dependencies', 'devDependencies', 'optionalDependencies']
+            .some((field) => manifest[field] && Object.keys(manifest[field]).length > 0);
+          if (hasDependencies) {
+            const checkIgnored = () => {
+              const result = spawnSync('git', ['check-ignore', '-q', 'node_modules'], { cwd: created.path, encoding: 'utf8' });
+              if (result.error || (result.status !== 0 && result.status !== 1)) {
+                throw new Error(result.error?.message || String(result.stderr || 'git check-ignore failed').trim());
+              }
+              return result.status === 0;
+            };
+            if (!checkIgnored()) {
+              const commonDir = spawnSync('git', ['rev-parse', '--git-common-dir'], { cwd: created.path, encoding: 'utf8' });
+              if (commonDir.error || commonDir.status !== 0) {
+                throw new Error(commonDir.error?.message || String(commonDir.stderr || 'could not find shared git directory').trim());
+              }
+              const excludeFile = path.resolve(created.path, String(commonDir.stdout).trim(), 'info', 'exclude');
+              fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+              const exclude = fs.existsSync(excludeFile) ? fs.readFileSync(excludeFile, 'utf8') : '';
+              if (!exclude.split(/\r?\n/).includes('/node_modules')) {
+                fs.appendFileSync(excludeFile, `${exclude && !exclude.endsWith('\n') ? '\n' : ''}/node_modules\n`);
+              }
+            }
+            if (!checkIgnored()) throw new Error('git still tracks node_modules after updating the shared exclude file');
+            fs.symlinkSync(sourceModules, targetModules, 'dir');
+            nodeModulesSource = sourceModules;
+          }
+        }
+      } catch (error) {
+        console.warn(`warning: could not link node_modules: ${String(error.message).split(/\r?\n/)[0]}`);
+      }
     } catch (e) {
       exitMissionError(`[mission start] worktree creation failed: ${e.message}`, 2, asJson);
     }
     mission.worktree = { path: created.path, branch: created.branch, base: created.base };
+    if (nodeModulesSource) mission.node_modules_source = nodeModulesSource;
     process.chdir(created.path);
   }
   if (mission.xp_task_enabled) {
@@ -4225,6 +4334,8 @@ function startMission(args, options = {}) {
       dirty_count: worktreeBaseline.dirty_count,
       dirty_hash: worktreeBaseline.dirty_hash,
     } : null,
+    node_modules_linked: Boolean(saved.node_modules_source),
+    node_modules_source: saved.node_modules_source || null,
     ...(saved.remap_reason ? { remap_reason: saved.remap_reason } : {}),
   };
   if (!options.silent) {
@@ -4236,6 +4347,7 @@ function startMission(args, options = {}) {
         `State: ${saved.status}`,
         ...(saved.remap_reason ? [`Remap: ${saved.remap_reason}`] : []),
         ...(saved.worktree ? [`Worktree: ${saved.worktree.path}`, `Branch: ${saved.worktree.branch}`] : []),
+        ...(saved.node_modules_source ? [`linked node_modules from ${saved.node_modules_source}`] : []),
         ...warnings.map((warning) => `Warning: ${warning.message}`),
         ...(saved.xp_task ? [`AgentXP task: ${saved.xp_task.ref}`] : []),
         ...(saved.worktree ? [`Next: cd ${saved.worktree.path} && ${nextTickCommand}`] : [`Next: ${nextTickCommand}`]),
@@ -8049,12 +8161,6 @@ function isWithinActiveHours(activeHours, now = new Date()) {
   return cur >= start || cur < end;
 }
 
-function sleepSync(ms) {
-  const waitMs = Math.max(0, Number(ms) || 0);
-  if (!waitMs) return;
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
-}
-
 function missionLockOwnerIsAlive(pid) {
   const ownerPid = Number(pid);
   if (!Number.isInteger(ownerPid) || ownerPid <= 0) return false;
@@ -8700,7 +8806,7 @@ function spawnGenericRunnerTick(mission, opts) {
     let briefId = null;
     try {
       promptFile = writeRunnerPromptFile(cwd, mission.id, prompt);
-      cmd = buildRunnerCommand({ promptFile, model });
+      cmd = buildRunnerCommand({ promptFile, model, ...(mission.roster_effort ? { effort: mission.roster_effort } : {}) });
       const engine = canonicalEngineName(mission.runner);
       if (engine) {
         const record = appendBriefRecord(cwd, {
@@ -8877,6 +8983,7 @@ function spawnClaudeTick(mission, opts) {
       '--include-partial-messages',
     ];
     if (model) args.push('--model', model);
+    if (mission.roster_effort) args.push('--effort', mission.roster_effort);
     if (sessionMode === 'set') args.push('--session-id', sessionId);
     else if (sessionMode === 'resume') args.push('--resume', sessionId);
 
@@ -9043,7 +9150,7 @@ async function runEngineVerifier(mission, options = {}) {
       signal: options.signal,
       timeoutMs: ENGINE_VERIFY_TIMEOUT_MS,
       prompt: buildEngineVerifyPrompt(mission, options.tickIndex || 1),
-      model: resolveClaudeRunnerModel(verifyMission),
+      model: resolveMissionTickRunnerModel(verifyMission),
     });
   } catch (error) {
     engineResult = { ok: false, error: error.message };
@@ -9623,12 +9730,12 @@ async function executeMissionRunTicksPhase(context) {
         const runClaudeSession = () => spawnClaudeTick(tickRuntimeMission, {
           sessionMode, sessionId: useId, cwd, signal: controller.signal,
           missionLock: lock,
-          timeoutMs: clampTimeoutMs(
+          timeoutMs: missionTickTimeoutMs(
+            tickRuntimeMission,
             (maxWallSeconds - ((Date.now() - startedAt) / 1000)) * 1000,
-            MISSION_RUN_DEFAULTS.claudeTimeoutMs,
           ),
           prompt,
-          model: resolveClaudeRunnerModel(tickRuntimeMission),
+          model: resolveMissionTickRunnerModel(tickRuntimeMission),
         });
         try {
           claudeResult = await runClaudeSession();
@@ -11629,6 +11736,7 @@ module.exports = {
   missionProtectedLaneHold,
   missionCommand,
   startMission,
+  resolveMission,
   spawnMissionDriver,
   missionRunnerNeedsLiveSession,
   completeMission,
@@ -11680,6 +11788,8 @@ module.exports = {
   missionHumanStatusText,
   resolveMissionRunnerSelection,
   resolveMissionTickRunner,
+  resolveMissionTickRunnerModel,
+  missionTickTimeoutMs,
   engineFailureHealthStatus,
   recordMissionEngineTickOutcome,
   tickMadeProgress,

package/commands/one-lap.js

@@ -9,7 +9,10 @@ const { readWishes } = require('../lib/wish-store');
 const {
   engineRegistryView,
   resolveEngineForRole,
+  resolveEngineForRoleRanked,
   resolveRegisteredEngine,
+  rosterPinFor,
+  rosterDecided,
 } = require('../lib/engine-registry');
 const { parseVerifyCommand } = require('../lib/auto-accept-certified');
 const fleet = require('../lib/fleet');
@@ -155,7 +158,8 @@ function readyExecutor(root, preferred = '') {
     if (!selected.roles.includes('executor')) throw new Error(`engine ${selected.id} is not an executor`);
     if (!selected.health || selected.health.status !== 'ready') throw new Error(`engine ${selected.id} is not ready`);
     if (!fleet.FLEET_CAPABLE.includes(selected.id)) throw new Error(`engine ${selected.id} cannot build headlessly`);
-    return selected;
+    const pin = rosterPinFor('executor', selected.id, root);
+    return Object.keys(pin).length ? { ...selected, ...pin } : selected;
   }
   const routed = resolveEngineForRole('executor', root);
   if (routed && fleet.FLEET_CAPABLE.includes(routed.id)) return routed;
@@ -168,16 +172,30 @@ function readyExecutor(root, preferred = '') {
 
 function readyValidators(root, preferred = '', exclude = '') {
   const blocked = String(exclude || '').trim();
+  const rosterRanked = resolveEngineForRoleRanked('validator', root);
+  const fromRoster = rosterDecided(rosterRanked.source);
+  const rosterOrder = !preferred && fromRoster
+    ? rosterRanked.ranked.map((engine) => engine.id)
+    : [];
+  const pinned = fromRoster && rosterRanked.engine
+    && (rosterRanked.engine.roster_model || rosterRanked.engine.roster_effort || rosterRanked.engine.roster_max_seconds)
+    ? rosterRanked.engine
+    : null;
+  // A roster pick can name an engine that reviews only when picked (codex),
+  // so the roster's list joins even when an engine lacks the role.
+  const rosterPicked = new Set(fromRoster ? rosterRanked.ranked.map((engine) => engine.id) : []);
   const candidates = engineRegistryView(root)
-    .filter((engine) => engine.roles.includes('validator'))
+    .filter((engine) => engine.roles.includes('validator') || rosterPicked.has(engine.id))
     .filter((engine) => engine.id !== blocked)
     .sort((a, b) => {
       const aPreferred = preferred && a.id === preferred ? 0 : 1;
       const bPreferred = preferred && b.id === preferred ? 0 : 1;
       return aPreferred - bPreferred
+        || (rosterOrder.length ? (rosterOrder.indexOf(a.id) - rosterOrder.indexOf(b.id)) : 0)
         || Number(a.fallback_order) - Number(b.fallback_order)
         || String(a.id).localeCompare(String(b.id));
-    });
+    })
+    .map((engine) => (pinned && engine.id === pinned.id ? { ...engine, ...pinFields(pinned) } : engine));
   const ready = candidates.filter((engine) => engine.health && engine.health.status === 'ready');
   // Route-time determinism: which validator binaries exist on this machine
   // must not change the lap's route. When none are ready, dispatch with the
@@ -187,6 +205,39 @@ function readyValidators(root, preferred = '', exclude = '') {
   return ready.length ? ready : candidates;
 }
 
+function pinFields(engine) {
+  const pin = {};
+  for (const field of ['roster_model', 'roster_effort', 'roster_max_seconds']) {
+    if (engine && engine[field]) pin[field] = engine[field];
+  }
+  return pin;
+}
+
+// The roster's pins ride into the flight: the builder's model, effort, and
+// time cap for the builder, and each reviewer's for that reviewer only. A
+// reviewer with only a model keeps the plain model string.
+function lapModelPins(executor, validators = []) {
+  const validatorModels = {};
+  for (const engine of validators) {
+    if (!engine) continue;
+    if (engine.roster_effort || engine.roster_max_seconds) {
+      validatorModels[engine.id] = {
+        model: engine.roster_model || '',
+        effort: engine.roster_effort || '',
+        max_seconds: engine.roster_max_seconds || 0,
+      };
+    } else if (engine.roster_model) {
+      validatorModels[engine.id] = engine.roster_model;
+    }
+  }
+  return {
+    model: executor && executor.roster_model || '',
+    ...(executor && executor.roster_effort ? { effort: executor.roster_effort } : {}),
+    ...(executor && executor.roster_max_seconds ? { maxSeconds: executor.roster_max_seconds } : {}),
+    validatorModels: Object.keys(validatorModels).length ? validatorModels : null,
+  };
+}
+
 function taskById(runCli, taskId) {
   const result = runCli(['task', 'show', taskId, '--json']);
   if (!result || result.status !== 0) return null;
@@ -656,6 +707,7 @@ async function runOneLap(ask, options = {}) {
       reviewOnly: true,
       verifierCommand: verifier,
       validatorEngines: validators.map((entry) => entry.id),
+      ...lapModelPins(executor, validators),
       actor: mission.owner || 'mission-lead',
       installedEngines: engineRegistryView(root)
         .filter((entry) => entry.health && entry.health.status === 'ready')
@@ -773,4 +825,7 @@ async function runOneLap(ask, options = {}) {
 module.exports = {
   oneLapSafetyIssue,
   runOneLap,
+  readyExecutor,
+  readyValidators,
+  lapModelPins,
 };

package/commands/pack.js

@@ -1622,7 +1622,7 @@ async function publishPack(rawArgs, cwd = process.cwd(), options = {}) {
   }
 
   // pack.json belongs to the pack, not to whatever repo happens to contain it
-  // (2026-07-27: publishing ~/arena/atrisos-backend/atris wrote a pack.json
+  // (2026-07-27: publishing a backend workspace's atris folder wrote a pack.json
   // into atrisos-backend/ and polluted the source repo).
   const manifestPath = path.join(sourceDir, 'pack.json');
   const existing = readJson(manifestPath);
@@ -2453,7 +2453,7 @@ function printCapabilityTrustCard(policy, trust, receiptPath, userDenyRuleCount
   if (options.operatorInput) {
     console.log(`  operator input: ${options.operatorInput.bytes} bytes injected; source path withheld from the pack and receipt`);
   }
-  console.log(`  host shell: ${policy.grantedCapabilities.includes('host.shell') ? 'GRANTED \u2014 Bash can reach host files and network' : 'denied'}`);
+  console.log(`  host shell: ${policy.grantedCapabilities.includes('host.shell') ? 'granted, bash can reach host files and network' : 'denied'}`);
   console.log('  receipt coverage: Atris hook tool events; direct slash-skill invocations and later Claude or policy denials may not appear');
   console.log(`  receipt: ${receiptPath}`);
 }

package/commands/probe.js

@@ -454,18 +454,24 @@ async function probeCommand(argv) {
   const detail = ok
     ? `answer: ${resultText.slice(0, 80).replace(/\n/g, ' ')}`
     : `dead-end: ${deadEnd}`;
-  const line = `- **atris-probe** \`${stamp}\` \u2014 ${where} · ${a.model}`
+  const line = buildProbeLine({ stamp, where, model: a.model, member, engine, ok, secs, toolsRun, calendar: a.calendar, cliCalendarOps, detail });
+  console.log(line);
+  return ok ? 0 : 1;
+}
+
+function buildProbeLine({ stamp, where, model, member, engine, ok, secs, toolsRun, calendar, cliCalendarOps, detail }) {
+  const line = `- **atris-probe** \`${stamp}\` - ${where} · ${model}`
     + (member ? ` · member=${member}` : '')
     + (engine ? ` · engine=${engine}` : '')
-    + ` · ${ok ? 'PASS' : 'FAIL'} · ${secs}s · tools=${toolsRun}`
-    + (a.calendar ? ` cal_cli=${cliCalendarOps}` : '')
+    + ` · ${ok ? 'pass' : 'fail'} · ${secs}s · tools=${toolsRun}`
+    + (calendar ? ` cal_cli=${cliCalendarOps}` : '')
     + ` · ${detail}`;
-  console.log(line);
-  return ok ? 0 : 1;
+  return line.replace(/\s*\u2014\s*/g, ', ');
 }
 
 module.exports = {
   probeCommand,
+  buildProbeLine,
   runAtris2Turn,
   // exported for tests
   normalizePath,

package/commands/pull.js

@@ -722,7 +722,7 @@ async function pullBusiness(slug) {
         fs.mkdirSync(path.dirname(localPath), { recursive: true });
         fs.writeFileSync(localPath, content);
       }
-      console.log(`  \u26A0 ${p.replace(/^\//, '')}  CONFLICT \u2014 both you and the computer changed this`);
+      console.log(`  \u26A0 ${p.replace(/^\//, '')}: conflict, both you and the computer changed this`);
       console.log(`    \u2192 Remote version saved as ${p.replace(/^\//, '')}.remote`);
       conflictCount++;
     }

package/commands/push.js

@@ -985,7 +985,7 @@ async function pushAtris() {
       console.log(`    ... +${failedToLand.length - shown.length} more`);
     }
     console.log('');
-    console.log('  Common causes: path is outside the workspace (e.g. absolute /Users/... path),');
+    console.log('  common causes: path is outside the workspace (for example, an absolute home path),');
     console.log('  your role lacks write permission for that folder, or warm runner returned an error.');
     console.log('  These files will appear as drift on your next push so you can retry.');
   }

package/commands/rainmaker.js

@@ -9,22 +9,9 @@
  */
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
-
-function resolveBackendRoot() {
-  const candidates = [
-    process.env.ATRIS_BACKEND_DIR,
-    path.resolve(__dirname, '..', '..', 'atrisos-backend'),
-    path.resolve(process.cwd(), '..', 'atrisos-backend'),
-    path.join(os.homedir(), 'arena', 'atrisos-backend'),
-  ].filter(Boolean);
-  for (const root of candidates) {
-    if (fs.existsSync(path.join(root, 'scripts', 'rainmaker.py'))) return root;
-  }
-  return null;
-}
+const { BACKEND_ROOT_HINT, resolveBackendRoot } = require('../utils/backend-root');
 
 function rainmakerCommand(args = []) {
   if (args[0] === '--help' || args[0] === '-h') {
@@ -32,8 +19,8 @@ function rainmakerCommand(args = []) {
     return 0;
   }
   const root = resolveBackendRoot();
-  if (!root) {
-    console.error('Cannot find scripts/rainmaker.py. Set ATRIS_BACKEND_DIR to atrisos-backend.');
+  if (!root || !fs.existsSync(path.join(root, 'scripts', 'rainmaker.py'))) {
+    console.error(BACKEND_ROOT_HINT);
     return 1;
   }
   const script = path.join(root, 'scripts', 'rainmaker.py');

package/commands/run.js

@@ -9,6 +9,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { mapNotesPath } = require('../lib/map-refs');
 const { execSync, spawnSync } = require('child_process');
 const { getLogPath, ensureLogDirectory, createLogFile } = require('../lib/journal');
 const { parseTodo } = require('../lib/todo');
@@ -118,11 +119,12 @@ function execPhaseCommandSync(cmd, opts = {}) {
  * what the validator found - closing the try → notice → adjust loop.
  */
 function buildRunPrompt(phase, context, priorCycleReview) {
-  const { mapPath, todoPath, personaPath, lessonsPath, journalPath } = context;
+  const { mapPath, notesPath, todoPath, personaPath, lessonsPath, journalPath } = context;
 
   const readFiles = [
     personaPath && `- ${personaPath}`,
     mapPath && `- ${mapPath}`,
+    notesPath && `- ${notesPath}`,
     todoPath && `- ${todoPath}`,
     lessonsPath && `- ${lessonsPath}`,
     journalPath && `- ${journalPath}`,
@@ -413,6 +415,7 @@ async function runAtris(options = {}) {
   // Build context paths
   const context = {
     mapPath: fs.existsSync(path.join(atrisDir, 'MAP.md')) ? 'atris/MAP.md' : null,
+    notesPath: mapNotesPath(path.dirname(atrisDir)),
     todoPath: fs.existsSync(path.join(atrisDir, 'TODO.md')) ? 'atris/TODO.md' : null,
     personaPath: fs.existsSync(path.join(atrisDir, 'PERSONA.md')) ? 'atris/PERSONA.md' : null,
     lessonsPath: fs.existsSync(path.join(atrisDir, 'lessons.md')) ? 'atris/lessons.md' : null,

package/commands/scout.js

@@ -53,7 +53,7 @@ const ENGINES = {
 function scoutPrompt(question, dir) {
   return [
     `You are a read-only scout in ${dir}. You NEVER write, edit, or run mutating commands.`,
-    `Search order: index files first (atris/MAP.md, atris/TODO.md, README) via targeted reads, then grep. Cheap reads only.`,
+    `Search order: index files first (atris/MAP.md, atris/refs/MAP-NOTES.md if present for exact file:line refs, atris/TODO.md, README) via targeted reads, then grep. Cheap reads only.`,
     ``,
     `Question: ${question}`,
     ``,

package/commands/search.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { existingMapDocs } = require('../lib/map-refs');
 
 const MEMORY_LAYERS = [
   { key: 'features', dir: path.join('atris', 'features') },
@@ -226,10 +227,11 @@ function scanLayer(root, layer, terms) {
   return scanFiles(root, layer.key, layer.dir.split(path.sep).join('/'), listMarkdownFiles(dir), terms);
 }
 
+// The map layer covers the boot map and the notes file that holds its deep refs.
 function scanMap(root, terms) {
-  const mapPath = path.join(root, 'atris', 'MAP.md');
-  if (!fs.existsSync(mapPath)) return emptyLayerResult('map', 'atris/MAP.md');
-  return scanFiles(root, 'map', 'atris/MAP.md', [mapPath], terms);
+  const files = existingMapDocs(root).map((doc) => path.join(root, doc));
+  if (!files.length) return emptyLayerResult('map', 'atris/MAP.md');
+  return scanFiles(root, 'map', 'atris/MAP.md', files, terms);
 }
 
 function scanSource(root, terms) {

package/commands/spaceship.js

@@ -4,7 +4,7 @@
  * atris spaceship, bounded, self-reporting overnight runner.
  *
  * Thin wrapper over scripts/spaceship.sh. The script is the implementation
- * (a supervised loop that survives bad ticks and emails Keshav on every
+ * (a supervised loop that survives bad ticks and emails the operator on every
  * meaningful state change); this module just makes it reachable as
  * `atris spaceship ...` and integrates with the CLI's command dispatch.
  *

package/commands/stream.js

@@ -293,6 +293,31 @@ function pushEvent(events, input) {
   if (event) events.push({ ...event, key: eventKey(event) });
 }
 
+// When timestamps match, state snapshots precede receipts, then landing summaries.
+const STREAM_SOURCE_RANK = {
+  task: 20,
+  task_episode: 30,
+  scorecard: 40,
+  mission_event: 50,
+  mission_state: 60,
+  mission_receipt: 70,
+  mission_landing: 80,
+  worktree: 85,
+  landing: 90,
+  state: 10,
+};
+
+function compareStreamEvents(a, b) {
+  const byMs = a.ms - b.ms;
+  if (byMs) return byMs;
+  const rankA = STREAM_SOURCE_RANK[a.source] ?? 55;
+  const rankB = STREAM_SOURCE_RANK[b.source] ?? 55;
+  if (rankA !== rankB) return rankA - rankB;
+  const byKey = String(a.key || '').localeCompare(String(b.key || ''));
+  if (byKey) return byKey;
+  return String(a.event || '').localeCompare(String(b.event || ''));
+}
+
 function statePaths(root) {
   const stateDir = path.join(root, '.atris', 'state');
   return {
@@ -455,7 +480,6 @@ function collectRunReceiptEvents(root, deps, events) {
 
 function candidateWorktreeDirs(root, deps) {
   const dirs = new Set([
-    path.resolve(root, '..', '.agent-worktrees'),
     path.join(path.dirname(root), '.agent-worktrees', path.basename(root)),
   ]);
   const sidecar = readJson(statePaths(root).sidecar, deps, null);
@@ -606,7 +630,7 @@ function collectStreamEvents({ root = process.cwd(), sinceMs = 0, agent = '', no
     if (wantedAgent && event.agent.toLowerCase() !== wantedAgent) continue;
     byKey.set(event.key, event);
   }
-  return [...byKey.values()].sort((a, b) => (a.ms - b.ms) || a.event.localeCompare(b.event));
+  return [...byKey.values()].sort(compareStreamEvents);
 }
 
 function waitingOnOperator(tasks) {
@@ -841,6 +865,7 @@ function streamCommand(args = [], deps = defaultDeps()) {
 module.exports = {
   collectSnapshot,
   collectStreamEvents,
+  compareStreamEvents,
   createStreamState,
   parseArgs,
   parseSince,

package/commands/study.js

@@ -15,6 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const http = require('http');
 const { spawn, spawnSync } = require('child_process');
+const { resolveBackendRoot } = require('../utils/backend-root');
 
 const FEED_URL = 'http://localhost:8777';
 const FEED_STATS_URL = `${FEED_URL}/api/stats`;
@@ -91,15 +92,19 @@ function parseArgs(argv = []) {
 }
 
 function resolveStudyRoot(cwd = process.cwd()) {
-  const candidates = [
-    process.env.ATRIS_STUDY_ROOT,
-    process.env.ATRIS_BACKEND_ROOT,
-    path.join(path.resolve(cwd), 'atris', 'study'),
-  ].filter(Boolean);
-  for (const root of candidates) {
-    const resolved = path.resolve(String(root));
-    if (fs.existsSync(resolved)) return resolved;
-  }
+  if (process.env.ATRIS_STUDY_ROOT) {
+    const explicit = path.resolve(process.env.ATRIS_STUDY_ROOT);
+    if (fs.existsSync(explicit) && fs.statSync(explicit).isDirectory()) return explicit;
+  }
+  // Same order as before: an explicitly set backend root wins over the local folder.
+  if (process.env.ATRIS_BACKEND_ROOT) {
+    const envBackend = path.resolve(process.env.ATRIS_BACKEND_ROOT);
+    if (fs.existsSync(envBackend)) return envBackend;
+  }
+  const local = path.join(path.resolve(cwd), 'atris', 'study');
+  if (fs.existsSync(local) && fs.statSync(local).isDirectory()) return local;
+  const backend = resolveBackendRoot(cwd);
+  if (backend) return backend;
   return null;
 }
 
@@ -697,6 +702,7 @@ async function run(argv = []) {
 
 module.exports = {
   run,
+  resolveStudyRoot,
   parseArgs,
   showHelp,
   wrapText,