atris 3.57.4 → 3.58.6

package/lib/bench/runner.js

@@ -3,8 +3,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { treeHashFor } = require('../tree-hash');
 const { createBenchContext, withBenchContext } = require('./context');
 const { ENGINE_NAMES, getEngineAdapter, normalizeEngineName } = require('./engines');
+const { renderTreeInto } = require('./tree-render');
 
 const DEFAULT_PACK = 'core-v1';
 
@@ -208,6 +210,23 @@ function copyFixtureIntoWorkspace(fixtureDir, workspace) {
   });
 }
 
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function installAtrisShim(ctx) {
+  const shimDir = path.join(ctx.env.HOME, 'bin');
+  const shimPath = path.join(shimDir, 'atris');
+  fs.mkdirSync(shimDir, { recursive: true });
+  fs.writeFileSync(
+    shimPath,
+    `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(ctx.cliPath)} "$@"\n`,
+    { encoding: 'utf8', mode: 0o755 },
+  );
+  ctx.env.PATH = [shimDir, ctx.env.PATH].filter(Boolean).join(path.delimiter);
+  return shimPath;
+}
+
 async function runSetup(spec, ctx) {
   if (!spec.setupPath) return;
   delete require.cache[require.resolve(spec.setupPath)];
@@ -246,6 +265,7 @@ async function runAgentTaskSpec(spec, options = {}) {
   const started = Date.now();
   const timeoutMs = Number(spec.timeoutMs || options.timeoutMs || 300000);
   let bench = null;
+  let reachedCheck = false;
   try {
     bench = createBenchContext({
       repoRoot: options.repoRoot,
@@ -257,9 +277,15 @@ async function runAgentTaskSpec(spec, options = {}) {
     ctx.fixtureDir = spec.fixtureDir;
     ctx.promptPath = spec.promptPath;
     copyFixtureIntoWorkspace(spec.fixtureDir, ctx.workspace);
+    installAtrisShim(ctx);
+    if (options.treeRoot) {
+      const rendered = renderTreeInto(ctx.workspace, options.treeRoot);
+      if (typeof options.onTreeRendered === 'function') options.onTreeRendered(rendered);
+    }
 
-    const engine = getEngineAdapter(options.engine, { solutionPath: spec.solutionPath });
-    const availability = engine.available(ctx.workspace);
+    const engine = options.engineAdapter
+      || getEngineAdapter(options.engine, { solutionPath: spec.solutionPath, model: options.model });
+    const availability = engine.available(ctx.workspace, ctx.env);
     if (!availability.available) {
       return {
         id: spec.id,
@@ -268,15 +294,27 @@ async function runAgentTaskSpec(spec, options = {}) {
         failures: [],
         duration_ms: Date.now() - started,
         retried: false,
+        ...(options.classifyCouldNotRun ? { could_not_run: true } : {}),
       };
     }
 
     await runSetup(spec, ctx);
     const promptText = readTaskPrompt(spec);
-    const engineResult = await withTimeout(Promise.resolve(engine.run(promptText, ctx.workspace, timeoutMs)), spec, timeoutMs);
+    const engineResult = await withTimeout(
+      Promise.resolve(engine.run(promptText, ctx.workspace, timeoutMs, ctx.env)),
+      spec,
+      timeoutMs,
+    );
+    ctx.engineResult = {
+      status: engineResult && engineResult.status,
+      stdout: String(engineResult && engineResult.stdout || ''),
+      stderr: String(engineResult && engineResult.stderr || ''),
+      timedOut: Boolean(engineResult && engineResult.timedOut),
+    };
     if (!engineResult || engineResult.status !== 0) {
       throw new Error(formatEngineFailure(options.engine, engineResult));
     }
+    reachedCheck = true;
     await withTimeout(Promise.resolve().then(() => spec.check(ctx)), spec, timeoutMs);
     return {
       id: spec.id,
@@ -285,6 +323,7 @@ async function runAgentTaskSpec(spec, options = {}) {
       failures: [],
       duration_ms: Date.now() - started,
       retried: false,
+      ...(options.classifyCouldNotRun ? { could_not_run: false } : {}),
     };
   } catch (err) {
     return {
@@ -294,6 +333,7 @@ async function runAgentTaskSpec(spec, options = {}) {
       failures: [formatFailure(err)],
       duration_ms: Date.now() - started,
       retried: false,
+      ...(options.classifyCouldNotRun ? { could_not_run: !reachedCheck } : {}),
     };
   } finally {
     if (bench) bench.teardown();
@@ -314,6 +354,7 @@ async function runTaskSpec(spec, options = {}) {
       failures: [],
       duration_ms: Date.now() - started,
       retried: false,
+      ...(options.classifyCouldNotRun ? { could_not_run: true } : {}),
     };
   }
 
@@ -328,6 +369,7 @@ async function runTaskSpec(spec, options = {}) {
           failures: [],
           duration_ms: Date.now() - started,
           retried,
+          ...(options.classifyCouldNotRun ? { could_not_run: true } : {}),
         };
       }
       return {
@@ -337,6 +379,7 @@ async function runTaskSpec(spec, options = {}) {
         failures: [],
         duration_ms: Date.now() - started,
         retried,
+        ...(options.classifyCouldNotRun ? { could_not_run: false } : {}),
       };
     } catch (err) {
       const infra = isInfraFailure(err);
@@ -351,6 +394,7 @@ async function runTaskSpec(spec, options = {}) {
         failures: [formatFailure(err)],
         duration_ms: Date.now() - started,
         retried,
+        ...(options.classifyCouldNotRun ? { could_not_run: infra } : {}),
       };
     }
   }
@@ -362,6 +406,7 @@ async function runTaskSpec(spec, options = {}) {
     failures: ['unreachable benchmark runner state'],
     duration_ms: Date.now() - started,
     retried,
+    ...(options.classifyCouldNotRun ? { could_not_run: true } : {}),
   };
 }
 
@@ -449,6 +494,7 @@ function exitCodeForRecord(record) {
 
 async function runBench(options = {}) {
   const repoRoot = path.resolve(options.repoRoot || repoRootFromHere());
+  const workspaceRoot = path.resolve(options.stateRoot || process.cwd());
   const pack = options.pack || (options.tasksDir ? path.basename(path.resolve(options.tasksDir)) : DEFAULT_PACK);
   const specs = selectTaskSpecs(loadTaskSpecs({ repoRoot, tasksDir: options.tasksDir, pack }), options.taskIds);
   const engine = normalizeBenchEngine(options.engine);
@@ -458,18 +504,27 @@ async function runBench(options = {}) {
   const label = normalizeLabel(options.label);
   const started = new Date().toISOString();
   const pythonCmd = options.pythonCmd === undefined ? findPython() : options.pythonCmd;
+  let renderedTreeHash = null;
   const taskRecords = await runTaskSpecs(specs, {
     repoRoot,
     timeoutMs: options.timeoutMs,
     pythonCmd,
     engine,
+    engineAdapter: options.engineAdapter,
+    model: options.model || null,
+    treeRoot: options.treeRoot,
+    onTreeRendered(rendered) {
+      renderedTreeHash = rendered.tree_hash;
+    },
   });
   const finished = new Date().toISOString();
   const summary = summarizeTasks(taskRecords);
   const record = {
     schema: 'atris.bench.run.v1',
+    tree_hash: options.treeRoot ? (renderedTreeHash || treeHashFor(options.treeRoot)) : treeHashFor(workspaceRoot),
     pack,
     engine,
+    model: engine ? (options.model || null) : null,
     label,
     experiment: options.experiment || null,
     started,
@@ -481,11 +536,154 @@ async function runBench(options = {}) {
     summary: summary.summary,
   };
 
-  if (options.persist !== false) appendResultRecord(record, options.stateRoot || process.cwd());
-  if (options.updateBaseline) writeBaselineRecord(record, options.stateRoot || process.cwd());
+  if (options.persist !== false) appendResultRecord(record, workspaceRoot);
+  if (options.updateBaseline) writeBaselineRecord(record, workspaceRoot);
   return { record, exitCode: exitCodeForRecord(record) };
 }
 
+function selectTaskSpecsInPackOrder(specs, taskIds = []) {
+  const ids = (taskIds || []).filter(Boolean);
+  if (!ids.length) return specs;
+  const requested = new Set(ids);
+  const known = new Set(specs.map((spec) => spec.id));
+  for (const id of requested) {
+    if (!known.has(id)) throw new BenchInfraError(`unknown benchmark task: ${id}`);
+  }
+  return specs.filter((spec) => requested.has(spec.id));
+}
+
+function positiveInteger(value, fallback, name) {
+  const normalized = value === undefined || value === null || value === '' ? fallback : Number(value);
+  if (!Number.isInteger(normalized) || normalized < 1) {
+    throw new BenchInfraError(`${name} must be a positive integer`);
+  }
+  return normalized;
+}
+
+function nonNegativeInteger(value, fallback, name) {
+  const normalized = value === undefined || value === null || value === '' ? fallback : Number(value);
+  if (!Number.isInteger(normalized) || normalized < 0) {
+    throw new BenchInfraError(`${name} must be a non-negative integer`);
+  }
+  return normalized;
+}
+
+function requireTreeDirectory(value, name) {
+  if (!value) throw new BenchInfraError(`${name} is required`);
+  const root = path.resolve(value);
+  try {
+    if (fs.statSync(root).isDirectory()) return root;
+  } catch {
+    // Fall through to the plain benchmark error.
+  }
+  throw new BenchInfraError(`${name} is not a directory: ${value}`);
+}
+
+function pairingScore(task) {
+  if (task.skipped || task.could_not_run) return null;
+  return task.passed ? 1 : 0;
+}
+
+function pairingOutcome(current, candidate) {
+  if (current === candidate) return 'tie';
+  if (candidate === null) return 'loss';
+  if (current === null) return 'win';
+  return candidate > current ? 'win' : 'loss';
+}
+
+function pairReason(wins, losses, verdict) {
+  if (wins === 0 && losses === 0) return 'all pairings tied';
+  if (verdict === 'select') {
+    return `candidate won ${wins} ${wins === 1 ? 'pairing' : 'pairings'} and lost ${losses}`;
+  }
+  return `candidate did not exceed its ${losses} ${losses === 1 ? 'loss' : 'losses'} with ${wins} ${wins === 1 ? 'win' : 'wins'}`;
+}
+
+async function runBenchPair(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot || repoRootFromHere());
+  const workspaceRoot = path.resolve(options.stateRoot || process.cwd());
+  const currentRoot = requireTreeDirectory(options.currentRoot || workspaceRoot, 'current tree');
+  const candidateRoot = requireTreeDirectory(options.candidateRoot, 'candidate tree');
+  const pack = options.pack || (options.tasksDir ? path.basename(path.resolve(options.tasksDir)) : DEFAULT_PACK);
+  const specs = selectTaskSpecsInPackOrder(
+    loadTaskSpecs({ repoRoot, tasksDir: options.tasksDir, pack }),
+    options.taskIds,
+  );
+  const engine = normalizeBenchEngine(options.engine);
+  if (specs.some((spec) => spec.kind === 'agent') && !engine) {
+    throw new BenchInfraError(`agent benchmark pack ${pack} requires --engine <${ENGINE_NAMES.join('|')}>`);
+  }
+  const repeats = positiveInteger(options.repeats, 1, 'repeats');
+  const minWinMargin = nonNegativeInteger(options.minWinMargin, 0, 'min win margin');
+  const pythonCmd = options.pythonCmd === undefined ? findPython() : options.pythonCmd;
+  const started = new Date().toISOString();
+  const tasks = [];
+  const currentScores = [];
+  const candidateScores = [];
+  let wins = 0;
+  let losses = 0;
+  let ties = 0;
+
+  for (const spec of specs) {
+    for (let repeat = 0; repeat < repeats; repeat += 1) {
+      const shared = {
+        repoRoot,
+        timeoutMs: options.timeoutMs,
+        pythonCmd,
+        engine,
+        engineAdapter: options.engineAdapter,
+        model: options.model || null,
+        classifyCouldNotRun: true,
+      };
+      const currentTask = await runTaskSpec(spec, { ...shared, treeRoot: currentRoot });
+      const candidateTask = await runTaskSpec(spec, { ...shared, treeRoot: candidateRoot });
+      const current = pairingScore(currentTask);
+      const candidate = pairingScore(candidateTask);
+      const outcome = pairingOutcome(current, candidate);
+      if (outcome === 'win') wins += 1;
+      else if (outcome === 'loss') losses += 1;
+      else ties += 1;
+      currentScores.push(current);
+      candidateScores.push(candidate);
+      tasks.push({
+        id: spec.id,
+        current,
+        candidate,
+        outcome,
+        current_duration_ms: currentTask.duration_ms,
+        candidate_duration_ms: candidateTask.duration_ms,
+        current_failures: currentTask.failures,
+        candidate_failures: candidateTask.failures,
+      });
+    }
+  }
+
+  const verdict = wins - losses > minWinMargin ? 'select' : 'reject';
+  const record = {
+    schema: 'atris.bench.pair.v1',
+    pack,
+    engine,
+    model: engine ? (options.model || null) : null,
+    started,
+    finished: new Date().toISOString(),
+    current_tree_hash: treeHashFor(currentRoot),
+    candidate_tree_hash: treeHashFor(candidateRoot),
+    tasks,
+    current_scores: currentScores,
+    candidate_scores: candidateScores,
+    wins,
+    losses,
+    ties,
+    min_win_margin: minWinMargin,
+    repeats,
+    verdict,
+    reason: pairReason(wins, losses, verdict),
+  };
+  if (options.persist !== false) appendResultRecord(record, workspaceRoot);
+  const allTied = wins === 0 && losses === 0;
+  return { record, exitCode: allTied ? 2 : verdict === 'select' ? 0 : 1 };
+}
+
 function taskMetadata(options = {}) {
   return loadTaskSpecs(options).map((spec) => ({
     id: spec.id,
@@ -514,6 +712,7 @@ module.exports = {
   readResultRecords,
   readTaskPrompt,
   runBench,
+  runBenchPair,
   summarizeTasks,
   taskMetadata,
 };

package/lib/bench/tree-render.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { computeTreeHash } = require('../tree-hash');
+
+const POINTER_BODY = [
+  'Read atris.md at the workspace root first and follow it.',
+  'Skills live under atris/skills, team briefs under atris/team.',
+];
+
+function writePointerIfAbsent(workspaceDir, filename) {
+  const destination = path.join(workspaceDir, filename);
+  if (fs.existsSync(destination)) return;
+  fs.writeFileSync(destination, [`# ${filename}`, ...POINTER_BODY, ''].join('\n'), 'utf8');
+}
+
+function renderTreeInto(workspaceDir, treeRoot) {
+  const workspace = path.resolve(workspaceDir);
+  const root = path.resolve(treeRoot);
+  const tree = computeTreeHash(root);
+  fs.mkdirSync(workspace, { recursive: true });
+
+  for (const entry of tree.manifest) {
+    const source = path.join(root, ...entry.path.split('/'));
+    const destination = path.join(workspace, ...entry.path.split('/'));
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(source, destination);
+  }
+
+  writePointerIfAbsent(workspace, 'CLAUDE.md');
+  writePointerIfAbsent(workspace, 'AGENTS.md');
+  return { tree_hash: tree.hash, files: tree.files };
+}
+
+function candidateError(source) {
+  return new Error(`candidate source not found: ${source}`);
+}
+
+function materializeCandidate(source, repoRoot) {
+  const candidate = String(source || '').trim();
+  const directPath = path.resolve(candidate || '.');
+  try {
+    if (candidate && fs.statSync(directPath).isDirectory()) return directPath;
+  } catch {
+    // A non-directory source may still name a git ref.
+  }
+
+  if (!candidate || candidate.startsWith('-')) throw candidateError(source);
+  const root = path.resolve(repoRoot || process.cwd());
+  const archive = spawnSync('git', ['archive', '--format=tar', candidate], {
+    cwd: root,
+    maxBuffer: 128 * 1024 * 1024,
+  });
+  if (archive.error || archive.status !== 0) throw candidateError(source);
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-bench-candidate-'));
+  const extract = spawnSync('tar', ['-x', '-C', tempDir], {
+    cwd: root,
+    input: archive.stdout,
+    encoding: 'utf8',
+    maxBuffer: 128 * 1024 * 1024,
+  });
+  if (extract.error || extract.status !== 0) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw candidateError(source);
+  }
+  return tempDir;
+}
+
+module.exports = {
+  materializeCandidate,
+  renderTreeInto,
+};

package/lib/card.js

@@ -1,4 +1,4 @@
-// atris card — turn one line of text into a beautiful, on-brand image.
+// atris card, turn one line of text into a beautiful, on-brand image.
 // Pure: spec -> self-contained HTML string. Reuses the design system: the same
 // themes as deck/site/html (incl. your .atris/theme.json brand), one accent,
 // Fraunces display, restraint. Render to PNG with headless Chrome (commands/card.js).

package/lib/chat-log-scan.js

@@ -176,7 +176,7 @@ function parseAxLog(filePath, text) {
     if (prompt) userTurns.push(compact(prompt[1], 240));
     if (/^●\s/.test(line)) toolCalls += 1;
     if (/·\s*Interrupted/i.test(line)) interrupted = true;
-    const worked = line.match(/^— Worked for ([^-]+?) —/);
+    const worked = line.match(/^\u2014 Worked for ([^-]+?) \u2014/);
     if (worked) lastWorkedSec = worked[1];
     if (ERROR_LINE.test(line) || /^x\s/.test(line.trim())) {
       findings.push(compact(line, 180));

package/lib/claude-boot-block.js

@@ -12,6 +12,8 @@ You are now running inside Atris, an AI workspace operating system.
 **ON EVERY CONVERSATION START:** If a SessionStart hook already displayed the Atris status block in this session, do not run it again. Otherwise, before your first response, execute \`atris atris.md\` and display the full output. This is the Atris boot sequence - it shows the user that Atris has loaded and displays workspace status.
 
 After displaying the boot output, respond to the user naturally.
+
+The person does not know atris words. Translate their plain English; when unsure run \`atris guide "<their words>"\`.
 ${ATRIS_END_MARKER}
 `;
 }

package/lib/deck-compose.js

@@ -50,7 +50,7 @@ function toItem(line) {
 
 // A quote may carry an attribution: `"..." - Name` or `... (Name)`.
 function splitQuote(text) {
-  const dash = text.match(/^["“]?(.+?)["”]?\s+[-–—]\s+(.+)$/);
+  const dash = text.match(/^["“]?(.+?)["”]?\s+[-–\u2014]\s+(.+)$/);
   if (dash) return { text: dash[1].trim(), author: dash[2].trim() };
   const paren = text.match(/^["“]?(.+?)["”]?\s+\(([^)]+)\)\s*$/);
   if (paren) return { text: paren[1].trim(), author: paren[2].trim() };

package/lib/deck-history.js

@@ -1,4 +1,4 @@
-// Deck build history — every build appends one line to a JSONL ledger so an
+// Deck build history: every build appends one line to a JSONL ledger so an
 // operator can answer "which presentation did this spec become, and when?".
 // Rebuilds reuse the same presentation id under --update; this ledger is how
 // you track iterations of a spec over time.
@@ -10,7 +10,7 @@ const crypto = require('crypto');
 
 const DEFAULT_HISTORY_PATH = path.join(os.homedir(), '.atris', 'deck-history.jsonl');
 
-// Short, stable content hash of a spec — same spec -> same hash, so you can
+// Short, stable content hash of a spec, same spec -> same hash, so you can
 // tell a no-op rebuild from a real change.
 function specHash(spec) {
   return crypto.createHash('sha256').update(JSON.stringify(spec || {})).digest('hex').slice(0, 12);

package/lib/deck-layout.js

@@ -1,4 +1,4 @@
-// Layout planner — map content shapes to slide archetypes deterministically.
+// Layout planner, map content shapes to slide archetypes deterministically.
 //
 // Agents (and `atris deck compose`) describe a deck as an ordered list of
 // SECTIONS, each tagged with a `kind` (cover, quote, points, compare, metrics,

package/lib/deck-review.js

@@ -1,4 +1,4 @@
-// Deck review loop — build -> thumbnail fetch -> agent visual review -> confirm.
+// Deck review loop, build -> thumbnail fetch -> agent visual review -> confirm.
 //
 // Agents should not call a deck "ready" until thumbnails pass visual review.
 // This module downloads slide PNGs via the Atris Google Slides API and writes
@@ -58,7 +58,7 @@ const BOXED_TYPES = new Set(['panel', 'receipt', 'versus', 'metricgrid', 'stack'
 
 // Clip thresholds. `warn` = check the thumbnail; `error` = it will clip or lose
 // content, so block the build. `caps` mirror the .slice() limits the engine
-// applies — exceeding one silently drops content, which is always an error.
+// applies, exceeding one silently drops content, which is always an error.
 // Pass `lintSpec(spec, { limits })` to override any of these.
 const CLIP_LIMITS = {
   statementSubWarn: 130,
@@ -80,7 +80,7 @@ function lintSpec(spec, opts = {}) {
         severity: 'error',
         slide: slideNo,
         rule: 'content-truncated',
-        message: `${count} ${label} but only ${cap} render; ${count - cap} will be dropped — split the slide`,
+        message: `${count} ${label} but only ${cap} render; ${count - cap} will be dropped, split the slide`,
       });
     }
   };
@@ -227,7 +227,7 @@ function lintSpec(spec, opts = {}) {
           severity: 'warn',
           slide: slideNo,
           rule: 'stack-sub-clip',
-          message: 'Four-layer stack plus a sub: the sub renders below the slide edge — drop a layer or the sub',
+          message: 'Four-layer stack plus a sub: the sub renders below the slide edge, drop a layer or the sub',
         });
       }
       if (layerCount >= 3) {
@@ -253,7 +253,7 @@ function lintSpec(spec, opts = {}) {
       severity: 'warn',
       slide: 0,
       rule: 'template-fatigue',
-      message: `${boxedCount} boxed slides — consider narrative types: interstitial, lede, prose, split, statement, bignumber`,
+      message: `${boxedCount} boxed slides, consider narrative types: interstitial, lede, prose, split, statement, bignumber`,
     });
   }
   return findings;

package/lib/deck-schema.js

@@ -1,4 +1,4 @@
-// Deck spec schema validation — catch a bad spec before it hits the Slides API.
+// Deck spec schema validation: catch a bad spec before it hits the Slides API.
 //
 // lintSpec (lib/deck-review.js) judges *taste* (clip risk, template fatigue,
 // AI-tell copy). validateSpec judges *shape*: unknown slide types, missing

package/lib/default-verifier.js

@@ -10,7 +10,7 @@ const DEFAULT_MISSION_VERIFIER_TIMEOUT_MS = 120000;
 // default is a proven footgun: in atrisos-backend `npm test` runs
 // backend/scripts/test_fast.sh, which fails without its env and killed missions
 // after two ticks (2026-07-16). A default the operator never chose must be a
-// check that reflects the mission's own work, not the whole repo's health — so
+// check that reflects the mission's own work, not the whole repo's health, so
 // the mission lane falls back to the always-safe `git diff --check` and leaves
 // broad suites to explicit `--verify`. Fleet/wish keep the suite default.
 function resolveDefaultVerifier(root = process.cwd(), { allowBroadSuite = true } = {}) {

package/lib/developer-api.js

@@ -62,6 +62,9 @@ function formatDollars(amount) {
   return `$${n.toFixed(2)}`;
 }
 
+// normalizeBalance is the only in-repo caller; keep the helper internal and
+// stop exporting it so the repo-hygiene ratchet stays green.
+
 function normalizeBalance(data = {}) {
   const raw = data && typeof data === 'object' ? data : {};
   const credits = Number(raw.balance != null ? raw.balance : raw.credits);

package/lib/engine-ask.js

@@ -24,13 +24,13 @@ const DEFAULT_ASK_CONCURRENCY = 3;
 const DEFAULT_ASK_TIMEOUT_MS = 120000;
 const MAX_ASK_CONCURRENCY = 4;
 const MAX_ASK_JOBS = 8;
-const MAX_ASK_TIMEOUT_MS = 10 * 60 * 1000;
-const DEFAULT_FABLE_ASK_TIMEOUT_MS = MAX_ASK_TIMEOUT_MS;
+const DEFAULT_FABLE_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_ASK_TIMEOUT_MS = 60 * 60 * 1000;
 const MAX_ASK_PROMPT_BYTES = 16 * 1024;
 const MAX_ASK_TOTAL_PROMPT_BYTES = 64 * 1024;
 const MAX_ASK_OUTPUT_BYTES = 1024 * 1024;
 const ASK_STOP_GRACE_MS = 250;
-const ASK_MODEL_ENGINES = new Set(['claude', 'fable', 'haiku', 'codex', 'cursor', 'devin', 'grok', 'agy']);
+const ASK_MODEL_ENGINES = new Set(['claude', 'fable', 'haiku', 'codex', 'cursor', 'devin', 'grok', 'agy', 'opencode', 'commandcode']);
 const READ_ONLY_PREAMBLE = [
   'This is a read-only request.',
   'Do not modify files, create worktrees, start background agents, or run commands with side effects.',
@@ -49,6 +49,9 @@ function askUsage() {
     `  --timeout <sec>    per-engine timeout, 1-${MAX_ASK_TIMEOUT_MS / 1000} (default ${DEFAULT_ASK_TIMEOUT_MS / 1000}; Fable ${DEFAULT_FABLE_ASK_TIMEOUT_MS / 1000})`,
     '  --json             print the receipt as json',
     '',
+    'long jobs: set --timeout explicitly; agy receives the same print deadline.',
+    'watch a running receipt from another shell: atris engine watch latest',
+    '',
     `jobs files contain up to ${MAX_ASK_JOBS} objects: [{"engine":"codex","model":"optional","prompt":"question","label":"optional"}]`,
   ].join('\n');
 }
@@ -202,7 +205,9 @@ function resolveAskModel(engine, modelName = '') {
   return RUNNER_PROFILE_DEFS[engine]?.model || DEFAULT_CLAUDE_RUNNER_MODEL;
 }
 
-function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '') {
+function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
+  timeoutMs = DEFAULT_ASK_TIMEOUT_MS,
+} = {}) {
   const engine = canonicalEngineName(engineName);
   const profile = RUNNER_PROFILE_DEFS[engine];
   if (!profile) throw new Error(`unknown engine "${engineName}"`);
@@ -258,9 +263,28 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '') {
     return {
       engine,
       bin: profile.bin,
-      args: ['--mode', 'plan', '--sandbox', '--dangerously-skip-permissions', ...(model ? ['--model', model] : []), '-p', request],
+      args: [
+        '--mode', 'plan',
+        '--sandbox',
+        '--dangerously-skip-permissions',
+        '--print-timeout', `${Math.max(1, Math.ceil(timeoutMs / 1000))}s`,
+        ...(model ? ['--model', model] : []),
+        '-p', request,
+      ],
     };
   }
+  if (engine === 'commandcode') {
+    // Headless print mode blocks file edits and shell commands by default,
+    // so plain -p is already read-only; no sandbox flags needed. Default is
+    // no --model: the run rides this machine's configured Command Code
+    // default, with an explicit ask --model still honored.
+    return { engine, bin: profile.bin, args: ['-p', request, ...(model ? ['--model', model] : [])] };
+  }
+  if (engine === 'opencode') {
+    // `run` with a message is headless print mode; the built-in plan agent
+    // keeps the ask read-only (verified live 2026-08-21, ~7s per lookup).
+    return { engine, bin: profile.bin, args: ['--agent', 'plan', ...(model ? ['-m', model] : []), request] };
+  }
   throw new Error(`engine ask has no read-only command for ${engine}`);
 }
 
@@ -292,6 +316,14 @@ function cancelledAskResult(job, extra = {}) {
   };
 }
 
+function normalizeAskResult(engine, result = {}) {
+  const output = `${String(result.stdout || '')}\n${String(result.stderr || '')}`;
+  if (engine === 'agy' && !result.cancelled && /timeout waiting for response/i.test(output)) {
+    return { ...result, ok: false, reason: 'timeout', timed_out: true };
+  }
+  return result;
+}
+
 function osAccountName() {
   try {
     return String(os.userInfo().username || '').trim();
@@ -448,7 +480,7 @@ async function runEngineAskJobs(jobs, {
   const answers = new Array(jobs.length);
   let nextIndex = 0;
   const execute = executeAskJob || (async (job) => {
-    const invocation = buildReadOnlyEngineInvocation(job.engine, job.prompt, job.model);
+    const invocation = buildReadOnlyEngineInvocation(job.engine, job.prompt, job.model, { timeoutMs });
     return runAskProcess(invocation, { cwd: invocation.cwd || root, timeoutMs, signal, onOutputChunk });
   });
   const workerCount = Math.min(concurrency, jobs.length);
@@ -465,7 +497,8 @@ async function runEngineAskJobs(jobs, {
       }
       try {
         assertAskModelSupported(job.engine, job.model);
-        answers[index] = { ...job, ...(await execute(job, { root, timeoutMs, index, signal, onOutputChunk })) };
+        const result = await execute(job, { root, timeoutMs, index, signal, onOutputChunk });
+        answers[index] = { ...job, ...normalizeAskResult(job.engine, result) };
       } catch (error) {
         answers[index] = {
           ...job,
@@ -586,12 +619,17 @@ async function runEngineAskCommand(args, root = process.cwd(), deps = {}) {
     started_at: startedAt,
     at: startedAt,
     read_only: true,
+    timeout_ms: parsed.timeoutMs,
   };
   const receiptPath = (deps.createReceipt || createEngineAskReceipt)(root, runningReceipt);
   const relativeReceiptPath = path.relative(root, receiptPath) || receiptPath;
   const liveLogPath = (deps.createLiveLog || createEngineLiveLog)(receiptPath);
   runningReceipt.live_log = path.relative(root, liveLogPath) || liveLogPath;
   (deps.updateReceipt || atomicWriteEngineAskReceipt)(receiptPath, runningReceipt);
+  if (!parsed.json) {
+    console.log(`engine ask started: ${relativeReceiptPath}`);
+    console.log(`watch: atris engine watch ${path.basename(receiptPath, '.json')}`);
+  }
   const appendLiveLog = deps.appendLiveLog
     || ((filePath, chunk) => appendEngineLiveLogChunk(filePath, chunk));
   let interruptedSignal = '';