atris 3.58.8 → 3.59.0

package/AGENTS.md

@@ -171,8 +171,9 @@ named none. These rules are the difference, in priority order:
 7. **Final report = files changed + verify command + its exact exit/output.**
    Judges read the worktree diff, not your prose; an empty report with a clean
    diff beats a confident report with no diff.
-8. **Update `atris/MAP.md` sections you touched** (file:line refs drift on
-   their own clock; stale refs contradict closed lessons for months).
+8. **Update the map sections you touched:** routing rows in `atris/MAP.md`,
+   file:line refs in `atris/refs/MAP-NOTES.md` (refs drift on their own clock;
+   stale refs contradict closed lessons for months).
 9. **Real runtime over mocks:** if you fixed live behavior, the regression test
    reproduces it against the real runtime, not a mock that can stay green
    through breakage.

package/atris/skills/engines/SKILL.md

@@ -24,6 +24,32 @@ tags:
 
 One contract, eleven live profiles. The orchestrator writes a bounded task prompt, dispatches it to an engine, then **independently verifies, lands, and pushes** the result. Engines never self-certify.
 
+## Pick the job owner first
+
+Before choosing an engine for search, build, or review, run `atris engine roster` and use that job's lead worker. Only deviate when the user names an engine.
+
+The roster is a markdown file the owner can edit any time: `atris/ROSTER.md` for this project, `~/.atris/ROSTER.md` for every project on this machine. A project job wins over the machine job with the same name. Each `## job` heading lists its workers in order, one per line, naming the tool and the model:
+
+```
+## review
+- codex, model: gpt-6-astra, effort: medium, max: 20 min
+- claude code, model: opus 5.5
+
+## small build
+- devin, model: swe-2-max, until 2026-10-24
+- grok, model: grok 4.7 fast
+```
+
+The first worker that is ready and not expired leads; the rest are its backups, in order. Tools take engine ids or `claude code`, `atris fast`, and `gemini`. The older one-line shape (`build: claude opus 5.5, backup codex`) still reads the same, and the first `atris engine assign` rewrites the file into sections. `assign <job> <tool>` sets the lead and keeps the rest; `--add` puts a worker at the end, `--remove <tool>` drops one, `--clear` drops the job, and `--everywhere` writes the machine file. `atris engine roster --available` lists the tools and models on this machine.
+
+A job's list is also its team. When a task splits into parallel parts, give the parts to that job's workers in order, first worker first, instead of piling them all on the lead. Heavy models like astra and fable should only judge: have the search lead write them a trimmed brief first.
+
+Changes for one shell only go in a session file above both rosters. Set `ATRIS_ROSTER_SESSION=<name>` (agent shells have no terminal, so they must), then `atris engine assign <job> <tool> --session`. A session job replaces that job's whole list for this shell; `atris engine roster session` shows the changes and `atris engine roster session clear` drops them. A session nobody used for a day is dropped on its own.
+
+Jobs are open-ended: besides search, build, and review, the owner can add a job like `## small build`, or `## quick fixes (like build)` when the name does not say its kind. For a small, tightly specified build slice, use the small build lead when `atris engine roster` shows one; bigger builds use build.
+
+Team members pick automatically. Navigators, researchers, and scouts do search; validators, reviewers, judges, critics, and verifiers do review; everyone else builds. A line under `## team` overrides that, with a job (`- researcher: search`) or a tool and model (`- judge: claude code, model: opus 5.5`). `member run`, missions with an owner, and autopilot's plan, do, and review use the member's pick; `--engine` still wins. `atris engine roster` lists the team and warns about any line it could not use.
+
 ## three verbs
 
 - ask: `atris engine <name> "<question>"`; pin a model with `atris engine <name> --model <model> "<question>"`
