atris 3.38.0 → 3.41.0

package/lib/engine-registry.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const childProcess = require('child_process');
 const {
   RUNNER_PROFILE_DEFS,
   RUNNER_PROFILE_ALIASES,
@@ -13,30 +13,33 @@ const { rankEnginesDetailed, routerPickExplanation } = require('./router-brain')
 const ENGINE_REGISTRY_SCHEMA = 'atris.engine_registry.v2';
 const ENGINE_TIERS = Object.freeze(['fast', 'pro', 'max']);
 const ENGINE_ROLES = Object.freeze(['navigator', 'executor', 'validator']);
+const ENGINE_DUTIES = Object.freeze(['leader', 'errands', 'learning']);
 const ENGINE_HEALTH_STATUSES = Object.freeze(['ready', 'not_installed', 'credit_out', 'error']);
 
 const ENGINE_SEED_META = Object.freeze({
-  'atris-fast': Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator']), fallback_order: 10 }),
-  codex: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), fallback_order: 10 }),
-  claude: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), fallback_order: 20 }),
-  cursor: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), fallback_order: 30 }),
-  devin: Object.freeze({ tier: 'max', roles: Object.freeze(['executor']), fallback_order: 40 }),
-  grok: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), fallback_order: 45 }),
-  fable: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), fallback_order: 50 }),
-  composer: Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator', 'executor']), fallback_order: 60 }),
-  haiku: Object.freeze({ tier: 'fast', roles: Object.freeze(['validator']), fallback_order: 70 }),
-  hermes: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), fallback_order: 80 }),
-  droid: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), fallback_order: 90 }),
+  'atris-fast': Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator']), models: Object.freeze(['atris fast']), duty: 'learning', fallback_order: 10 }),
+  codex: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['codex']), fallback_order: 10 }),
+  claude: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), models: Object.freeze(['opus 5', 'opus 4.8', 'fable', 'haiku']), fallback_order: 20 }),
+  cursor: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['composer 2.5', 'grok 4.5', 'kimi 3']), fallback_order: 30 }),
+  devin: Object.freeze({ tier: 'max', roles: Object.freeze(['executor']), models: Object.freeze(['built-in router']), duty: 'errands', fallback_order: 40 }),
+  grok: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['grok 4.5']), fallback_order: 45 }),
+  fable: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), models: Object.freeze(['opus 5', 'opus 4.8', 'fable', 'haiku']), duty: 'leader', fallback_order: 50 }),
+  composer: Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator', 'executor']), models: Object.freeze(['composer 2.5']), fallback_order: 60 }),
+  haiku: Object.freeze({ tier: 'fast', roles: Object.freeze(['validator']), models: Object.freeze(['haiku']), fallback_order: 70 }),
+  droid: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['built-in router']), duty: 'errands', fallback_order: 90 }),
 });
 
 function engineRegistryFile(root = process.cwd()) {
   return path.join(root, '.atris', 'state', 'engines.json');
 }
 
+// Machine probe. Routing never calls this on a settled registry: it runs once
+// when an engine first appears (seeding the policy file), at the execution
+// stage right before a spawn, and on the explicit `atris engine doctor`.
 function binInstalled(bin) {
   const safe = String(bin || '').replace(/[^A-Za-z0-9_.-]/g, '');
   if (!safe) return false;
-  const probe = spawnSync('sh', ['-c', `command -v ${safe}`], { encoding: 'utf8' });
+  const probe = childProcess.spawnSync('sh', ['-c', `command -v ${safe}`], { encoding: 'utf8' });
   return probe.status === 0 && Boolean(String(probe.stdout || '').trim());
 }
 
@@ -68,6 +71,18 @@ function normalizeRoles(value, fallback = ['executor']) {
   return filtered.length ? filtered : fallback;
 }
 