@@ -80,7 +106,8 @@ Headless dispatch permissions (verified 2026-08-11): `codex exec`, `grok`, and `
 
 ## Picking an engine
 
-- **Multi-file or long build**: Devin `swe-2-max` while its Free tag holds (check `devin models list`); Codex `gpt-6-sol` if the tag is gone.
+- **Cheap bounded errands**: Devin `swe-2-max` while its Free tag holds (check `devin models list`).
+- **Multi-file or long build**: Use the project's build pick. If there is no pick, use the router's choice.
 - **Judgment-heavy build**: Opus 5.5 subagent (Claude row).
 - **Review / deep judgment**: FABLE profile; Codex `gpt-6-sol` or Opus 5.5 as second validator.
 - **Quick fix**: Cursor.

package/bin/atris.js

@@ -1248,6 +1248,7 @@ if (!command || !knownCommands.includes(command)) {
       error: command ? `unknown command: ${command}` : 'unknown command',
       command: command || null,
       input: rawNaturalArgs.join(' '),
+      suggestions: suggestCommands(command),
       usage: 'atris help',
     }, null, 2));
     process.exit(2);
@@ -3288,6 +3289,8 @@ if (command === 'guide') {
       .then(() => process.exit(0))
       .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
   }
+} else if (command === 'host') {
+  require('../commands/host').hostCommand();
 } else if (command === 'social') {
   require('../commands/social').socialCommand()
     .then(() => process.exit(0))

package/commands/autopilot.js

@@ -18,6 +18,7 @@ const {
   runnerAvailabilityFailureMessage,
 } = require('../lib/runner-command');
 const { findStalePages, findStaleTasks, healBrokenMapRefs } = require('./clean');
+const { mapNotesPath } = require('../lib/map-refs');
 const {
   buildScorecardData,
   readScorecards,
@@ -483,19 +484,73 @@ function execPhaseCommandSync(cmd, opts = {}) {
   }
 }
 
+// plan, do, and review run as the navigator, executor, and validator. When
+// the roster names an engine for that member, the phase spawns it. A runner
+// set in the environment still wins, and with no roster line behind the
+// member the configured runner runs exactly as before.
+const AUTOPILOT_PHASE_MEMBERS = Object.freeze({ plan: 'navigator', do: 'executor', review: 'validator' });
+const RUNNER_ENV_OVERRIDES = Object.freeze([
+  'ATRIS_RUNNER_PROFILE',
+  'ATRIS_RUNNER_COMMAND_TEMPLATE',
+  'ATRIS_RUNNER_BIN',
+  'ATRIS_CLAUDE_COMMAND_TEMPLATE',
+  'ATRIS_CLAUDE_BIN',
+]);
+
+function autopilotPhaseEngine(phase, cwd = process.cwd()) {
+  const member = AUTOPILOT_PHASE_MEMBERS[phase];
+  if (!member) return null;
+  if (RUNNER_ENV_OVERRIDES.some((name) => String(process.env[name] || '').trim())) return null;
+  const { memberRosterEngine } = require('../lib/member-engine');
+  return memberRosterEngine(member, cwd, { requireMember: false });
+}
+
+// The phase's launch command and, when its roster line sets "max 20 min",
+// the time cap in ms (null means the caller's own timeout stands).
+function buildPhaseRunner(phase, promptFile, cwd = process.cwd(), allowedTools = 'Bash,Read,Write,Edit,Glob,Grep') {
+  const picked = autopilotPhaseEngine(phase, cwd);
+  if (!picked) return { command: buildRunnerCommand({ promptFile, allowedTools }), timeoutMs: null };
+  if (process.env.ATRIS_ROUTER_EXPLAIN !== '0') console.error(picked.reason);
+  const previous = process.env.ATRIS_RUNNER_PROFILE;
+  process.env.ATRIS_RUNNER_PROFILE = picked.engine.id;
+  try {
+    const command = buildRunnerCommand({
+      promptFile,
+      allowedTools,
+      ...(picked.model ? { model: picked.model } : {}),
+      ...(picked.engine.roster_effort ? { effort: picked.engine.roster_effort } : {}),
+    });
+    const maxSeconds = Number(picked.engine.roster_max_seconds) || 0;
+    return { command, timeoutMs: maxSeconds > 0 ? maxSeconds * 1000 : null };
+  } finally {
+    if (previous === undefined) delete process.env.ATRIS_RUNNER_PROFILE;
+    else process.env.ATRIS_RUNNER_PROFILE = previous;
+  }
+}
+
+function buildPhaseRunnerCommand(phase, promptFile, cwd = process.cwd()) {
+  return buildPhaseRunner(phase, promptFile, cwd).command;
+}
+
 /**
  * Run a phase via the configured runner subprocess.
  */
 function executePhaseDetailed(phase, context, options = {}) {
-  const { verbose = false, timeout = PHASE_TIMEOUT } = options;
+  const { verbose = false } = options;
+  let timeout = options.timeout || PHASE_TIMEOUT;
 
   const prompt = buildPrompt(phase, context, options);
   const tmpFile = path.join(process.cwd(), '.autopilot-prompt.tmp');
   fs.writeFileSync(tmpFile, prompt);
 
   try {
-    const cmd = options.cmdOverride
-      || buildRunnerCommand({ promptFile: tmpFile, allowedTools: 'Bash,Read,Write,Edit,Glob,Grep' });
+    let cmd = options.cmdOverride;
+    if (!cmd) {
+      const runner = buildPhaseRunner(phase, tmpFile);
+      cmd = runner.command;
+      // A roster time cap stops the phase at that time.
+      if (runner.timeoutMs) timeout = runner.timeoutMs;
+    }
     const env = { ...process.env };
     delete env.CLAUDECODE;
     const output = execPhaseCommandSync(cmd, {
@@ -625,6 +680,8 @@ function getContextFiles(phase, options = {}) {
     agentSpec && fs.existsSync(path.join(cwd, agentSpec)) ? agentSpec : null,
     'atris/PERSONA.md',
     'atris/MAP.md',
+    // Exact file:line refs live beside the short routing map.
+    mapNotesPath(cwd),
     'atris/TODO.md',
     fs.existsSync(path.join(cwd, 'atris/lessons.md')) ? 'atris/lessons.md' : null,
     (() => { const { logFile } = getLogPath(); return fs.existsSync(logFile) ? path.relative(cwd, logFile) : null; })(),
@@ -1357,15 +1414,25 @@ function parseProposedBlock(lines) {
   return Object.keys(proposed).length ? proposed : null;
 }
 
+// Plan review is review work, so it runs on the review pick like the review
+// phase, with that line's model, effort, and time cap. With no roster line
+// behind it, the configured runner runs exactly as before.
+function buildPlanReviewRunner(promptFile, cwd = process.cwd(), timeout = 180000) {
+  const runner = buildPhaseRunner('review', promptFile, cwd, 'Bash,Read,Grep,Glob');
+  return { command: runner.command, timeoutMs: runner.timeoutMs || timeout };
+}
+
 /**
- * Default executor for plan-review: spawn a fresh configured runner call.
+ * Default executor for plan-review: spawn a fresh runner call on the review pick.
  * Kept thin so tests can inject a stub via options.planReviewExec.
  */
 function defaultPlanReviewExecutor(prompt, { cwd, timeout = 180000 } = {}) {
   const tmpFile = path.join(cwd, '.autopilot-plan-review.tmp');
   fs.writeFileSync(tmpFile, prompt);
   try {
-    const cmd = buildRunnerCommand({ promptFile: tmpFile, allowedTools: 'Bash,Read,Grep,Glob' });
+    const runner = buildPlanReviewRunner(tmpFile, cwd, timeout);
+    const cmd = runner.command;
+    timeout = runner.timeoutMs;
     const env = { ...process.env };
     delete env.CLAUDECODE;
     const output = execPhaseCommandSync(cmd, {
@@ -3872,6 +3939,9 @@ module.exports = {
   isPhaseKillError,
   execPhaseCommandSync,
   executePhaseDetailed,
+  buildPhaseRunnerCommand,
+  buildPhaseRunner,
+  buildPlanReviewRunner,
   buildAutopilotGlassLog,
   writeAutopilotGlassLog,
   lessonSlug

package/commands/clean.js

@@ -358,9 +358,26 @@ function findStaleTasks(atrisDir) {
  * Detects both out-of-bounds AND drift (symbol moved to different line)
  * Returns { healed: number, unhealable: array }
  */
+// The boot map routes; atris/refs/MAP-NOTES.md holds the deep file:line refs.
+// Heal both. Entries from the notes file carry `map` so reports can say where.
+const MAP_NOTES_FILE = path.join('refs', 'MAP-NOTES.md');
+
 function healBrokenMapRefs(cwd, atrisDir, dryRun = false, homeDir = os.homedir()) {
   const mapFile = path.join(atrisDir, 'MAP.md');
   if (!fs.existsSync(mapFile)) return { healed: 0, unhealable: [] };
+  const result = healMapFileRefs(cwd, mapFile, dryRun, homeDir);
+  const notesFile = path.join(atrisDir, MAP_NOTES_FILE);
+  if (!fs.existsSync(notesFile)) return result;
+  const notes = healMapFileRefs(cwd, notesFile, dryRun, homeDir);
+  const map = path.relative(cwd, notesFile).split(path.sep).join('/');
+  return {
+    healed: result.healed + notes.healed,
+    unhealable: [...result.unhealable, ...notes.unhealable.map((entry) => ({ ...entry, map }))],
+    replacements: [...result.replacements, ...notes.replacements.map((entry) => ({ ...entry, map }))],
+  };
+}
+
+function healMapFileRefs(cwd, mapFile, dryRun, homeDir) {
 
   let mapContent = fs.readFileSync(mapFile, 'utf8');
   const unhealable = [];

package/commands/doc-health.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { resolveWorkspaceRoot } = require('../lib/mission-root');
 const { readText } = require('./brain');
-const { checkMapRefs, fixMapRefs } = require('../lib/map-refs');
+const { checkMapDocs, fixMapDocs } = require('../lib/map-refs');
 
 const BOOT_FILES = [
   'CLAUDE.md', 'AGENTS.md', 'atris/atris.md', 'atris/MAP.md',
@@ -76,9 +76,10 @@ function collectMap(root, text, featureNames, memberNames) {
   const files = [...paths].map(file => ({ path: file, exists: fs.existsSync(path.resolve(root, file)) }));
   const existing = files.filter(file => file.exists).length;
   const pathScore = files.length ? existing / files.length : 0;
-  const { refs: all, ...refs } = checkMapRefs(root, text);
+  // Line refs are checked in the boot map and in the notes file it points to.
+  const { refs: all, ...refs } = checkMapDocs(root, text);
   refs.flagged = all.filter(ref => ref.status !== 'ok').map(ref => ({
-    map_line: ref.map_line, ref: ref.raw, symbol: ref.symbol, status: ref.status,
+    doc: ref.doc, map_line: ref.map_line, ref: ref.raw, symbol: ref.symbol, status: ref.status,
     ...(ref.line ? { line: ref.line } : {}), ...(ref.lines ? { lines: ref.lines } : {}),
     ...(ref.reason ? { reason: ref.reason } : {}),
   }));
@@ -286,21 +287,25 @@ function refsLine(refs) {
   return `map refs: ${refs.ok} right, ${refs.moved} moved, ${refs.ambiguous} unclear, ${gone} gone`;
 }
 
+function docLine(ref) {
+  return `${ref.doc === 'atris/MAP.md' ? 'MAP' : ref.doc} line ${ref.map_line}`;
+}
+
 function describeLeft(ref) {
-  const where = `MAP line ${ref.map_line}: ${ref.raw}${ref.symbol ? ` (${ref.symbol})` : ''}`;
+  const where = `${docLine(ref)}: ${ref.raw}${ref.symbol ? ` (${ref.symbol})` : ''}`;
   if (ref.status === 'ambiguous') return `${where} found on lines ${ref.lines.join(', ')}`;
   if (ref.status === 'missing-file') return `${where} file is gone`;
   return `${where} ${ref.reason}`;
 }
 
 function fixRefsCommand(root, asJson) {
-  const { changes, left } = fixMapRefs(root);
+  const { changes, left } = fixMapDocs(root);
   if (asJson) {
     console.log(JSON.stringify({ ok: true, action: 'doc-health fix-refs', changes, left }, null, 2));
     return 0;
   }
   const lines = [changes.length ? `map refs: moved ${changes.length}` : 'map refs: nothing to move.'];
-  for (const change of changes) lines.push(`  MAP line ${change.map_line}: ${change.from} -> ${change.to} (${change.symbol})`);
+  for (const change of changes) lines.push(`  ${docLine(change)}: ${change.from} -> ${change.to} (${change.symbol})`);
   if (left.length) {
     lines.push(`left for a human: ${left.length}`);
     for (const ref of left) lines.push(`  ${describeLeft(ref)}`);