+function normalizeModels(value, fallback = []) {
+  const models = Array.isArray(value) ? value.map((model) => String(model || '').trim()) : [];
+  const filtered = models.filter((model, index) => model && models.indexOf(model) === index);
+  return filtered.length ? filtered : fallback;
+}
+
+function normalizeDuty(value, fallback = '') {
+  if (value === undefined) return fallback || '';
+  const duty = String(value || '').trim();
+  return ENGINE_DUTIES.includes(duty) ? duty : '';
+}
+
 function normalizeFallbackOrder(value, fallback) {
   const order = Number(value);
   return Number.isInteger(order) ? order : fallback;
@@ -75,22 +90,32 @@ function normalizeFallbackOrder(value, fallback) {
 
 function normalizeEngineEntry(id, saved = {}) {
   const def = RUNNER_PROFILE_DEFS[id];
-  const seed = ENGINE_SEED_META[id] || { tier: 'pro', roles: ['executor'], fallback_order: 100 };
-  const installed = binInstalled(def.bin);
+  const seed = ENGINE_SEED_META[id] || { tier: 'pro', roles: ['executor'], models: [id], fallback_order: 100 };
   const savedHealth = saved && saved.health && typeof saved.health === 'object' ? saved.health : {};
   const savedStatus = String(savedHealth.status || '').trim();
-  const savedFailure = savedStatus === 'credit_out'
-    || savedStatus === 'error'
-    || (savedStatus === 'not_installed' && Boolean(savedHealth.last_failure_ts));
-  const status = savedFailure ? savedStatus : (installed ? 'ready' : 'not_installed');
+  // Policy over probes: a saved health status is the routing truth, verbatim.
+  // Only an engine the registry has never seen gets one seeding probe; after
+  // that, installed-state changes flow through `atris engine doctor` (or
+  // `atris engine health`), never through the resolve path.
+  let status;
+  let installed;
+  if (ENGINE_HEALTH_STATUSES.includes(savedStatus)) {
+    status = savedStatus;
+    installed = typeof saved.installed === 'boolean' ? saved.installed : status !== 'not_installed';
+  } else {
+    installed = binInstalled(def.bin);
+    status = installed ? 'ready' : 'not_installed';
+  }
   const health = { status };
-  if (savedFailure && savedHealth.last_failure_ts) health.last_failure_ts = String(savedHealth.last_failure_ts);
+  if (status !== 'ready' && savedHealth.last_failure_ts) health.last_failure_ts = String(savedHealth.last_failure_ts);
   return {
     id,
     name: id,
     bin: def.bin,
     tier: normalizeTier(saved.tier, seed.tier),
     roles: normalizeRoles(saved.roles, Array.from(seed.roles)),
+    models: normalizeModels(saved.models, Array.from(seed.models)),
+    duty: normalizeDuty(saved.duty, seed.duty),
     fallback_order: normalizeFallbackOrder(saved.fallback_order, seed.fallback_order),
     installed,
     health,
@@ -118,6 +143,62 @@ function writeEngineRegistry(root, registry) {
   fs.writeFileSync(file, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
 }
 
+function setEngineOverrides(name, overrides = {}, root = process.cwd()) {
+  const id = canonicalEngineName(name);
+  const knownIds = RUNNER_PROFILE_NAMES.filter((engineId) => ENGINE_SEED_META[engineId]);
+  if (!id || !knownIds.includes(id)) {
+    throw new Error(`Unknown engine "${name}". Known engines: ${knownIds.join(', ')}`);
+  }
+
+  const nextOverrides = {};
+  if (Object.prototype.hasOwnProperty.call(overrides, 'duty')) {
+    const duty = String(overrides.duty || '').trim();
+    if (!ENGINE_DUTIES.includes(duty)) {
+      throw new Error(`Unknown duty "${overrides.duty}". Known duties: ${ENGINE_DUTIES.join(', ')}`);
+    }
+    nextOverrides.duty = duty;
+  }
+  if (Object.prototype.hasOwnProperty.call(overrides, 'models')) {
+    const models = normalizeModels(overrides.models, []);
+    if (!models.length) throw new Error('models must include at least one name');
+    nextOverrides.models = models;
+  }
+  if (!Object.keys(nextOverrides).length) throw new Error('set requires --duty or --models');
+
+  const file = engineRegistryFile(root);
+  const raw = readRawRegistry(file);
+  const savedById = new Map();
+  for (const entry of raw.engines || []) {
+    const savedId = canonicalEngineName(entry && (entry.id || entry.name));
+    if (savedId && knownIds.includes(savedId)) savedById.set(savedId, entry);
+  }
+
+  if (nextOverrides.duty === 'leader' || nextOverrides.duty === 'learning') {
+    for (const engineId of knownIds) {
+      if (engineId === id) continue;
+      const saved = savedById.get(engineId) || {};
+      const effectiveDuty = Object.prototype.hasOwnProperty.call(saved, 'duty')
+        ? normalizeDuty(saved.duty, '')
+        : normalizeDuty(undefined, ENGINE_SEED_META[engineId].duty);
+      if (effectiveDuty === nextOverrides.duty) {
+        savedById.set(engineId, { ...saved, id: engineId, name: engineId, duty: '' });
+      }
+    }
+  }
+
+  const saved = savedById.get(id) || {};
+  savedById.set(id, { ...saved, id, name: id, ...nextOverrides });
+  const ordered = knownIds.map((engineId) => savedById.get(engineId)).filter(Boolean);
+  const next = {
+    ...raw,
+    schema: ENGINE_REGISTRY_SCHEMA,
+    updated_at: new Date().toISOString(),
+    engines: ordered,
+  };
+  writeEngineRegistry(root, next);
+  return { id, ...nextOverrides };
+}
+
 function readEngineRegistry(root = process.cwd(), options = {}) {
   const registry = seededRegistry(root);
   if (options.persist !== false) writeEngineRegistry(root, registry);
@@ -159,6 +240,8 @@ function resolveEngineForRoleRanked(role, root = process.cwd(), options = {}) {
   const ranked = rankEnginesDetailed(engines, {
     root,
     taskType: options.taskType || options.task_type || normalizedRole,
+    lowStakes: options.lowStakes,
+    stakes: options.stakes,
   });
   return {
     engine: ranked.candidates[0] || null,
@@ -224,17 +307,55 @@ function setEngineHealth(name, status, root = process.cwd()) {
   return engines.find((engine) => engine.id === id);
 }
 
+// Execution-stage guard. Routing hands out engines from policy without ever
+// touching the machine, so the moment we are about to spawn one is where a
+// missing binary has to fail loudly, in one plain sentence naming the binary.
+function requireEngineBin(engineOrId) {
+  const id = typeof engineOrId === 'string'
+    ? canonicalEngineName(engineOrId)
+    : canonicalEngineName(engineOrId && engineOrId.id);
+  const def = RUNNER_PROFILE_DEFS[id];
+  if (!def) {
+    throw new Error(`Unknown engine "${engineOrId && engineOrId.id ? engineOrId.id : engineOrId}". Known engines: ${RUNNER_PROFILE_NAMES.join(', ')}`);
+  }
+  if (!binInstalled(def.bin)) {
+    throw new Error(`${id} CLI (${def.bin}) is not installed here, so this run cannot start.`);
+  }
+  return def.bin;
+}
+
+// The explicit opt-in probe pass: check every engine binary on this machine,
+// fold the result back into the policy file (a ready/not_installed flip only;
+// credit_out and error are operator policy and survive), and report.
+function engineDoctorReport(root = process.cwd()) {
+  const registry = readEngineRegistry(root, { persist: false });
+  const engines = registry.engines.map((engine) => {
+    const installed = binInstalled(engine.bin);
+    let health = engine.health && engine.health.status ? engine.health : { status: installed ? 'ready' : 'not_installed' };
+    if (installed && health.status === 'not_installed') health = { status: 'ready' };
+    if (!installed && health.status === 'ready') health = { status: 'not_installed' };
+    return { ...engine, installed, health };
+  });
+  const next = { ...registry, updated_at: new Date().toISOString(), engines };
+  writeEngineRegistry(root, next);
+  return engines;
+}
+
 module.exports = {
   ENGINE_ROLES,
+  ENGINE_DUTIES,
   ENGINE_HEALTH_STATUSES,
   engineRegistryFile,
   binInstalled,
   canonicalEngineName,
   readEngineRegistry,
+  requireEngineBin,
+  engineDoctorReport,
   engineRegistryView,
   resolveRegisteredEngine,
   resolveEngineForRoleRanked,
   resolveEngineForRole,
   resolveEngineForRoleWithPreference,
+  setEngineOverrides,
   setEngineHealth,
 };

package/lib/falsifier-probe.js

@@ -0,0 +1,84 @@
+'use strict';
+
+// A check that cannot fail is not a check. `task ready --verify` runs a command
+// and accepts the work on exit 0, which catches a command that fails but never
+// catches one that could not have failed. The 2026-07-26 reward-ledger audit
+// found 131 of 802 accepted proofs carrying nothing falsifiable.
+//
+// The probe: run the same command again in an empty directory, with none of
+// the work present. A check anchored to this codebase fails there. One that
+// passes anywhere - `true`, `echo done`, a check of something outside the
+// repo - passes there too, and proves nothing about the work.
+//
+// Scope, stated plainly: this asks whether a check depends on the codebase at
+// all. It does not ask whether the check exercises the change. `git diff
+// --check` fails in an empty directory and still says nothing about whether
+// the code works, so it clears this probe. The probe raises the floor; it is
+// not a ceiling.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PROBE_TIMEOUT_MS = 60_000;
+
+// An absolute path reaches back into a real checkout no matter where the
+// command runs, so the empty directory proves nothing about it. Say so rather
+// than reporting a false verdict.
+function absolutePathIn(command) {
+  const match = String(command || '').match(/(?:^|[\s"'`=(])(\/[^\s"'`)]+)/);
+  return match ? match[1] : '';
+}
+
+function probeVerifierCanFail({ command, runner, tmpRoot } = {}) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return { probed: false, canFail: null, reason: 'no command to probe' };
+
+  const absolute = absolutePathIn(cmd);
+  if (absolute) {
+    return {
+      probed: false,
+      canFail: null,
+      reason: `not probed: the command reaches an absolute path (${absolute}), so running it away from this checkout proves nothing`,
+    };
+  }
+
+  const dir = fs.mkdtempSync(path.join(tmpRoot || os.tmpdir(), 'atris-falsifier-probe-'));
+  try {
+    const run = runner || spawnSync;
+    const result = run('bash', ['-lc', cmd], {
+      cwd: dir,
+      encoding: 'utf8',
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    if (result.error) {
+      const timedOut = /ETIMEDOUT/i.test(String(result.error.code || result.error.message || ''));
+      return {
+        probed: false,
+        canFail: null,
+        reason: timedOut
+          ? `not probed: the command ran past ${PROBE_TIMEOUT_MS / 1000}s with none of the work present`
+          : `not probed: the command could not start away from this checkout (${result.error.message})`,
+      };
+    }
+    if (result.status === 0) {
+      return {
+        probed: true,
+        canFail: false,
+        exit: 0,
+        reason: 'this check passes in an empty directory, with none of the work present, so passing here says nothing about the work',
+      };
+    }
+    return {
+      probed: true,
+      canFail: true,
+      exit: result.status,
+      reason: 'this check fails when the work is absent, so passing it means something',
+    };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { probeVerifierCanFail, absolutePathIn, PROBE_TIMEOUT_MS };

package/lib/fleet.js

@@ -24,13 +24,15 @@ const {
 } = require('./brief-ledger');
 const { RUNNER_PROFILE_DEFS, buildRunnerCommand } = require('./runner-command');
 const { resolveDefaultVerifier } = require('./default-verifier');
-const { rankEngines } = require('./router-brain');
+const { rankEnginesDetailed } = require('./router-brain');
 const {
   buildOneLapValidatorPrompt,
   parseOneLapValidatorVerdict,
 } = require('./one-lap-validator');
 const { listWorktrees } = require('../commands/worktree');
 const { isConductorStatusLine } = require('./conductor-artifacts');
+const { matchLessons } = require('./lesson-preflight');
+const { matchTaste } = require('./taste-lessons');
 
 // Lanes a fleet may never staff on its own: the human keeps irreversible
 // calls. Mirrors the autoland denied lanes.
@@ -94,6 +96,30 @@ function buildFleetPrompt(task, { worktreePath, yolo = false } = {}) {
     '',
     'Final report (plain text): files changed, test command + result, commit sha (or say the commit failed and why).'
   );
+  const lessonFiles = [
+    ...(Array.isArray(task.files) ? task.files : []),
+    ...(Array.isArray(task.metadata && task.metadata.files) ? task.metadata.files : []),
+    ...fileSurface(task),
+  ];
+  const briefText = lines.join('\n');
+  const preflightRoot = worktreePath || process.cwd();
+  const lessons = matchLessons({
+    briefText,
+    files: lessonFiles,
+    root: preflightRoot,
+  });
+  if (lessons.length) {
+    lines.push('', '## lessons that apply', ...lessons.map((lesson) => `- ${lesson.text}`));
+  }
+  const requestedTasteScope = String(
+    task.scope || (task.metadata && task.metadata.scope) || task.tag || 'any'
+  ).toLowerCase();
+  const taste = matchTaste({ briefText, scope: requestedTasteScope, root: preflightRoot });
+  if (taste.length) {
+    lines.push('', "## the owner's taste", ...taste.map((entry) => (
+      `- The operator's verdict is ${entry.verdict} for "${entry.subject}". The reason is: ${entry.why}`
+    )));
+  }
   return lines.join('\n');
 }
 
@@ -396,13 +422,18 @@ function installedFleetEngines(root) {
   return normalizeInstalledEngines(roster(root).filter((e) => e.installed));
 }
 
-function rankFleetEngines(engines, root = process.cwd()) {
-  return rankEngines(normalizeInstalledEngines(engines), {
+function rankFleetEnginesDetailed(engines, root = process.cwd(), options = {}) {
+  return rankEnginesDetailed(normalizeInstalledEngines(engines), {
     root,
     taskType: 'executor',
+    lowStakes: options.lowStakes === true,
   });
 }
 
+function rankFleetEngines(engines, root = process.cwd()) {
+  return rankFleetEnginesDetailed(engines, root).candidates;
+}
+
 function nextInstalledFleetEngine(current, { root = process.cwd(), installedEngines = null } = {}) {
   const engines = installedEngines ? normalizeInstalledEngines(installedEngines) : installedFleetEngines(root);
   const currentName = String(current || '').trim();
@@ -570,27 +601,30 @@ function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), ti
 // ---------------------------------------------------------------------------
 // T2 — staffing
 
+const {
+  taskTagTokens,
+  isDecisionHoldTag,
+  isDecisionTask,
+  DECISION_REFUSE_REASON,
+} = require('./task-decision');
+
 function taskTags(task) {
-  const fromTags = Array.isArray(task.tags) ? task.tags : [];
-  const fromTag = task && task.tag ? [task.tag] : [];
   // Tags added after creation live in metadata.tags (`atris task tag`); a
   // fleet that only read task.tags/title hashtags would ignore an owner-hold
   // flag stamped on a live task and keep restaffing it (CLI-879).
-  const fromMeta = task && task.metadata && Array.isArray(task.metadata.tags) ? task.metadata.tags : [];
-  const fromTitle = (String(task.title || '').match(/#([a-z0-9-]+)/gi) || []).map((t) => t.slice(1));
-  return [...fromTag, ...fromTags, ...fromMeta, ...fromTitle].map((t) => String(t).toLowerCase());
+  return taskTagTokens(task);
 }
 
 // A task flagged for a human decision is never fleet-staffable, whatever its
-// lane. Mirrors the sweep's needs-human hold so both loops agree.
+// lane. Mirrors the sweep's needs-human hold so both loops agree. Also honors
+// the clearer `decision` tag so policy questions stay off autonomous lanes.
 function isHumanHoldTag(tag) {
-  const normalized = String(tag).trim().toLowerCase().replace(/_/g, '-');
-  return normalized === 'needs-human' || normalized === 'needshuman';
+  return isDecisionHoldTag(tag);
 }
 
 function isSafeLane(task) {
+  if (isDecisionTask(task)) return false;
   const tags = taskTags(task);
-  if (tags.some(isHumanHoldTag)) return false;
   return !tags.some((t) => DENIED_TAGS.includes(t));
 }
 
@@ -822,9 +856,12 @@ module.exports = {
   isSafeLane,
   taskTags,
   nextInstalledFleetEngine,
+  rankFleetEnginesDetailed,
   dispatchToEngine,
   taskTags,
   isHumanHoldTag,
+  isDecisionTask,
+  DECISION_REFUSE_REASON,
   isSafeLane,
   staffFlight,
   assignEngines,
@@ -2105,15 +2142,24 @@ async function runFleetFlight({
   guardCliLink = guardGlobalCliLink,
 } = {}) {
   const cli = ownCli || defaultOwnCli(root);
-  const roster = engines || (() => {
+  // Staff first, rank second: every task staffFlight returns already cleared
+  // the safe-lane filter (not a decision row, no denied tags), so the rank
+  // that pairs engines to those tasks is low stakes and the stretch zone
+  // rule may trade the strongest engine for the cheapest learnable one.
+  // Protected or denied work never reaches staffFlight's output, so it never
+  // gets the flag; when nothing is staffed there is no task to rank for and
+  // the flag stays off.
+  const staffedTasks = staffFlight(readProjectionTasks(root), { slots });
+  const rosterDetail = engines ? null : (() => {
     const { roster: fullRoster } = require('../commands/engine');
     const installed = fullRoster(root)
       .filter((e) => e.installed && FLEET_CAPABLE.includes(e.name))
       .map((e) => e.name);
-    return rankFleetEngines(installed, root);
+    return rankFleetEnginesDetailed(installed, root, { lowStakes: staffedTasks.length > 0 });
   })();
+  const roster = engines || rosterDetail.candidates;
 
-  const staffed = assignEngines(staffFlight(readProjectionTasks(root), { slots }), roster);
+  const staffed = assignEngines(staffedTasks, roster);
   // The receipt path is decided BEFORE landings so each task's ready-proof
   // can cite it — the proof policy certifies receipt-backed proofs agent-side.
   const receiptPath = path.join(root, 'atris', 'runs', `fleet-${nowStamp()}.json`);
@@ -2123,10 +2169,14 @@ async function runFleetFlight({
     slots,
     roster,
     staffed: staffed.map((s) => ({ task: s.task.display_id, title: String(s.task.title || '').slice(0, 140), engine: s.engine, surface: s.surface })),
+    stretch_zone_pick: rosterDetail && rosterDetail.stretch_zone_pick ? rosterDetail.stretch_zone_pick : null,
     results: [],
     landed: [],
     paused: [],
   };
+  if (flight.stretch_zone_pick) {
+    flight.stretch_zone_note = `low-stakes staffing picked ${flight.stretch_zone_pick} from the stretch zone: the cheapest engine with a learnable track record won this lane.`;
+  }
 
   log('');
   log(`  fleet — ${roster.length} engine${roster.length === 1 ? '' : 's'} ready, ${staffed.length} task${staffed.length === 1 ? '' : 's'} staffed`);

package/lib/git-spawn.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// One synchronous git runner for commands that shell out to git.
+// check: true throws on a non-zero exit; check: false hands back the raw result.
+function runGit(args, { cwd = process.cwd(), check = true, maxBuffer } = {}) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', ...(maxBuffer ? { maxBuffer } : {}) });
+  if (check && result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return result;
+}
+
+module.exports = { runGit };

package/lib/json-file.js

@@ -0,0 +1,37 @@
+// Shared JSON file read/write so every call site fails the same way.
+//
+// Bare `JSON.parse(fs.readFileSync(...))` drifted across commands: some sites
+// caught, some returned null, some returned {}. These two helpers keep the
+// tolerant shape in one place.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read and parse a JSON file, returning `fallback` when it is missing or corrupt.
+ * @param {string} filePath
+ * @param {*} [fallback=null]
+ * @returns {*}
+ */
+function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Write a value as pretty JSON with a trailing newline, creating parent dirs.
+ * @param {string} filePath
+ * @param {*} value
+ * @param {{ indent?: number }} [options]
+ * @returns {string} the path written
+ */
+function writeJson(filePath, value, { indent = 2 } = {}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, indent) + '\n', 'utf8');
+  return filePath;
+}
+
+module.exports = { readJson, writeJson };

package/lib/known-commands.js

@@ -2,8 +2,8 @@
 
 const knownCommands = ['init', 'log', 'logs', 'wish', 'drill', 'dream', 'now', 'goal', 'wtf', 'orb', 'radar', 'stream', 'ctop', 'launchpad', 'status', 'analytics', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', '_start', 'plan', 'do', 'review', 'release',
                        'activate', '_activate', 'agent', 'team', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
-                       'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'teach', 'plugin', 'experiments', 'bench', 'router', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube',
-                       'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'agents', 'probe', 'worktree', 'land', 'autoland', 'drive', 'aeo', 'slop', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
+                       'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'taste', 'teach', 'plugin', 'experiments', 'bench', 'router', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube',
+                       'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'decide', 'agents', 'probe', 'worktree', 'land', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
                        'github', 'vercel', 'supabase', 'linear', 'stripe', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'pack', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'fleet-report', 'loops', 'self-improve', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'feed', 'brief'];