agy-crew 0.0.0-stage → 0.9.2

package/companion/agy-companion.mjs

@@ -0,0 +1,2136 @@
+#!/usr/bin/env node
+/**
+ * agy-companion — the single brain of the agy-crew plugin.
+ *
+ * Wraps Google's Antigravity CLI (`agy`) so Claude Code and OpenAI Codex can
+ * delegate work to Gemini via five modes: staffer (general-purpose), research,
+ * review, implement, ask.
+ *
+ * Subcommands:
+ *   staffer | research | review | implement
+ *                                   run a task as a background job (staffer is
+ *                                   the general-purpose mode: a minimal prompt
+ *                                   with no role or output-format framing)
+ *   ask --prompt <question>         cheap zero-tool one-shot Q&A (foreground)
+ *   continue --prompt <text>        continue the most recent conversation (any mode)
+ *   observe [job-id]                immediate bounded snapshot in every job state
+ *   restart <job-id>                explicitly relaunch the stored task
+ *   status [job-id]                 list background jobs / show one job
+ *   wait [job-id] [--timeout 100s]  block until the job finishes, then print
+ *                                   its result (exit 2 = still running: call
+ *                                   it again)
+ *   result [job-id]                 print the stored output of a finished job
+ *   cancel <job-id>                 kill a running background job
+ *   setup [--apply]                 optional: install the evidence-gathering
+ *                                   command allowlist used by restricted runs
+ *   setup --restrict <modes|none>   optional: per-repo policy — make the listed
+ *                                   modes default to the restricted profile in
+ *                                   this repository (.agy-crew/config.json)
+ *   install [--hosts a,b | --all] [--dry-run] [--json] [--status]
+ *                                   install the skills into the user-level skill
+ *                                   directories of detected harnesses (claude,
+ *                                   codex, omp, opencode, dsh) from one shared
+ *                                   bundle; refuses to overwrite foreign content
+ *                                   or coexist with upstream agy-staff
+ *   uninstall [--hosts a,b | --all] [--json]
+ *                                   remove only the links install created
+ *   accounts <list|login|import|remove|enable|disable|cooldown clear|quota>
+ *                                   manage the pool of private agy logins
+ *   _worker <job-id>                (internal) background job executor
+ *
+ * Uniform flags:
+ *   --job <id>            continue a specific job with its original configuration
+ *   --conversation <id>   resume a specific agy conversation
+ *   --continue            reuse the last conversation id for this mode
+ *   --model <id>          explicit agy model id (overrides --effort)
+ *   --effort <l|m|h>      low|medium|high → gemini-3.8-flash-<effort>
+ *   --account <a>         auto (default) | live | <pool account name>; with an empty
+ *                         pool every run uses your own (live) agy login
+ *   --restricted          hardening opt-in: keep agy's permission enforcement
+ *                         on (wants setup's evidence-gathering allowlist)
+ *   --unrestricted        pass --dangerously-skip-permissions (already the
+ *                         default for research/review/implement)
+ *   --json                (review) ask agy for schema-enforced JSON findings
+ *   --timeout <dur>       background hard limit (default 60m, maximum 120m); ask response timeout
+ *   --prompt <text>       the task text as one opaque argv value
+ *   --prompt-file <path>  read the task text from a file (long prompts)
+ *   --stdin               read the task text from stdin
+ *
+ * Task text for the run commands (staffer/research/review/implement/ask and
+ * continue) comes from exactly one of --prompt, --prompt-file, or --stdin.
+ * argv is parsed once, exactly as the shell delivered it, and the task value
+ * travels whole: never re-split, never scanned. Flag-like text inside a task
+ * (`--check`, `--json`, an unknown `--whatever`) is therefore ordinary prompt
+ * content and reaches agy byte for byte.
+ *
+ * Permissions: all tool-using modes (staffer/research/review/implement) run
+ * unrestricted by default, so they work out of the box with no setup;
+ * --restricted is the hardening opt-in that relies on the evidence-gathering
+ * allowlist installed by `setup`. ask is tool-free and always restricted.
+ * Profile precedence: CLI flag > project policy (.agy-crew/config.json,
+ * written by `setup --restrict`) > built-in default. The policy is a run
+ * policy for per-repo consistency, not a security boundary.
+ * The guardrails against irreversible side effects live in the prompt
+ * templates, backed by two tiered checks here: implement treats dirty
+ * workspaces as bounded prompt context, while staffer/review/research snapshot
+ * `git status --porcelain` around the run and report any delta with the result
+ * without ever blocking.
+ *
+ * Output split: stdout carries the deliverable — agy's response plus any guard
+ * warning about the working tree. The `[agy-crew]` telemetry line (mode,
+ * profile, model, duration, tokens, conversation id) goes to stderr, and for
+ * background jobs into `jobs/<id>.log`; it is metadata for the calling agent,
+ * never something to show the user.
+ *
+ * Execution style is fixed per mode and cannot be overridden: ask runs in the
+ * foreground; staffer/research/review/implement run as detached background
+ * jobs whose output is collected with wait/status/result/cancel.
+ *
+ * Job exit codes (`status <id>` and `wait`): 0 = done, 2 = running (for wait:
+ * still running when its own timeout expired — call it again), 3 = error or
+ * crashed, 4 = canceled, 5 = attention (resumable timeout). 1 stays the generic companion error (bad id, etc.),
+ * so a caller can loop on "exit code 2" with zero output parsing.
+ *
+ * Review is prompt-based: the subject ("Review PR #730", "Review changes
+ * against master") is described in the task text and agy gathers the evidence
+ * itself with its own tools.
+ *
+ * No dependencies beyond the Node standard library.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { PRODUCT, STATE_DIR_NAME } from './identity.mjs';
+import { cmdInstall, cmdUninstall } from './install.mjs';
+import { boundSnapshot, excerpt } from './observation.mjs';
+import { atomicJSON, runStreaming, processIdentity } from './stream-worker.mjs';
+import { withStateLock, replaceFile, readTextRetry } from './state-lock.mjs';
+import { cmdAccounts, poolSettingsFiles } from './accounts.mjs';
+import { acquireRun, boundAccount, preflight, recordCooldown, markAuthError } from './pool/lease.mjs';
+import { classifyFailureText, modelFamily } from './pool/results.mjs';
+import { loadPool, updatePool, poolExists } from './pool/state.mjs';
+
+const SELF = fileURLToPath(import.meta.url);
+const TEMPLATES_DIR = path.join(path.dirname(SELF), '..', 'templates');
+const AGY_BIN = process.env.AGY_BIN || 'agy';
+
+/** How to launch agy. AGY_BIN normally names an executable; when it names a
+ *  Node script (the test fake), run it through the current Node binary so the
+ *  launch does not depend on shebang support (Windows has none: EFTYPE). */
+function agyCommand(args) {
+  if (/\.(mjs|cjs|js)$/i.test(AGY_BIN)) return { cmd: process.execPath, args: [AGY_BIN, ...args] };
+  return { cmd: AGY_BIN, args };
+}
+const AGY_SETTINGS = path.join(os.homedir(), '.gemini', 'antigravity-cli', 'settings.json');
+
+const MODES = ['staffer', 'research', 'review', 'implement', 'ask'];
+
+const DEFAULTS = {
+  model: {
+    staffer: 'gemini-3.8-flash-medium',
+    research: 'gemini-3.8-flash-high',
+    review: 'gemini-3.8-flash-medium',
+    implement: 'gemini-3.8-flash-high',
+    ask: 'gemini-3.8-flash-low',
+  },
+  // Every tool-using mode is unrestricted by default: headless agy denies
+  // unlisted tool calls, so a restricted default made research/review come
+  // back empty until the user ran `setup`. --restricted is the opt-in.
+  // ask is tool-free, so its profile is irrelevant and stays restricted.
+  profile: {
+    staffer: 'unrestricted',
+    research: 'unrestricted',
+    review: 'unrestricted',
+    implement: 'unrestricted',
+    ask: 'restricted',
+  },
+  timeout: { staffer: '60m', research: '60m', review: '60m', implement: '60m', ask: '2m' },
+  // Background-first: only ask (seconds-long, tool-free) stays in the foreground.
+  // No flag overrides this; execution style is a property of the mode.
+  background: { staffer: true, research: true, review: true, implement: true, ask: false },
+};
+
+// agy only accepts effort-suffixed model ids; bare family names are rejected
+// with status ERROR ("--model gemini-3.8-flash requires --effort").
+// Known ids from `agy models` (v1.1.13):
+const KNOWN_MODELS = new Set([
+  'gemini-3.8-flash-high', 'gemini-3.8-flash-medium', 'gemini-3.8-flash-low',
+  'gemini-3.7-flash-high', 'gemini-3.7-flash-medium', 'gemini-3.7-flash-low',
+  'gemini-3.6-flash-high', 'gemini-3.6-flash-medium', 'gemini-3.6-flash-low',
+  'gemini-3.5-flash-high', 'gemini-3.5-flash-medium', 'gemini-3.5-flash-low',
+  'gemini-3.1-pro-high', 'gemini-3.1-pro-low',
+  'claude-sonnet-4-6', 'claude-opus-4-6-thinking', 'gpt-oss-120b-medium',
+]);
+const MODEL_FAMILIES = {
+  'gemini-3.8-flash': ['low', 'medium', 'high'],
+  'gemini-3.7-flash': ['low', 'medium', 'high'],
+  'gemini-3.6-flash': ['low', 'medium', 'high'],
+  'gemini-3.5-flash': ['low', 'medium', 'high'],
+  'gemini-3.1-pro': ['low', 'high'],
+};
+const MODEL_ALIASES = { flash: 'gemini-3.8-flash', pro: 'gemini-3.1-pro' };
+
+/** Normalize a user-supplied --model value to an id agy accepts, or die
+ *  pre-flight with a helpful message. Never lets a bare family reach agy. */
+function normalizeModel(raw, effort) {
+  const name = MODEL_ALIASES[raw] || raw;
+  if (KNOWN_MODELS.has(name)) return name;
+  const efforts = MODEL_FAMILIES[name];
+  if (efforts) {
+    let e = effort || 'medium';
+    if (!efforts.includes(e)) {
+      // e.g. gemini-3.1-pro has no medium: fall back to its highest tier
+      const fallback = efforts[efforts.length - 1];
+      process.stderr.write(`${PRODUCT}: ${name} has no "${e}" effort; using ${name}-${fallback}\n`);
+      e = fallback;
+    }
+    return `${name}-${e}`;
+  }
+  // future-tolerance: pass through anything already effort-suffixed
+  if (/-(low|medium|high|thinking)$/.test(name)) return name;
+  die(
+    `unknown model id "${raw}". agy needs effort-suffixed ids, e.g. ` +
+      `gemini-3.8-flash-low|medium|high, gemini-3.1-pro-low|high. ` +
+      `Aliases accepted here: "flash" (gemini-3.8-flash), "pro" (gemini-3.1-pro), ` +
+      `optionally combined with --effort. Run \`agy models\` for the full list.`
+  );
+}
+
+// Optional GLOBAL setup rules. AGY owns prefix matching and deny precedence;
+// the small deny list prevents common mistakes, not every destructive action.
+const EVIDENCE_ALLOWLIST = [
+  'command(git)',
+  'command(gh)',
+  'command(cat)',
+  'command(head)',
+  'command(ls)',
+  'command(grep)',
+  'command(find)',
+  'command(rg)',
+  'command(wc)',
+];
+const EVIDENCE_DENYLIST = [
+  'command(git push)',
+  'command(git reset --hard)',
+  'command(git clean)',
+  'command(gh pr merge)',
+  'command(gh release delete)',
+];
+
+// ~200KB task-text ceiling; macOS ARG_MAX is ~1MB and the prompt
+// travels as a single argv entry.
+const MAX_INLINE_BYTES = 200 * 1024;
+const MAX_DIRTY_STATUS_LINES = 100;
+const MAX_DIRTY_STATUS_BYTES = 16 * 1024;
+
+const REVIEW_JSON_SCHEMA = JSON.stringify({
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['approve', 'request_changes', 'comment'] },
+    summary: { type: 'string' },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'nit'] },
+          file: { type: 'string' },
+          line: { type: 'string' },
+          title: { type: 'string' },
+          detail: { type: 'string' },
+        },
+        required: ['severity', 'title', 'detail'],
+      },
+    },
+    could_not_verify: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['verdict', 'summary', 'findings', 'could_not_verify'],
+});
+
+// ---------------------------------------------------------------------------
+// small utils
+// ---------------------------------------------------------------------------
+
+let inWorker = false;
+function die(msg, code = 1) {
+  if (inWorker) throw new Error(msg);
+  process.stderr.write(`${PRODUCT} error: ${msg}\n`);
+  throw Object.assign(new Error(msg), { exitCode: code, alreadyPrinted: true });
+}
+
+function sh(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true, ...opts });
+  return { code: r.status ?? -1, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+}
+
+const repoRootCache = new Map();
+function repoRoot() {
+  const cwd = process.cwd();
+  if (repoRootCache.has(cwd)) return repoRootCache.get(cwd);
+  const r = sh('git', ['rev-parse', '--show-toplevel']);
+  // git prints forward slashes even on Windows; normalize so the root compares
+  // equal to process.cwd()-derived paths and reads naturally in agy arguments.
+  const root = r.code === 0 && r.out ? path.normalize(r.out) : cwd;
+  repoRootCache.set(cwd, root);
+  return root;
+}
+
+function stateDir() {
+  return path.join(repoRoot(), STATE_DIR_NAME);
+}
+
+function statePath() {
+  return path.join(stateDir(), 'state.json');
+}
+
+function configPath() {
+  return path.join(stateDir(), 'config.json');
+}
+
+// Modes whose default profile can be set per repo. ask is tool-free and
+// always restricted, so it is not configurable.
+const CONFIGURABLE_MODES = ['staffer', 'research', 'review', 'implement'];
+
+/** Project policy (per-repo default profiles), written by `setup --restrict`.
+ *  Missing file → null. Invalid file → die: a policy that is silently ignored
+ *  is worse than an error. */
+function loadProjectConfig() {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath(), 'utf8');
+  } catch {
+    return null;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch {
+    die(`project config is corrupt: ${configPath()} — fix or delete it, then retry`);
+  }
+  for (const [m, p] of Object.entries(cfg.profiles || {})) {
+    if (!CONFIGURABLE_MODES.includes(m)) {
+      die(
+        `project config: unknown mode "${m}" in ${configPath()} ` +
+          `(configurable: ${CONFIGURABLE_MODES.join(', ')}; ask is always restricted)`
+      );
+    }
+    if (p !== 'restricted' && p !== 'unrestricted') {
+      die(`project config: profile for ${m} must be "restricted" or "unrestricted", got "${p}" (${configPath()})`);
+    }
+  }
+  return cfg;
+}
+
+/** Create .agy-crew/ on first use and keep it out of `git status`.
+ *  .git/info/exclude is repo-local and untracked — never the team's
+ *  .gitignore. Best-effort: a read-only .git must not block a run. */
+function ensureStateDir() {
+  const dir = stateDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    if (sh('git', ['check-ignore', '-q', dir]).code !== 0) {
+      const p = sh('git', ['rev-parse', '--git-path', 'info/exclude']);
+      if (p.code === 0 && p.out) {
+        try {
+          fs.appendFileSync(path.resolve(p.out), STATE_DIR_NAME + '/\n');
+        } catch {}
+      }
+    }
+  }
+  return dir;
+}
+
+function loadState() {
+  let raw;
+  try {
+    raw = readTextRetry(statePath());
+  } catch (error) {
+    // Only a missing file means "no state yet". Anything else must not be
+    // mistaken for an empty state: callers write it back and would wipe jobs.
+    if (error.code === 'ENOENT') return { conversations: {}, last: null, jobs: [] };
+    die(`cannot read state file ${statePath()}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Never silently reset: every caller writes the state back, which would
+    // wipe all job records and conversation ids.
+    die(`state file is corrupt: ${statePath()} — fix or delete it, then retry`);
+  }
+}
+
+function saveState(state) {
+  ensureStateDir();
+  // Atomic replace: a detached worker and a status/result call can read this
+  // file at any moment; a plain truncate-then-write leaves a torn window.
+  const tmp = statePath() + `.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n');
+  replaceFile(tmp, statePath());
+}
+
+function updateState(change) {
+  ensureStateDir();
+  return withStateLock(statePath() + '.lock', () => {
+    const state = loadState();
+    const value = change(state);
+    saveState(state);
+    return value;
+  });
+}
+
+function updateJob(id, fields, terminal = false) {
+  return updateState((state) => {
+    const job = state.jobs?.find((j) => j.id === id);
+    if (!job) throw new Error(`Missing job ${id}`);
+    if (terminal && job.status !== 'running') return job;
+    Object.assign(job, fields);
+    return job;
+  });
+}
+
+function finishJob(id, output, fields) {
+  return updateState((state) => {
+    const job = state.jobs?.find((j) => j.id === id);
+    if (!job) throw new Error(`Missing job ${id}`);
+    if (typeof fields === 'function') fields = fields(job);
+    if (job.status !== 'running' && !(job.status === 'canceled' && fields.status === 'canceled')) return job;
+    if (job.cancel_requested_at && fields.status !== 'canceled') throw Object.assign(new Error('Execution canceled.'), { reason: 'canceled' });
+    const final = { ...fields, finished_at: new Date().toISOString() };
+    const completed = { ...job, ...final };
+    fs.writeFileSync(job.result_file, typeof output === 'function' ? output(completed) : output);
+    atomicJSON(job.result_file + '.status.json', final);
+    Object.assign(job, final);
+    return job;
+  });
+}
+
+function rememberConversation(resolved, id, jobId, account = null) {
+  if (!id) return;
+  updateState((state) => {
+    state.conversations ||= {};
+    state.conversations[resolved.mode] = id;
+    state.last = { mode: resolved.mode, id, model: resolved.model, profile: resolved.profile };
+    state.conversation_configs ||= {};
+    state.conversation_configs[id] = { mode: resolved.mode, model: resolved.model,
+      profile: resolved.profile, cwd: process.cwd(), ...(account ? { account } : {}) };
+    const job = state.jobs?.find((j) => j.id === jobId);
+    if (job) job.conversation_id = id;
+  });
+  bindConversation(id, account);
+}
+
+/** A conversation lives in one account's HOME, so it is bound to that account
+ *  the first time its id is seen. live conversations stay unbound (unbound
+ *  means live). */
+function bindConversation(id, account) {
+  if (!account || account === 'live') return;
+  updatePool((pool) => {
+    pool.conversations[id] ||= { account, recorded_at: new Date().toISOString() };
+  });
+}
+
+function pidAlive(pid) {
+  if (pid == null) return true; // registered, pid backfill pending — treat as running
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+const VALUE_FLAGS = new Set(['job', 'conversation', 'model', 'effort', 'timeout', 'restrict', 'prompt', 'prompt-file', 'hosts', 'account', 'family', 'home']);
+const BOOL_FLAGS = new Set(['continue', 'restricted', 'unrestricted', 'json', 'apply', 'dry-run', 'stdin', 'all', 'status', 'yes', 'refresh']);
+
+// Flags dropped in 0.2. They get their own error instead of falling through to
+// "unknown flag", so a 0.1 caller learns what replaced them.
+const REMOVED_REVIEW_FLAGS = new Set(['diff-file', 'pr', 'target']);
+const REMOVED_EXEC_FLAGS = new Set(['background', 'wait']);
+
+// Deprecated 0.1 spellings, kept for one release and undocumented.
+const FLAG_ALIASES = { strict: 'restricted', loose: 'unrestricted' };
+const warnedAliases = new Set();
+
+function migrationDie(name) {
+  if (REMOVED_REVIEW_FLAGS.has(name)) {
+    die(
+      `--${name} was removed in 0.2: review is prompt-based now. Describe the subject in the prompt, ` +
+        `e.g. \`review --prompt "Review PR #730"\` or \`review --prompt "Review changes against master"\`.`
+    );
+  }
+  die(
+    `--${name} was removed in 0.2: execution style is fixed per mode (ask runs in the foreground; ` +
+      `research/review/implement run as background jobs). Use status/result/cancel to manage jobs.`
+  );
+}
+
+/** A flag name that still contains whitespace means the caller packed several
+ *  arguments (and usually the task) into one quoted string. The companion does
+ *  not split argument strings, so say so and name the fix. */
+function packedArgumentDie(name, raw) {
+  const first = name.split(/\s+/)[0] || '';
+  const shown = raw.length > 60 ? `${raw.slice(0, 60)}…` : raw;
+  die(
+    `unknown flag --${first}: the whole string "${shown}" arrived as a single argument. ` +
+      `${PRODUCT} parses argv exactly as the shell delivers it and never splits an argument into flags — ` +
+      `pass each flag as its own argument and put the task text in --prompt, ` +
+      `e.g. \`review --restricted --prompt "Review PR #730"\`.`
+  );
+}
+
+/** Reject a value flag whose value is missing, empty, or itself flag-shaped.
+ *  An empty value is a caller mistake worth surfacing rather than a default
+ *  request, and a flag-shaped value almost always means the value was
+ *  forgotten (`ask --prompt --json`). The one exception is
+ *  --prompt with a value containing whitespace: that is a real sentence that
+ *  happens to start with `--`, and prompt bytes are never second-guessed. */
+function checkValue(name, v) {
+  if (v === undefined || v === '') die(`flag --${name} needs a value`);
+  if (!v.startsWith('--')) return;
+  if (name === 'prompt') {
+    if (/\s/.test(v)) return;
+    die(
+      `flag --prompt needs a value (if your prompt really starts with --, ` +
+        `quote the full sentence or use --prompt-file)`
+    );
+  }
+  die(`flag --${name} needs a value`);
+}
+
+/**
+ * Parse the shell's argv once. Values are taken verbatim: nothing is re-split,
+ * no quotes are interpreted, no byte of a value is inspected for flags.
+ *
+ * `taskCommand` only changes what a positional means. Run commands take their
+ * task from --prompt/--prompt-file/--stdin, so a positional there is a caller
+ * mistake and dies loudly. Management commands (status/wait/result/cancel/
+ * setup) keep collecting positionals as ids and values.
+ */
+function parseFlags(argv, { taskCommand = false } = {}) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith('--')) {
+      let name = t.slice(2);
+      if (REMOVED_REVIEW_FLAGS.has(name) || REMOVED_EXEC_FLAGS.has(name)) migrationDie(name);
+      if (FLAG_ALIASES[name]) {
+        if (!warnedAliases.has(name)) {
+          warnedAliases.add(name);
+          process.stderr.write(`${PRODUCT}: --${name} is deprecated; use --${FLAG_ALIASES[name]}\n`);
+        }
+        name = FLAG_ALIASES[name];
+      }
+      if (VALUE_FLAGS.has(name)) {
+        const v = argv[++i];
+        checkValue(name, v);
+        opts[name] = v;
+      } else if (BOOL_FLAGS.has(name)) {
+        opts[name] = true;
+      } else if (/\s/.test(name)) {
+        packedArgumentDie(name, t);
+      } else {
+        die(`unknown flag --${name}`);
+      }
+    } else if (taskCommand) {
+      die(
+        `positional task text was removed; pass the task with --prompt <text>, ` +
+          `--prompt-file <path>, or --stdin`
+      );
+    } else {
+      opts._.push(t);
+    }
+  }
+  return opts;
+}
+
+function fmtTokens(usage) {
+  if (!usage) return 'n/a';
+  const parts = [`in ${usage.input_tokens ?? '?'}`, `out ${usage.output_tokens ?? '?'}`];
+  if (usage.thinking_tokens) parts.push(`think ${usage.thinking_tokens}`);
+  if (usage.cache_read_tokens) parts.push(`cache ${usage.cache_read_tokens}`);
+  return parts.join(', ');
+}
+
+// ---------------------------------------------------------------------------
+// prompt building
+// ---------------------------------------------------------------------------
+
+function fillTemplate(mode, vars) {
+  const file = path.join(TEMPLATES_DIR, `${mode}.md`);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    die(`template not found: ${file}`);
+  }
+  return text.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+
+function gatherContext() {
+  const branch = sh('git', ['branch', '--show-current']).out || '(no git branch)';
+  return [
+    `Working directory: ${process.cwd()}`,
+    `Git branch: ${branch}`,
+    `Date: ${new Date().toISOString().slice(0, 10)}`,
+  ].join('\n');
+}
+
+function dirtyWorkspacePrompt() {
+  if (!inGitRepo()) return '';
+  const status = porcelainSnapshot();
+  if (!status?.length) return '';
+  const lines = [];
+  let bytes = 0;
+  for (const line of status) {
+    const next = Buffer.byteLength(`${line}\n`);
+    if (lines.length >= MAX_DIRTY_STATUS_LINES || bytes + next > MAX_DIRTY_STATUS_BYTES) break;
+    lines.push(line);
+    bytes += next;
+  }
+  const truncated = lines.length < status.length;
+  const limitNote = truncated
+    ? `\n\nThe status list was truncated to ${lines.length} of ${status.length} entries and ${bytes} bytes. Run \`git status --porcelain\` and inspect relevant diffs before editing or delivering changes.`
+    : '';
+  return (
+    '## Existing workspace changes\n\n' +
+    'The workspace was already dirty before this implement run. Treat these paths as user-owned context. Build on them only when the task clearly includes them; otherwise pause and ask for confirmation before overwriting, cleaning, stashing, resetting, deleting, committing, pushing, or opening a PR with them. Use `git status --porcelain` and `git diff` as ground truth when path ownership is unclear.\n\n' +
+    '`git status --porcelain` before this run (bounded summary):\n' +
+    '```text\n' +
+    lines.join('\n') +
+    '\n```' +
+    limitNote
+  );
+}
+
+// ---------------------------------------------------------------------------
+// agy invocation
+// ---------------------------------------------------------------------------
+
+function durationToMs(d) {
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(d);
+  if (!m) return null;
+  const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2]];
+  return Math.round(parseFloat(m[1]) * mult);
+}
+
+
+function queryAgyModels() {
+  try {
+    const agy = agyCommand(['models']);
+    const r = spawnSync(agy.cmd, agy.args, {
+      encoding: 'utf8',
+      timeout: 10_000,
+      windowsHide: true,
+    });
+    if (r.error) {
+      return { ok: false, error: r.error.message };
+    }
+    if (r.status !== 0) {
+      return { ok: false, error: (r.stderr || '').trim() || `exit ${r.status}` };
+    }
+    const stdout = (r.stdout || '').trim();
+    if (!stdout) {
+      return { ok: false, error: 'empty output from `agy models`' };
+    }
+    const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+    const models = [];
+    for (const line of lines) {
+      if (/^fetching/i.test(line)) continue;
+      const parts = line.split(/\s+/);
+      const id = parts[0];
+      const desc = parts.slice(1).join(' ');
+      if (id) {
+        models.push({ id, desc });
+      }
+    }
+    if (models.length === 0) {
+      return { ok: false, error: 'no models found in `agy models` output' };
+    }
+    return { ok: true, models };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function recommendCompatibleModel(requestedModel, availableModelIds) {
+  const effortMatch = requestedModel ? requestedModel.match(/-(low|medium|high)$/) : null;
+  const effort = effortMatch ? effortMatch[1] : null;
+
+  if (effort) {
+    const sameEffort = availableModelIds.filter((id) => id.endsWith(`-${effort}`));
+    if (sameEffort.length > 0) {
+      const flashOrder = [
+        `gemini-3.8-flash-${effort}`,
+        `gemini-3.7-flash-${effort}`,
+        `gemini-3.6-flash-${effort}`,
+        `gemini-3.5-flash-${effort}`,
+      ];
+      for (const candidate of flashOrder) {
+        if (sameEffort.includes(candidate) && candidate !== requestedModel) {
+          return candidate;
+        }
+      }
+      const otherFlash = sameEffort.find((id) => id.includes('flash') && id !== requestedModel);
+      if (otherFlash) return otherFlash;
+
+      const proOrder = [`gemini-3.1-pro-${effort}`];
+      for (const candidate of proOrder) {
+        if (sameEffort.includes(candidate) && candidate !== requestedModel) {
+          return candidate;
+        }
+      }
+      const otherSameEffort = sameEffort.find((id) => id !== requestedModel);
+      if (otherSameEffort) return otherSameEffort;
+    }
+  }
+
+  const anyFlash = availableModelIds.find((id) => id.includes('flash') && id !== requestedModel);
+  if (anyFlash) return anyFlash;
+
+  return availableModelIds.find((id) => id !== requestedModel) || null;
+}
+
+function isUnsupportedModelError(errText) {
+  if (!errText) return false;
+  if (/auth|login|credential|unauthorized|401|403/i.test(errText)) return false;
+  if (/quota|rate.?limit|resource.?exhausted|429/i.test(errText)) return false;
+  if (/network|econnrefused|enotfound|fetch failed|socket|eai_again/i.test(errText)) return false;
+  if (/requires --effort/i.test(errText)) return false;
+  return (
+    /not recognized as a known model/i.test(errText) ||
+    /unknown model/i.test(errText) ||
+    /unsupported model/i.test(errText) ||
+    /invalid model selection/i.test(errText) ||
+    /model .* (not found|is not supported|is not available|is not recognized)/i.test(errText)
+  );
+}
+
+function handleUnsupportedModel({ requestedModel, errText, originalError, convNote }) {
+  const discovery = queryAgyModels();
+  let msg = `agy reported an unsupported-model error for requested model "${requestedModel}".\n`;
+  if (originalError) {
+    msg += `agy error: ${originalError}\n`;
+  }
+
+  if (!discovery.ok) {
+    msg +=
+      `Model discovery via \`agy models\` failed (${discovery.error}).\n` +
+      `Please run \`agy models\` to check available models.\n` +
+      `Updating agy is preferred to use the latest default (gemini-3.8-flash).`;
+    die(msg + (convNote || ''));
+  }
+
+  const availableIds = discovery.models.map((m) => m.id);
+  const best = recommendCompatibleModel(requestedModel, availableIds);
+
+  msg +=
+    `Available models (from \`agy models\`):\n` +
+    discovery.models.map((m) => `  ${m.id}${m.desc ? `\t${m.desc}` : ''}`).join('\n') +
+    '\n\n';
+
+  if (best) {
+    msg += `Best same-effort compatible recommendation: --model ${best}\n`;
+  }
+  msg += `Updating agy is preferred to use the latest default (gemini-3.8-flash).`;
+  die(msg + (convNote || ''));
+}
+
+function agyArgs({ prompt, model, timeout, conversation, unrestricted, jsonSchema, workspace }, format) {
+  const args = ['-p', prompt, '--model', model, '--output-format', format, '--print-timeout', timeout, '--add-dir', workspace];
+  if (conversation) args.push('--conversation', conversation);
+  if (unrestricted) args.push('--dangerously-skip-permissions');
+  if (jsonSchema) args.push('--json-schema', jsonSchema);
+  return args;
+}
+
+function runAgy(invoke) {
+  const { model, timeout } = invoke;
+  const args = agyArgs(invoke, 'json');
+
+  const budget = (durationToMs(timeout) ?? 600_000) + 60_000; // grace over agy's own timeout
+  const agy = agyCommand(args);
+  const r = spawnSync(agy.cmd, agy.args, {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    timeout: budget,
+    windowsHide: true,
+    env: invoke.env, // undefined inherits; pool accounts pass a private HOME
+  });
+  if (r.error && r.error.code === 'ETIMEDOUT') {
+    die(`agy timed out: no result within ${timeout} plus 60s grace. Retry with a larger --timeout, or narrow the task.`);
+  }
+  if (r.error) die(`failed to launch agy (${AGY_BIN}): ${r.error.message}`);
+  if (r.signal) {
+    die(`agy was killed by signal ${r.signal} before returning a result (companion budget: ${timeout} + 60s grace).`);
+  }
+
+  const stdout = (r.stdout || '').trim();
+  const stderr = (r.stderr || '').trim();
+  // agy prints a single-line JSON object; be defensive about leading noise.
+  const start = stdout.indexOf('{');
+  let payload = null;
+  if (start >= 0) {
+    try {
+      payload = JSON.parse(stdout.slice(start));
+    } catch {
+      /* fall through */
+    }
+  }
+  if (!payload) {
+    const errText = `${stdout}\n${stderr}`;
+    if (isUnsupportedModelError(errText)) {
+      handleUnsupportedModel({
+        requestedModel: model,
+        errText,
+        originalError: stderr || stdout,
+      });
+    }
+    let msg =
+      `agy did not return parseable JSON (exit ${r.status}).\n` +
+      `stdout: ${stdout.slice(0, 800) || '(empty)'}\n` +
+      `stderr: ${stderr.slice(0, 800) || '(empty)'}`;
+    // EPERM on agy's own home files or on binding localhost is the signature of
+    // a harness command sandbox (e.g. Codex workspace-write). agy cannot run
+    // sandboxed: it binds a local port for its language server and reads its
+    // OAuth token file, which sandbox secret-protection hides — no
+    // writable_roots/network_access knob fixes the hidden token.
+    if (/operation not permitted/i.test(stderr)) {
+      msg +=
+        '\n\nThis looks like a harness command sandbox blocking agy (EPERM on its log/state files or on binding 127.0.0.1). ' +
+        'agy cannot run inside a sandbox — it needs a localhost port and its OAuth token file, which sandboxes typically hide. ' +
+        'Run this companion command unsandboxed: in Codex, grant the workspace full access or approve the command with escalated permissions.';
+    }
+    // A quota or auth failure is classified by executeRun before anything is
+    // printed; it re-raises through die() when no pool account handles it.
+    if (classifyFailureText(errText)) throw Object.assign(new Error(msg), { deferredDie: true, diagnosticText: errText });
+    die(msg);
+  }
+  return { payload, stderr, exit: r.status ?? 0 };
+}
+
+/** Triage the agy result into distinct classes with distinct guidance
+ *  (never cross-suggested), or return the response text on success.
+ *  1. status ERROR / nonzero exit, but response text came back
+ *     → return the text (exit 0) and put diagnostics on stderr.
+ *       The orchestrator judges task completion; nonempty text is not proof.
+ *  2. status ERROR / nonzero exit, no response
+ *     → agy's own error verbatim; NEVER suggest --unrestricted. Cause
+ *       hints are appended only when the error text actually matches them.
+ *  3. response timeout             → attention when the conversation is resumable.
+ *  4. status SUCCESS, empty body   → permission fail-closed signature; only a
+ *                                    --restricted run gets the setup hint
+ *                                    (unrestricted runs have no rules to fix).
+ */
+function triageResult({ payload, stderr, exit }, mode, profile, profileSource, requestedModel) {
+  const status = (payload.status || '').toUpperCase();
+  const response = (payload.response || '').trim();
+  const convNote = payload.conversation_id
+    ? `\nConversation id (you can still continue it): ${payload.conversation_id}`
+    : '';
+
+  // Match AGY's response deadline, not a tool/network timeout embedded in an
+  // unrelated error. Response text keeps the done-with-warnings delivery contract.
+  if (!response && (['TIMEOUT', 'TIMED_OUT', 'RESPONSE_TIMEOUT'].includes(status) ||
+      (status === 'ERROR' && /^timeout waiting for response[.!]?$/i.test(String(payload.error || '').trim())))) {
+    throw Object.assign(new Error(`agy timed out (status ${payload.status}) before finishing.` +
+      (payload.error ? `\nagy error: ${payload.error}` : '') + convNote), { reason: 'response_timeout' });
+  }
+
+  if ((status && status !== 'SUCCESS') || exit !== 0) {
+    if (response) {
+      // Preserve response text and diagnostics for the orchestrator to assess.
+      process.stderr.write(
+        `${PRODUCT} warning: agy reported status ${payload.status || 'unknown'} (exit ${exit}) ` +
+          'but returned response text — delivering it for assessment.\n' +
+          (payload.error ? `agy error: ${payload.error}\n` : '') +
+          (stderr ? `agy stderr: ${stderr}\n` : '')
+      );
+      return response;
+    }
+    const errText = `${payload.error || ''}\n${stderr}`;
+    if (isUnsupportedModelError(errText)) {
+      handleUnsupportedModel({
+        requestedModel: requestedModel || DEFAULTS.model[mode],
+        errText,
+        originalError: payload.error || stderr,
+        convNote,
+      });
+    }
+
+    let msg = `agy reported an error (status ${payload.status || 'unknown'}, exit ${exit}).`;
+    if (payload.error) msg += `\nagy error: ${payload.error}`;
+    if (stderr) msg += `\nagy stderr: ${stderr}`;
+    const hints = [];
+    if (/model|effort/i.test(errText)) {
+      hints.push('invalid model id (agy needs effort-suffixed ids, e.g. gemini-3.8-flash-low — run `agy models`)');
+    }
+    if (/auth|login|credential|unauthorized|401|403/i.test(errText)) {
+      hints.push('expired auth (run `agy` interactively once to re-login)');
+    }
+    if (/quota|rate.?limit|resource.?exhausted|429/i.test(errText)) {
+      hints.push('exhausted quota');
+    }
+    if (hints.length) msg += `\nLikely cause: ${hints.join('; ')}.`;
+    die(msg + convNote);
+  }
+
+  if (response) return response;
+
+  // status SUCCESS but nothing came back
+  if (mode === 'ask') {
+    die(
+      'unexpected: agy returned success with an empty answer, but ask uses no tools, so this cannot be a ' +
+        'permission denial. Please report it (include the agy stderr below if any).' +
+        (stderr ? `\n\nagy stderr:\n${stderr}` : '') +
+        convNote
+    );
+  }
+  let msg = 'agy returned an empty response (status SUCCESS but no content).';
+  if (profile === 'restricted') {
+    const cause =
+      profileSource === 'project'
+        ? 'This run was restricted by the project policy in .agy-crew/config.json'
+        : profileSource === 'inherited' ? 'This continuation inherited the restricted profile' : 'This run used `--restricted`';
+    const relax =
+      profileSource === 'project'
+        ? 'relax the policy (`setup --restrict none`) or pass `--unrestricted` for this run'
+        : profileSource === 'inherited' ? 'pass `--unrestricted` explicitly for this continuation' : `drop \`--restricted\` — ${mode} runs unrestricted by default`;
+    msg +=
+      `\n${cause}, so agy kept its permission enforcement on: in headless mode every` +
+      ' unlisted tool call is auto-denied, which is the usual cause of an empty response.' +
+      `\nFix: run \`setup\` once to install the evidence-gathering command allowlist, or ${relax}.` +
+      '\nNote: some agy tools ignore allow-rules in headless mode entirely, so even a complete allowlist cannot' +
+      ' make them work; those need an unrestricted run.';
+  }
+  if (stderr) msg += `\n\nagy stderr:\n${stderr}`;
+  die(msg + convNote);
+}
+
+// ---------------------------------------------------------------------------
+// A follow-up targets a conversation whose execution has stopped. While the
+// job is still running, report its status and id instead of queueing: the
+// orchestrator decides whether to wait or cancel first.
+function refuseRunningFollowUp(state, conversation, jobId = null) {
+  if (!conversation && !jobId) return;
+  const active = (state.jobs || []).find(j =>
+    ((conversation && j.conversation_id === conversation) || (jobId && j.id === jobId)) &&
+    liveJobStatus(j) === 'running');
+  if (!active) return;
+  die(`job ${active.id} is still running (status: running); the follow-up was not accepted or queued. ` +
+    `Collect it with \`wait ${active.id}\` and continue afterwards, or \`cancel ${active.id}\` first for an immediate change of direction.`);
+}
+
+// run (research / review / implement / continue)
+// ---------------------------------------------------------------------------
+
+const ACCOUNT_REQUEST_RE = /^(auto|live|[a-z0-9][a-z0-9._-]{0,31})$/;
+
+/** --account <auto|live|name>, defaulting to AGY_CREW_ACCOUNT, then auto. */
+function accountRequest(opts) {
+  const value = opts.account || process.env.AGY_CREW_ACCOUNT || 'auto';
+  if (!ACCOUNT_REQUEST_RE.test(value)) die(`invalid --account "${value}": use auto, live, or a pool account name (see \`accounts list\`)`);
+  return value;
+}
+
+function resolveRun(mode, opts, priorJob = null) {
+  // likely a typo for --restricted; --restrict (per-repo policy) belongs to setup
+  if (opts.restrict !== undefined) {
+    die(`--restrict is a setup flag (per-repo policy: \`setup --restrict <modes|none>\`). For a single ${mode} run use --restricted.`);
+  }
+
+  // model / effort
+  if (opts.effort && !['low', 'medium', 'high'].includes(opts.effort)) {
+    die('--effort must be low|medium|high');
+  }
+  let model;
+  if (opts.model) {
+    model = normalizeModel(opts.model, opts.effort);
+  } else if (opts.effort) {
+    model = `gemini-3.8-flash-${opts.effort}`;
+  } else {
+    model = DEFAULTS.model[mode];
+  }
+
+  // profile: CLI flag > project policy (.agy-crew/config.json) > built-in default
+  if (opts.restricted && opts.unrestricted) die('--restricted and --unrestricted are mutually exclusive');
+  const policyProfile = mode === 'ask' ? null : loadProjectConfig()?.profiles?.[mode] || null;
+  let profile;
+  let profileSource; // 'flag' | 'project' | 'default' | 'inherited'
+  if (opts.restricted || opts.unrestricted) {
+    profile = opts.restricted ? 'restricted' : 'unrestricted';
+    profileSource = 'flag';
+  } else if (policyProfile) {
+    profile = policyProfile;
+    profileSource = 'project';
+  } else {
+    profile = DEFAULTS.profile[mode];
+    profileSource = 'default';
+  }
+  if (mode === 'ask' && (opts.unrestricted || opts.restricted)) {
+    if (opts.unrestricted) process.stderr.write(PRODUCT + ': ask is tool-free; --unrestricted ignored\n');
+    profile = 'restricted';
+  }
+
+  // execution style is a property of the mode; no flag overrides it
+  const background = DEFAULTS.background[mode];
+
+  const timeout = opts.timeout || DEFAULTS.timeout[mode];
+  const budget = durationToMs(timeout);
+  if (!Number.isFinite(budget) || budget <= 0 || (background && budget > 7200000)) die('invalid --timeout: use a positive duration, at most 120m for background jobs');
+
+  // conversation
+  const state = loadState();
+  let conversation = opts.conversation || null;
+  if (!conversation && opts.continue) {
+    conversation = state.conversations?.[mode] || null;
+    if (!conversation) die(`--continue given but no previous ${mode} conversation is recorded in state.json`);
+  }
+
+  const recorded = state.conversation_configs?.[conversation];
+  const prior = priorJob || (conversation ? [...(state.jobs || [])].reverse().find((j) => j.conversation_id === conversation && j.mode === mode) : null)
+    || (recorded?.mode === mode ? recorded : null)
+    || (state.last?.id === conversation && state.last?.mode === mode ? { model: state.last.model, profile: state.last.profile } : null);
+  // Configuration may come from an earlier job; occupancy belongs to the
+  // whole conversation, including jobs launched through another mode.
+  refuseRunningFollowUp(state, conversation);
+  if (prior) {
+    if (!opts.model && !opts.effort && prior.model) model = prior.model;
+    if (!opts.restricted && !opts.unrestricted && prior.profile) { profile = prior.profile; profileSource = 'inherited'; }
+  }
+  if (profileSource === 'project') process.stderr.write(`${PRODUCT}: profile=${profile} set by project policy (${configPath()})\n`);
+  return { mode, model, profile, profileSource, background, timeout, conversation, parentJobId: prior?.id || null, originalCwd: prior?.cwd || null,
+    account_request: accountRequest(opts) };
+}
+
+/** Task text comes from exactly one source: --prompt, --prompt-file, or
+ *  --stdin. Long prompts should use the latter two instead of shell quoting.
+ *  Whatever the source, the contents are opaque here: already a single string
+ *  by the time they arrive, and never scanned for companion flags. */
+function taskText(opts) {
+  const sources = [
+    opts.prompt !== undefined && '--prompt',
+    opts['prompt-file'] !== undefined && '--prompt-file',
+    opts.stdin && '--stdin',
+  ].filter(Boolean);
+  if (sources.length > 1) die(`task text given more than one way (${sources.join(', ')}) — use exactly one`);
+  if (opts.prompt !== undefined) return opts.prompt.trim();
+  if (opts['prompt-file'] !== undefined) {
+    try {
+      return fs.readFileSync(opts['prompt-file'], 'utf8').trim();
+    } catch (e) {
+      die(`cannot read --prompt-file ${opts['prompt-file']}: ${e.message}`);
+    }
+  }
+  if (opts.stdin) {
+    try {
+      return fs.readFileSync(0, 'utf8').trim();
+    } catch (e) {
+      die(`cannot read task text from stdin: ${e.message}`);
+    }
+  }
+  return '';
+}
+
+function buildPrompt(mode, opts) {
+  const task = taskText(opts);
+  const context = gatherContext();
+
+  if (!task) {
+    if (mode === 'ask') die('ask needs a question');
+    if (mode === 'review') {
+      die(
+        'review needs a subject description, e.g. review --prompt "Review PR #730" or review --prompt "Review the current working tree"'
+      );
+    }
+    die(`${mode} needs a task description`);
+  }
+  if (Buffer.byteLength(task) > MAX_INLINE_BYTES) {
+    die(`task text exceeds the ${MAX_INLINE_BYTES / 1024}KB inline limit`);
+  }
+  // ask is zero-tool by design: question only, no workspace context
+  if (mode === 'ask') return fillTemplate('ask', { TASK: task });
+  return fillTemplate(mode, {
+    TASK: task,
+    CONTEXT: context,
+    WORKSPACE: mode === 'implement' ? dirtyWorkspacePrompt() : '',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// tiered guards (unrestricted runs only; ask is forced restricted upstream)
+//
+//   implement → it is meant to edit files. Dirty workspaces are prompt context,
+//               not a hard companion refusal: agy can continue when the task
+//               clearly includes the existing changes, and must ask when it
+//               would overwrite or deliver unrelated user work.
+//   review /  → no gate at all, never blocked. They should not be touching
+//   research    files, so we snapshot `git status --porcelain` around the run
+//               and report any delta with the result.
+//   staffer   → same snapshot/report, but neutrally worded: a general task may
+//               legitimately edit files, so the delta is information for the
+//               caller, not an accusation.
+// ---------------------------------------------------------------------------
+
+function inGitRepo() {
+  const r = sh('git', ['rev-parse', '--is-inside-work-tree']);
+  return r.code === 0 && r.out === 'true';
+}
+
+/** Porcelain lines as an array, or null when git can't tell us (no repo). */
+function porcelainSnapshot() {
+  const r = sh('git', ['status', '--porcelain']);
+  if (r.code !== 0) return null;
+  return r.out ? r.out.split('\n') : [];
+}
+
+/** Lines that appeared during the run, plus lines whose status changed for a
+ *  path that was already dirty (e.g. " M f" → "MM f"). */
+function porcelainDelta(before, after) {
+  const seen = new Map();
+  for (const line of before) seen.set(line.slice(3), line);
+  return after.filter((line) => seen.get(line.slice(3)) !== line);
+}
+
+function implementGuardApplies(resolved) {
+  return resolved.profile === 'unrestricted' && resolved.mode === 'implement';
+}
+
+function treeReportApplies(resolved) {
+  return resolved.profile === 'unrestricted' && ['staffer', 'review', 'research'].includes(resolved.mode);
+}
+
+function implementDispatchWarning() {
+  if (!inGitRepo()) {
+    process.stderr.write(
+      PRODUCT + ' warning: not a git repository — agy\'s edits cannot be reviewed or rolled back via git.\n' +
+        'Proceeding anyway; back up anything you care about, or run implement from inside a repository.\n'
+    );
+  }
+}
+
+function implementPostcondition(before) {
+  if (!inGitRepo()) return '';
+  const after = porcelainSnapshot() || [];
+  if (!after.length) return '\n[unrestricted] Working tree clean after implement.';
+  const diffStat = sh('git', ['diff', '--stat']).out;
+  const delta = before ? porcelainDelta(before, after) : after;
+  const untracked = delta
+    .filter((l) => l.startsWith('??'))
+    .map((l) => l.slice(3))
+    .join(', ');
+  let out;
+  if (before?.length) {
+    out =
+      '\n[unrestricted] Working tree is dirty after implement. Existing pre-run changes may be part of the task context.\n' +
+      'Status entries that appeared or changed during the run:\n' +
+      (delta.length ? delta.map((l) => `  ${l}`).join('\n') : '  (none detected by porcelain status)') +
+      '\n`git diff --stat`:\n' +
+      (diffStat || '(only new files or committed by agy)');
+  } else {
+    out =
+      '\n[unrestricted] agy modified the working tree. `git diff --stat`:\n' +
+      (diffStat || '(only new files or committed by agy)');
+  }
+  if (untracked) out += `\nNew untracked files: ${untracked}`;
+  out += '\nACTION FOR THE CALLING AGENT: inspect the current workspace (`git status --short`, `git diff`) and distinguish pre-run dirty paths from this run\'s delta. Continue the same agy conversation for follow-up work. If committing or opening a PR, first verify the task explicitly authorized that delivery.';
+  return out;
+}
+
+/** Tree-delta warning for staffer/review/research: silent unless agy dirtied
+ *  the tree. review/research should never edit, so the report blames agy; a
+ *  staffer task may legitimately edit, so its wording is neutral. */
+function treeDeltaReport(mode, before, after) {
+  if (!before || !after) return '';
+  const delta = porcelainDelta(before, after);
+  if (!delta.length) return '';
+  const blame =
+    mode === 'staffer'
+      ? `agy modified the working tree during this ${mode} run — verify the task asked for it. `
+      : `agy modified the working tree during this ${mode} — it should not have. `;
+  return (
+    `\n[unrestricted] ${blame}` +
+    `Delta (\`git status --porcelain\` entries that appeared or changed during the run):\n` +
+    delta.map((l) => `  ${l}`).join('\n') +
+    `\nACTION FOR THE CALLING AGENT: inspect these changes (\`git diff\`) before trusting this ${mode}. ` +
+    `Rollback: \`git checkout -- <path>\` for tracked files, delete the new untracked ones.`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// account pool: acquire -> run -> classify -> fail over or loan
+// ---------------------------------------------------------------------------
+
+const MAX_POOL_RETRIES = 3;
+const QUOTA_CONTINUE_PROMPT = 'Your previous turn stopped because the account hit a quota limit. ' +
+  'Continue the same task from where you stopped; do not repeat finished steps.';
+
+/** With an empty pool and no --account the run is plain live, and stays silent
+ *  about accounts exactly as it did before the pool existed. */
+const showsAccount = (held, resolved) => !!held && (held.pooled || resolved.account_request === 'live');
+
+function accountTelemetry(held, resolved) {
+  if (!showsAccount(held, resolved)) return '';
+  return ` account=${held.account}${held.lender ? ` credential=${held.lender}` : ''}`;
+}
+
+/** Re-raise an agy failure that runAgy deferred so the pool could look at it. */
+function rethrow(error) {
+  if (error.deferredDie) die(error.message);
+  throw error;
+}
+
+function resultFailure({ payload, stderr, exit }) {
+  const status = (payload.status || '').toUpperCase();
+  if ((payload.response || '').trim() || ((!status || status === 'SUCCESS') && exit === 0)) return null;
+  const text = `${payload.error || ''}\n${stderr || ''}`;
+  const kind = classifyFailureText(text);
+  return kind ? { kind, text } : null;
+}
+
+/** One agy call. A quota/auth failure comes back as data in both shapes agy
+ *  reports it (an ERROR payload, or a thrown error carrying the raw output);
+ *  anything else behaves exactly as before. */
+async function invokeOnce(invoke, execution) {
+  let result;
+  try {
+    result = execution ? await execution(invoke) : runAgy(invoke);
+  } catch (error) {
+    const text = `${error.message}\n${error.diagnosticText || ''}`;
+    const kind = error.reason === 'canceled' ? null : classifyFailureText(text);
+    if (!kind) throw error;
+    return { error, failure: { kind, text } };
+  }
+  return { result, failure: resultFailure(result) };
+}
+
+function quotaFailure(resolved, opts, { message, retry_at, conversation }) {
+  const when = retry_at || 'the account quota resets';
+  const recovery = conversation
+    ? `continue ${opts.jobId ? `--job ${opts.jobId}` : `--conversation ${conversation}`} after ${when}; ` +
+      'when another pool account is idle, a credential loan is used automatically'
+    : `start a new run after ${when}, pass --account live, or choose another model family`;
+  const text = `${message}\n${recovery}`;
+  if (resolved.background) throw Object.assign(new Error(text), { reason: 'quota_exhausted', retry_at: retry_at || null, recovery });
+  die(`${text}\n${JSON.stringify({ status: conversation ? 'attention' : 'error', reason: 'quota_exhausted',
+    retry_at: retry_at || null, conversation_id: conversation || null, recovery }, null, 2)}`, conversation ? 5 : 1);
+}
+
+function latestConversation(jobId) {
+  return jobId ? loadState().jobs?.find((j) => j.id === jobId)?.conversation_id || null : null;
+}
+
+/** Run agy on a pool account chosen under a lease. A quota failure records a
+ *  cooldown and then either fails over to another account (nothing started
+ *  yet) or continues the bound conversation on a borrowed credential. */
+async function runWithPool(resolved, invoke, opts, execution) {
+  const family = modelFamily(resolved.model);
+  for (let retries = 0; ; retries++) {
+    const got = acquireRun({ requested: resolved.account_request, family, conversation: invoke.conversation, jobId: opts.jobId });
+    if (got.error) {
+      if (got.error.reason !== 'quota_exhausted') die(got.error.message);
+      quotaFailure(resolved, opts, { ...got.error, conversation: invoke.conversation });
+    }
+    const held = got.held;
+    const shown = showsAccount(held, resolved);
+    invoke.env = held.env;
+    invoke.recordAs = shown ? held.account : null;
+    if (shown && opts.jobId) updateJob(opts.jobId, { account: held.account, ...(held.lender ? { credential_from: held.lender } : {}) });
+
+    let attempt;
+    try {
+      attempt = await invokeOnce(invoke, execution);
+      if (attempt.result) rememberConversation(resolved, attempt.result.payload.conversation_id, opts.jobId, invoke.recordAs);
+    } finally {
+      held.release();
+    }
+    const { result, error, failure } = attempt;
+    if (!failure || held.account === 'live') {
+      if (error) rethrow(error);
+      return { result, held };
+    }
+    const credit = held.lender || held.account; // the credential that made the request
+    if (failure.kind === 'authentication_failed') {
+      markAuthError(credit, failure.text);
+      if (error) rethrow(error);
+      return { result, held }; // triage reports it with its usual message
+    }
+    const cooldown = recordCooldown(credit, family, failure.text, opts.jobId);
+    const conversation = result?.payload?.conversation_id || latestConversation(opts.jobId) || invoke.conversation;
+    if (retries < MAX_POOL_RETRIES) {
+      if (!conversation && held.auto) continue; // nothing started: just pick another account
+      if (conversation && boundAccount(loadPool(), conversation) !== 'live') {
+        invoke.conversation = conversation; // the next acquire finds the account cooling and borrows a credential
+        invoke.prompt = QUOTA_CONTINUE_PROMPT;
+        continue;
+      }
+    }
+    quotaFailure(resolved, opts, { conversation, retry_at: cooldown.retry_at,
+      message: `agy account "${credit}" hit a ${family} quota limit (quota_exhausted).` });
+  }
+}
+
+async function executeRun(resolved, prompt, opts, execution = null) {
+  const workspaceBefore = resolved.mode === 'ask' ? null : porcelainSnapshot();
+  const implementBefore = implementGuardApplies(resolved) ? workspaceBefore : null;
+  const treeBefore = treeReportApplies(resolved) ? workspaceBefore : null;
+
+  const invoke = {
+    prompt,
+    workspace: repoRoot(),
+    model: resolved.model,
+    timeout: resolved.timeout,
+    conversation: resolved.conversation,
+    unrestricted: resolved.profile === 'unrestricted',
+    jsonSchema: opts.json && resolved.mode === 'review' ? REVIEW_JSON_SCHEMA : null,
+  };
+  let result, response, held;
+  try {
+    ({ result, held } = await runWithPool(resolved, invoke, opts, execution));
+    response = triageResult(result, resolved.mode, resolved.profile, resolved.profileSource, resolved.model);
+  } catch (error) {
+    error.workspace = {
+      before: excerpt(workspaceBefore?.join('\n') ?? 'Git status unavailable', 3000),
+      after: excerpt(porcelainSnapshot()?.join('\n') ?? 'Git status unavailable', 3000),
+      note: 'Inspect git status --short, git diff and git diff --cached. Status cannot detect further edits to already dirty files; no workspace rollback was performed.' };
+    if (error.reason === 'response_timeout' && !resolved.background) {
+      const conversation = result.payload.conversation_id;
+      const recovery = timeoutRecovery({ ...resolved, conversation_id: conversation });
+      die(`${error.message}\n${JSON.stringify({
+        status: conversation ? 'attention' : 'error', reason: error.reason,
+        conversation_id: conversation || null, mode: resolved.mode, model: resolved.model,
+        profile: resolved.profile, recovery,
+      }, null, 2)}`, conversation ? 5 : 1);
+    }
+    throw error;
+  }
+  const payload = result.payload;
+  const treeAfter = treeBefore ? porcelainSnapshot() : null;
+  opts.warnings = !!(result.stderr || result.observationWarnings?.length || result.exit !== 0 || (payload.status && payload.status.toUpperCase() !== 'SUCCESS'));
+
+  // Telemetry is plumbing, not content: it goes to stderr so it never mixes
+  // into the deliverable. Foreground runs put it on the caller's stderr;
+  // background workers have stdout and stderr both wired to jobs/<id>.log, so
+  // it lands there as the job's provenance record.
+  process.stderr.write(
+    `[${PRODUCT}] mode=${resolved.mode} profile=${resolved.profile} model=${resolved.model}${accountTelemetry(held, resolved)} ` +
+      `agy_status=${payload.status || 'unknown'} agy_exit=${result.exit} ` +
+      `duration=${payload.duration_seconds ?? '?'}s turns=${payload.num_turns ?? '?'} tokens(${fmtTokens(payload.usage)})\n` +
+      `conversation: ${payload.conversation_id || 'unknown'} (follow up with --continue)\n`
+  );
+
+  // Guard output is part of the body: the calling agent must act on it.
+  let guard = '';
+  if (implementGuardApplies(resolved)) guard += implementPostcondition(implementBefore);
+  if (treeReportApplies(resolved)) guard += treeDeltaReport(resolved.mode, treeBefore, treeAfter);
+  opts.warnings ||= !!guard;
+  return guard ? response + '\n' + guard : response;
+}
+
+function cmdRun(mode, opts) {
+  const task = taskText(opts); // Resolve prompt-file/stdin in the caller's cwd.
+  const resolved = resolveRun(mode, opts);
+  enterOriginalWorkspace(resolved.originalCwd);
+  if (resolved.parentJobId) {
+    const prior = findJob(resolved.parentJobId);
+    enterOriginalWorkspace(prior.cwd);
+    if (prior.spec_file) { try { opts.json ||= JSON.parse(fs.readFileSync(prior.spec_file, 'utf8')).opts.json; } catch {} }
+  }
+  const prompt = buildPrompt(mode, { prompt: task });
+  return dispatch(resolved, prompt, { ...opts, promptSource: { kind: 'template', task } });
+}
+
+/** Fail fast (before a background job is registered) on an account request
+ *  that can never work: unknown or disabled name, or a conversation owned by
+ *  another account. Quota problems are left to the run itself. */
+function preflightAccount(resolved) {
+  const problem = preflight({ requested: resolved.account_request, family: modelFamily(resolved.model), conversation: resolved.conversation });
+  if (problem && problem.reason !== 'quota_exhausted') die(problem.message);
+}
+
+async function dispatch(resolved, prompt, opts) {
+  const mode = resolved.mode;
+  preflightAccount(resolved);
+  if (!resolved.background) {
+    process.stdout.write(await executeRun(resolved, prompt, opts) + '\n');
+    return;
+  }
+
+  if (implementGuardApplies(resolved)) implementDispatchWarning();
+
+  // background: write a job spec, spawn ourselves detached as _worker
+  const jobId = `${mode}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+  const jobsDir = path.join(ensureStateDir(), 'jobs');
+  fs.mkdirSync(jobsDir, { recursive: true });
+  const logFile = path.join(jobsDir, `${jobId}.log`);
+  const specFile = path.join(jobsDir, `${jobId}.spec.json`);
+  const resultFile = path.join(jobsDir, `${jobId}.result.md`);
+
+  // Register the job BEFORE spawning: a fast worker's own state update must
+  // find the record already present, or it gets lost in its read-modify-write.
+  const record = {
+    id: jobId, mode, pid: null, status: 'running', cwd: process.cwd(),
+    model: resolved.model, profile: resolved.profile, profileSource: resolved.profileSource,
+    timeout: resolved.timeout, conversation_id: resolved.conversation || null,
+    parent_job_id: opts.parentJobId || resolved.parentJobId || null,
+    started_at: new Date().toISOString(), log_file: logFile, result_file: resultFile,
+    spec_file: specFile,
+    events_file: path.join(jobsDir, `${jobId}.events.jsonl`),
+    progress_file: path.join(jobsDir, `${jobId}.progress.json`),
+  };
+  updateState((state) => {
+    // Two callers can both resolve an idle conversation. Recheck under the
+    // registration lock before accepting either the job or its prompt file.
+    refuseRunningFollowUp(state, resolved.conversation);
+    fs.writeFileSync(specFile, JSON.stringify({ resolved, prompt, prompt_source: opts.promptSource || null, opts: { json: !!opts.json }, cwd: process.cwd() }, null, 2));
+    state.jobs ||= [];
+    state.jobs.push(record);
+  });
+  fs.appendFileSync(logFile, `[${PRODUCT}] dispatch registered ${jobId} at ${record.started_at}\n`);
+
+  const logFd = fs.openSync(logFile, 'a');
+  // detached on every platform: on POSIX it isolates the process group; on
+  // Windows it is DETACHED_PROCESS, so the worker has no console (with
+  // windowsHide its own children get none either) and outlives the terminal
+  // that dispatched it, including its Ctrl+C.
+  const child = spawn(process.execPath, [SELF, '_worker', jobId], {
+    cwd: process.cwd(),
+    detached: true,
+    windowsHide: true,
+    stdio: ['ignore', logFd, logFd],
+  });
+  child.unref();
+  fs.closeSync(logFd);
+
+  // Backfill the pid, preserving whatever status the worker may have written.
+  updateJob(jobId, { pid: child.pid });
+  child.on('error', (error) => {
+    fs.writeFileSync(resultFile, `Job failed: worker launch: ${error.message}\n`);
+    updateJob(jobId, { status: 'error', reason: 'worker_launch_error', finished_at: new Date().toISOString() }, true);
+  });
+
+  process.stdout.write(
+    `Started background ${mode} job.\n` +
+      `job id: ${jobId} (pid ${child.pid})\n` +
+      `model: ${resolved.model}  profile: ${resolved.profile}  timeout: ${resolved.timeout}\n` +
+      `result file (written when the job finishes): ${resultFile}\n` +
+      `Collect: run \`wait ${jobId} --timeout 10m\` as a background command ` +
+      `(one background wait per job; exit 0 = result printed, 2 = still running — wait again for the same job, without extra progress checks).\n` +
+      `Progress only if the user asks: \`observe ${jobId}\`   Stop: \`cancel ${jobId}\`\n`
+  );
+}
+
+async function workerMain(jobId) {
+  inWorker = true;
+  const started = Date.now();
+  const controller = new AbortController();
+  const onSignal = () => controller.abort();
+  process.on('SIGTERM', onSignal);
+  process.on('SIGINT', onSignal);
+  let job, cancelTimer;
+  try {
+    job = updateJob(jobId, { worker_started_at: new Date().toISOString(), worker_pid: process.pid, worker_identity: processIdentity(process.pid) });
+    process.stderr.write(`[${PRODUCT}] worker started ${jobId} pid=${process.pid} at ${job.worker_started_at}\n`);
+    if (job.status !== 'running') return;
+    const checkCancellation = () => {
+      if (job.cancel_requested_at || fs.existsSync(job.spec_file + '.cancel')) controller.abort();
+    };
+    checkCancellation();
+    cancelTimer = setInterval(checkCancellation, 100);
+    if (controller.signal.aborted) throw Object.assign(new Error('Execution canceled.'), { reason: 'canceled' });
+    const spec = JSON.parse(fs.readFileSync(job.spec_file, 'utf8'));
+    const opts = { ...spec.opts, jobId };
+    const output = await executeRun(spec.resolved, spec.prompt, opts, (invoke) => {
+      const agy = agyCommand(agyArgs(invoke, 'stream-json'));
+      return runStreaming({ binary: agy.cmd, args: agy.args, job,
+        budget: durationToMs(spec.resolved.timeout) - (Date.now() - started), signal: controller.signal,
+        env: invoke.env,
+        update: (fields) => updateJob(jobId, fields),
+        conversation: (id) => rememberConversation(spec.resolved, id, jobId, invoke.recordAs),
+      }).catch((error) => {
+        if (error.reason === 'missing_result' && isUnsupportedModelError(error.diagnosticText || '')) {
+          handleUnsupportedModel({ requestedModel: invoke.model, errText: error.diagnosticText, originalError: error.diagnosticText });
+        }
+        throw error;
+      });
+    });
+    if (controller.signal.aborted) throw Object.assign(new Error('Execution canceled.'), { reason: 'canceled' });
+    // Result and conversation metadata are durable before completion is visible.
+    job = finishJob(jobId, output + '\n', { status: 'done', warnings: opts.warnings });
+    if (job.status === 'done' && !job.warnings) {
+      for (const file of [job.events_file, job.progress_file]) {
+        try { fs.unlinkSync(file); } catch (error) { process.stderr.write(`cleanup: ${error.message}\n`); }
+      }
+    }
+  } catch (error) {
+    if (!job) throw error;
+    job = loadState().jobs?.find((j) => j.id === jobId);
+    if (!job) throw error;
+    const reason = job.cancel_requested_at ? 'canceled' : error.reason || 'agy_error';
+    const status = job.status === 'canceled' || reason === 'canceled' ? 'canceled'
+      : (isTimeoutReason(reason) || reason === 'quota_exhausted') && job.conversation_id ? 'attention' : 'error';
+    job = finishJob(jobId, (completed) => {
+      const report = { ...diagnosticPacket(completed), result_exists: true, reason: completed.reason,
+        workspace: error.workspace, last_snapshot: readObservation(completed) };
+      return `${completed.status === 'attention' ? 'Job needs attention' : 'Job failed'}:\n${completed.reason === 'canceled' ? 'Execution canceled.' : error.message}\n\n${JSON.stringify(report, null, 2)}\n`;
+    }, (current) => current.cancel_requested_at ? { status: 'canceled', reason: 'canceled' } : { status, reason, ...(error.retry_at ? { retry_at: error.retry_at } : {}) });
+    process.exitCode = JOB_EXIT_CODES[job.status] ?? 1;
+  } finally {
+    clearInterval(cancelTimer);
+    process.removeListener('SIGTERM', onSignal);
+    process.removeListener('SIGINT', onSignal);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// jobs: status / result / cancel
+// ---------------------------------------------------------------------------
+
+const CRASH_SANDBOX_HINT =
+  'The worker pid is not visible from this process. If the job may have been started from a different harness permission or sandbox context, rerun wait/status/result from the same unsandboxed context before treating it as crashed.';
+
+function refreshJobs(state) {
+  for (const job of state.jobs || []) job.status = liveJobStatus(job);
+}
+
+function liveJobStatus(job) {
+  if (['done', 'canceled', 'error', 'attention'].includes(job.status)) return job.status;
+  try {
+    const final = JSON.parse(fs.readFileSync(job.result_file + '.status.json', 'utf8'));
+    if (['done', 'error', 'canceled', 'attention'].includes(final.status)) return final.status;
+  } catch {}
+  if (pidAlive(job.pid)) return 'running';
+  // New jobs publish an explicit result status; never infer success from an
+  // error report left behind by a worker that died before updating state.
+  return !job.spec_file && fs.existsSync(job.result_file) ? 'done' : 'crashed';
+}
+
+// Machine-readable job exit codes shared by `status <id>` and `wait`.
+// 1 stays the generic companion error, so callers can loop on "code 2"
+// without parsing any output.
+const JOB_EXIT_CODES = { done: 0, running: 2, error: 3, crashed: 3, canceled: 4, attention: 5 };
+
+function cmdStatus(opts) {
+  const state = loadState();
+  refreshJobs(state);
+  const jobs = state.jobs || [];
+  const id = opts._[0];
+
+  if (id) {
+    const job = jobs.find((j) => j.id === id);
+    if (!job) die(`no job ${id} in this repository`);
+    process.stdout.write(JSON.stringify(job, null, 2) + '\n');
+    if (job.status === 'running') {
+      process.stdout.write(`\nStill running. Log tail:\n`);
+      const log = readTail(job.log_file);
+      process.stdout.write(log.split('\n').slice(-10).join('\n') + '\n');
+    } else if (job.status === 'crashed' && !fs.existsSync(job.result_file)) {
+      process.stdout.write(JSON.stringify(diagnosticPacket(job), null, 2) + '\n');
+      process.stdout.write(`\n${CRASH_SANDBOX_HINT}\n`);
+    }
+    // machine-readable outcome so callers never have to parse the JSON
+    process.exitCode = JOB_EXIT_CODES[job.status] ?? 1;
+    return;
+  }
+
+  if (!jobs.length) {
+    process.stdout.write('No ' + PRODUCT + ' jobs recorded in this repository.\n');
+    return;
+  }
+  process.stdout.write('id | mode | status | started | finished\n');
+  for (const j of jobs.slice(-20)) {
+    process.stdout.write(`${j.id} | ${j.mode} | ${j.status} | ${j.started_at} | ${j.finished_at || '-'}\n`);
+  }
+  process.stdout.write('\nDetails: `status <id>`   Output: `result <id>`\n');
+  if (jobs.slice(-20).some((j) => j.status === 'crashed' && !fs.existsSync(j.result_file))) {
+    process.stdout.write(`\n${CRASH_SANDBOX_HINT}\n`);
+  }
+}
+
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Block until the job reaches a terminal state, then print its result —
+ *  `wait` + `result` in one call. Bounded by its own --timeout (default 100s,
+ *  chosen to sit under a typical harness per-command timeout); expiring is NOT
+ *  a failure: exit code 2 means "still running — call wait again". */
+async function cmdWait(opts) {
+  const id = opts._[0] || null;
+  const timeout = opts.timeout || '100s';
+  const budget = durationToMs(timeout);
+  if (!Number.isFinite(budget)) die(`invalid --timeout "${timeout}" (examples: 100s, 5m)`);
+
+  // Wait silently: callers use observe for progress, not periodic liveness text.
+  // Read-only lookup: the poll loop must never write state.json, or it races
+  // the worker's own final read-modify-write (see liveJobStatus).
+  const findJob = () => {
+    const jobs = loadState().jobs || [];
+    if (id) return jobs.find((j) => j.id === id) || null;
+    return jobs.length ? jobs[jobs.length - 1] : null;
+  };
+  let job = findJob();
+  if (!job) die(id ? `no job ${id} in this repository` : `no ${PRODUCT} jobs recorded in this repository`);
+
+  const POLL_MS = 200;
+  const start = Date.now();
+  let status = liveJobStatus(job);
+  while (status === 'running' && Date.now() - start < budget) {
+    await sleepMs(Math.min(POLL_MS, budget - (Date.now() - start)));
+    job = findJob();
+    if (!job) die(`job record disappeared from state.json`);
+    status = liveJobStatus(job);
+  }
+
+  return renderJobResponse(job);
+}
+
+function findJob(id) {
+  const jobs = loadState().jobs || [];
+  const job = id ? jobs.find((j) => j.id === id) : jobs.at(-1);
+  if (!job) die(id ? `no job ${id} in this repository` : `no ${PRODUCT} jobs recorded in this repository`);
+  return job;
+}
+
+function readObservation(job) {
+  let snapshot = { recent_activities: [], latest_text: null, last_event_at: null, warnings: ['No activity record is available for this job.'] };
+  try { snapshot = JSON.parse(fs.readFileSync(job.progress_file, 'utf8')); } catch {}
+  return boundSnapshot({ ...snapshot, job_id: job.id, mode: job.mode, status: liveJobStatus(job),
+    started_at: job.started_at, observed_at: new Date().toISOString(),
+    elapsed_seconds: Math.max(0, Math.round((Date.now() - Date.parse(job.started_at)) / 1000)),
+    details: { raw_output: job.events_file || null, diagnostics: job.log_file, result: job.result_file },
+  });
+}
+
+function readTail(file, limit = 8192) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const size = fs.fstatSync(fd).size;
+    const buffer = Buffer.alloc(Math.min(size, limit));
+    fs.readSync(fd, buffer, 0, buffer.length, Math.max(0, size - buffer.length));
+    return buffer.toString('utf8');
+  } catch { return ''; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+function isTimeoutReason(reason) {
+  return reason === 'response_timeout' || reason === 'hard_timeout';
+}
+
+function shellArg(value) {
+  return /^[a-zA-Z0-9_./:-]+$/.test(value) ? value : "'" + String(value).replaceAll("'", "'\\''") + "'";
+}
+
+function timeoutRecovery(job) {
+  const previous = durationToMs(job.timeout) || durationToMs(DEFAULTS.timeout[job.mode]) || 3600000;
+  const next = job.mode === 'ask' ? previous * 2 : Math.min(previous * 2, 7200000);
+  const suggested = next % 60000 === 0 ? `${next / 60000}m` : `${next / 1000}s`;
+  const target = job.id ? `--job ${shellArg(job.id)}` : `--conversation ${shellArg(job.conversation_id || '')}`;
+  return {
+    inspect: 'git status --short; git diff; git diff --cached', spec_file: job.spec_file || null,
+    requires_user_confirmation: true, suggested_timeout: suggested, at_timeout_ceiling: next <= previous,
+    continue: job.conversation_id ? `continue ${target} --timeout ${suggested} --prompt "Continue after inspecting partial workspace changes"` : null,
+    restart: job.id ? `restart ${shellArg(job.id)} --timeout ${suggested}` : null,
+    note: job.conversation_id
+      ? 'Ask the user whether to continue ' + (next <= previous ? 'with a narrower task at the 120m ceiling' : `with a larger timeout (suggested: ${suggested})`) +
+        ' or stop and inspect the current workspace. No automatic retry or continuation.'
+      : 'No conversation ID is available. Inspect partial workspace changes and ask the user before restarting. No retry was started.',
+  };
+}
+
+/** Recovery for a job that stopped on an exhausted account quota. */
+function quotaRecovery(job) {
+  const when = job.retry_at || 'the account quota resets';
+  return { retry_at: job.retry_at || null, spec_file: job.spec_file || null,
+    continue: job.conversation_id ? `continue --job ${job.id} --prompt "Continue the task"` : null,
+    restart: `restart ${job.id}`,
+    note: job.conversation_id
+      ? `continue --job ${job.id} after ${when}; when another pool account is idle, a credential loan is used automatically.`
+      : `No conversation was started. Restart after ${when}, pass --account live, or choose another model family.` };
+}
+
+function diagnosticPacket(job) {
+  let logBytes = null;
+  try { logBytes = fs.statSync(job.log_file).size; } catch {}
+  return { job_id: job.id, mode: job.mode, cwd: job.cwd || process.cwd(), status: liveJobStatus(job),
+    started_at: job.started_at, worker_started_at: job.worker_started_at || null, finished_at: job.finished_at || null,
+    pid: job.pid, agy_pid: job.agy_pid || null, log_bytes: logBytes,
+    log_state: logBytes === null ? 'missing' : logBytes === 0 ? 'empty' : 'present',
+    result_exists: fs.existsSync(job.result_file), log_file: job.log_file, events_file: job.events_file || null,
+    conversation_id: job.conversation_id || null, model: job.model || null, profile: job.profile || null,
+    ...(job.account ? { account: job.account } : {}),
+    ...(job.reason === 'quota_exhausted' ? { retry_at: job.retry_at || null } : {}),
+    recovery: isTimeoutReason(job.reason) ? timeoutRecovery(job) : job.reason === 'quota_exhausted' ? quotaRecovery(job) : { inspect: 'git status --short; git diff', spec_file: job.spec_file || null,
+      continue: job.conversation_id ? `continue --job ${job.id} --prompt "Continue after inspecting partial workspace changes"` : null,
+      restart: `restart ${job.id}`, note: 'Inspect partial workspace changes first. Recovery creates a linked new job with a fresh budget; nothing is retried automatically.' },
+  };
+}
+
+/** Observation never reads the result body, even when completion races a read.
+ *  A separate wait/result owns delivery; observers cannot consume its output. */
+function readTerminalObservation(job, status) {
+  // A result sidecar may be visible just before the shared registry commit.
+  let final = {};
+  try { final = JSON.parse(fs.readFileSync(job.result_file + '.status.json', 'utf8')); } catch {}
+  const finishedAt = job.finished_at || final.finished_at || null;
+  const snapshot = {
+    job_id: job.id, mode: job.mode, status,
+    started_at: job.started_at, finished_at: finishedAt, observed_at: new Date().toISOString(),
+    elapsed_seconds: Math.max(0, Math.round(((Date.parse(finishedAt) || Date.now()) - Date.parse(job.started_at)) / 1000)),
+    result_file: job.result_file, result_available: fs.existsSync(job.result_file),
+    collection: {
+      command: `result ${job.id}`,
+      instruction: 'Collect the existing wait session if one is pending; otherwise use result for the full output.',
+    },
+  };
+  if (status !== 'done') {
+    const reason = job.reason || final.reason || (status === 'crashed' ? 'worker_crashed' : status === 'canceled' ? 'canceled' : 'job_error');
+    const packet = diagnosticPacket({ ...job, ...final, reason });
+    Object.assign(snapshot, {
+      reason,
+      summary: status === 'attention' ? 'Timeout with a resumable conversation; ask the user whether to continue.'
+        : reason === 'hard_timeout' ? 'Execution stopped at its hard limit.' : `Job ${status}; inspect the retained report and diagnostics.`,
+      conversation_id: job.conversation_id || null, model: job.model || null, profile: job.profile || null,
+      ...(job.account ? { account: job.account } : {}),
+      worker_started_at: job.worker_started_at || null, pid: job.pid, agy_pid: job.agy_pid || null,
+      log_state: packet.log_state, log_bytes: packet.log_bytes,
+      details: { diagnostics: job.log_file, raw_output: job.events_file || null, snapshot: job.progress_file || null },
+      recovery: packet.recovery,
+    });
+    if (status === 'crashed') snapshot.liveness_note = CRASH_SANDBOX_HINT;
+  }
+  // Intermediate tool errors remain internal when the overall job succeeds.
+  return boundSnapshot(snapshot);
+}
+
+function renderJobResponse(initial, { observeOnly = false } = {}) {
+  let job = findJob(initial.id);
+  let status = liveJobStatus(job);
+  if (status === 'running') {
+    const snapshot = readObservation(job);
+    // Success cleanup can race the snapshot read; terminal state wins.
+    job = findJob(job.id);
+    status = liveJobStatus(job);
+    if (status === 'running') {
+      process.stdout.write(JSON.stringify(snapshot) + '\n');
+      process.exitCode = 2;
+      return;
+    }
+  }
+  if (observeOnly) {
+    process.stdout.write(JSON.stringify(readTerminalObservation(job, status)) + '\n');
+    process.exitCode = JOB_EXIT_CODES[status] ?? 1;
+    return;
+  }
+  // Include warning metadata when the sidecar precedes the registry commit.
+  if (job.status === 'running') {
+    try { job = { ...job, ...JSON.parse(fs.readFileSync(job.result_file + '.status.json', 'utf8')) }; } catch {}
+  }
+  if (fs.existsSync(job.result_file)) {
+    process.stdout.write(`# Job ${job.id} (${job.mode}, ${status})\n\n`);
+    process.stdout.write(fs.readFileSync(job.result_file, 'utf8'));
+  } else {
+    process.stdout.write(`Job ${job.id} (${job.mode}) finished with status ${status} and no stored result. Log: ${job.log_file}\n`);
+    process.stdout.write(JSON.stringify(diagnosticPacket(job), null, 2) + '\n');
+    if (status === 'crashed') process.stdout.write(`\n${CRASH_SANDBOX_HINT}\n`);
+  }
+  if (status === 'done' && job.warnings) {
+    process.stderr.write(`Job diagnostics (tail, up to 8192 bytes). Full log: ${job.log_file}\n${readTail(job.log_file)}\n`);
+  }
+  process.exitCode = JOB_EXIT_CODES[status] ?? 1;
+}
+
+
+function cmdResult(opts) {
+  const state = loadState();
+  refreshJobs(state);
+  const jobs = state.jobs || [];
+  let job;
+  if (opts._[0]) {
+    job = jobs.find((j) => j.id === opts._[0]);
+    if (!job) die(`no job ${opts._[0]} in this repository`);
+  } else {
+    job = [...jobs].reverse().find((j) => j.status !== 'running');
+    if (!job) die('no finished jobs in this repository');
+  }
+  if (job.status === 'running') {
+    die(`job ${job.id} is still running — collect it with \`wait ${job.id}\` or peek with \`status ${job.id}\``);
+  }
+  if (!fs.existsSync(job.result_file)) {
+    let msg = `job ${job.id} (${job.status}) has no stored result. Log: ${job.log_file}`;
+    if (job.status === 'crashed') {
+      msg += `\n${JSON.stringify(diagnosticPacket(job), null, 2)}\n\n${CRASH_SANDBOX_HINT}`;
+    }
+    die(msg);
+  }
+  renderJobResponse(job);
+  // Preserve result's historical exit contract for non-attention terminal states.
+  process.exitCode = job.status === 'attention' ? 5 : 0;
+}
+
+async function cmdCancel(opts) {
+  const id = opts._[0];
+  if (!id) die('cancel needs a job id (see `status`)');
+  let changed = false, status;
+  const job = updateState((state) => {
+    const job = state.jobs?.find((j) => j.id === id);
+    if (!job) die(`no job ${id} in this repository`);
+    status = liveJobStatus(job);
+    if (status === 'running') {
+      if (!job.spec_file) die('this legacy job has no cancellation request channel; cannot safely signal an unverified stored PID');
+      const identity = job.worker_identity;
+      const current = identity ? processIdentity(job.pid) : null;
+      if (identity && (identity.pid !== job.pid || (current && identity.born !== current.born))) {
+        die('worker identity no longer matches this job; refusing to signal a reused or unrelated PID');
+      }
+      // Keep running visible until the worker stores the cancellation report.
+      job.cancel_requested_at ||= new Date().toISOString();
+      fs.writeFileSync(job.spec_file + '.cancel', job.cancel_requested_at);
+      changed = true;
+    }
+    return job;
+  });
+  if (!changed) { process.stdout.write(`Job ${id} is not running (status: ${status}).\n`); return; }
+  // The worker polls the request even if PID inspection/signaling is blocked.
+  // Never send signals to the stored AGY PID: the worker owns that child.
+  // On Windows process.kill() is TerminateProcess: the worker would die without
+  // running its cleanup and orphan the agy tree, so rely on the marker alone there.
+  const current = job.worker_identity && process.platform !== 'win32' ? processIdentity(job.pid) : null;
+  if (current && current.pid === job.worker_identity.pid && current.born === job.worker_identity.born) {
+    try { process.kill(current.pid, 'SIGTERM'); } catch {}
+  }
+  const deadline = Date.now() + 10000;
+  while (Date.now() < deadline) {
+    const latest = findJob(id);
+    status = liveJobStatus(latest);
+    if (status === 'canceled') { process.stdout.write(`Canceled job ${id} (pid ${job.pid}).\n`); return; }
+    if (status !== 'running') die(`Cancellation requested, but job is ${status}; inspect \`observe ${id}\` and the retained diagnostics.`);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  die(`Cancellation requested but the worker has not published a terminal report; inspect \`observe ${id}\` from the original unsandboxed context.`);
+}
+
+// ---------------------------------------------------------------------------
+// continue
+// ---------------------------------------------------------------------------
+
+function enterOriginalWorkspace(cwd) {
+  if (!cwd) return; // Legacy records did not store a cwd.
+  const root = fs.realpathSync(repoRoot());
+  let target;
+  try { target = fs.realpathSync(cwd); } catch { die(`original workspace directory is unavailable: ${cwd}`); }
+  const git = sh('git', ['rev-parse', '--show-toplevel'], { cwd: target });
+  const targetRoot = fs.realpathSync(git.code === 0 && git.out ? git.out : target);
+  if (root !== targetRoot) die(`recovery cannot switch worktrees; run from the original workspace: ${cwd}`);
+  process.chdir(target);
+  repoRootCache.set(target, git.code === 0 && git.out ? git.out : target);
+  repoRootCache.set(process.cwd(), git.code === 0 && git.out ? git.out : target);
+}
+
+function cmdContinue(opts) {
+  const state = loadState();
+  const targetId = opts.conversation || state.last?.id;
+  const prior = opts.job ? findJob(opts.job) : [...(state.jobs || [])].reverse().find((j) => j.conversation_id === targetId)
+    || state.conversation_configs?.[targetId];
+  const legacyMode = Object.entries(state.conversations || {}).find(([, id]) => id === targetId)?.[0];
+  const mode = prior?.mode || legacyMode || (state.last?.id === targetId ? state.last?.mode : null);
+  const conversation = prior?.conversation_id || targetId;
+  if (opts.job) refuseRunningFollowUp(state, prior?.conversation_id, prior?.id);
+  if (!mode || !conversation) die(`no previous ${PRODUCT} conversation recorded in this repository for this target; use restart <job-id> when no conversation is available`);
+  if (opts.job && opts.conversation && opts.conversation !== prior.conversation_id) die('--job and --conversation identify different conversations');
+  if (opts.job && !prior.conversation_id) die('this job has no known conversation; use restart <job-id>');
+  const task = taskText(opts);
+  if (!task) die('continue needs follow-up text');
+  enterOriginalWorkspace(prior?.cwd);
+  const resolved = resolveRun(mode, { ...opts, conversation }, prior);
+  const workspace = mode === 'implement' ? dirtyWorkspacePrompt() : '';
+  const prompt = `${workspace ? `${workspace}\n\n` : ''}Follow-up in the same conversation:\n\n${task}`;
+  let json = opts.json;
+  if (prior?.spec_file) { try { json ||= JSON.parse(fs.readFileSync(prior.spec_file, 'utf8')).opts.json; } catch {} }
+  return dispatch(resolved, prompt, { ...opts, json, parentJobId: prior?.id, promptSource: { kind: 'followup', task } });
+}
+
+function cmdRestart(opts) {
+  if (!opts._[0]) die('restart needs a job id');
+  const job = findJob(opts._[0]);
+  if (liveJobStatus(job) === 'running') die('job is still running; cancel it before restarting');
+  if (!job.spec_file) die('this legacy job has no stored restart specification');
+  const spec = JSON.parse(fs.readFileSync(job.spec_file, 'utf8'));
+  enterOriginalWorkspace(spec.cwd);
+  // A fresh conversation selects an account again; --account overrides the stored request.
+  const resolved = { ...spec.resolved, conversation: null, timeout: DEFAULTS.timeout[job.mode],
+    account_request: opts.account ? accountRequest(opts) : spec.resolved.account_request || accountRequest({}) };
+  if (opts.timeout) {
+    resolved.timeout = resolveRun(job.mode, { ...opts, model: resolved.model, [resolved.profile]: true }).timeout;
+  }
+  // Rebuild saved task sources with fresh context. For legacy prompts, label
+  // historical snapshots and append current facts without parsing task text.
+  const source = spec.prompt_source || { kind: 'legacy', text: spec.prompt };
+  let prompt;
+  if (source.kind === 'template') prompt = buildPrompt(job.mode, { prompt: source.task });
+  else if (source.kind === 'followup') prompt = `${job.mode === 'implement' ? dirtyWorkspacePrompt() + '\n\n' : ''}Follow-up task in a fresh conversation:\n\n${source.task}`;
+  else {
+    const current = `${gatherContext()}\n\n${job.mode === 'implement' ? dirtyWorkspacePrompt() || 'Working tree is currently clean.' : ''}`;
+    prompt = `Restart the original task below. Its embedded workspace/environment snapshots are historical. Use the current workspace section at the end for this execution; preserve existing partial work.\n\n${source.text}\n\n## Current workspace for this restart\n\n${current}`;
+  }
+  return dispatch(resolved, prompt, { ...spec.opts, parentJobId: job.id, promptSource: source });
+}
+
+// ---------------------------------------------------------------------------
+// setup
+// ---------------------------------------------------------------------------
+
+/** `setup --restrict <modes|none>`: write the per-repo policy. Declarative —
+ *  the listed modes become restricted-by-default, every unlisted mode falls
+ *  back to the built-in default. Written directly (no --apply): the file is
+ *  repo-local, git-ignored by convention, and trivially reversible. */
+function applyProjectPolicy(value) {
+  const cfg = loadProjectConfig() || {};
+  if (value === 'none') {
+    delete cfg.profiles;
+    if (Object.keys(cfg).length) {
+      fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + '\n');
+    } else {
+      try {
+        fs.unlinkSync(configPath());
+      } catch {}
+    }
+    process.stdout.write(`Project policy cleared — all modes use the built-in defaults again.\n\n`);
+    return false;
+  }
+
+  const modes = value.split(',').map((s) => s.trim()).filter(Boolean);
+  if (!modes.length) die('--restrict needs a value: a comma-separated list of modes, or "none" to clear');
+  for (const m of modes) {
+    if (m === 'ask') die('ask is tool-free and always restricted; it cannot be configured');
+    if (!CONFIGURABLE_MODES.includes(m)) {
+      die(`--restrict: unknown mode "${m}" (configurable: ${CONFIGURABLE_MODES.join(', ')}, or "none" to clear)`);
+    }
+  }
+  cfg.profiles = {};
+  for (const m of modes) cfg.profiles[m] = 'restricted';
+  ensureStateDir();
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + '\n');
+
+  process.stdout.write(`Project policy written: ${configPath()}\n`);
+  for (const m of modes) process.stdout.write(`  ${m}: restricted (default for this repository)\n`);
+  process.stdout.write(
+    'Unlisted modes keep the built-in default (unrestricted). A --restricted/--unrestricted flag on a\n' +
+      'call still overrides the policy. This is a per-repo, per-machine preference (.agy-crew/ is\n' +
+      'normally git-ignored, so it is not shared with the team) and a run policy, not a security\n' +
+      'boundary — for untrusted input use an isolated checkout.\n\n'
+  );
+  return true;
+}
+
+function cmdSetup(opts) {
+  // check agy availability
+  const probe = agyCommand(['--version']);
+  const v = sh(probe.cmd, probe.args);
+  if (v.code !== 0) {
+    die(
+      `agy CLI not found or not working (tried \`${AGY_BIN} --version\`).\n` +
+        'Install Google Antigravity CLI and make sure `agy` is on PATH (expected at ~/.local/bin/agy).'
+    );
+  }
+
+  let policyWritten = false;
+  if (opts.restrict !== undefined) policyWritten = applyProjectPolicy(opts.restrict);
+
+  let settings = {};
+  let exists = false;
+  try {
+    settings = JSON.parse(fs.readFileSync(AGY_SETTINGS, 'utf8'));
+    exists = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') die(`cannot read settings ${AGY_SETTINGS}: ${error.message}`);
+  }
+
+  const current = settings.permissions?.allow || [];
+  const denied = settings.permissions?.deny || [];
+  const missing = EVIDENCE_ALLOWLIST.filter((r) => !current.includes(r));
+  const missingDeny = EVIDENCE_DENYLIST.filter((r) => !denied.includes(r));
+  const poolTargets = poolSettingsTargets();
+  const poolPending = poolTargets.filter((t) => t.missing.length || t.missingDeny.length);
+
+  process.stdout.write(`agy CLI: OK (version ${v.out})\n`);
+  const profiles = loadProjectConfig()?.profiles || {};
+  const policyLine = Object.keys(profiles).length
+    ? Object.entries(profiles)
+        .map(([m, p]) => `${m}=${p}`)
+        .join(' ')
+    : '(none — built-in defaults apply)';
+  process.stdout.write(`Project policy (${configPath()}): ${policyLine}\n`);
+  process.stdout.write(`Global settings file: ${AGY_SETTINGS} ${exists ? '(exists)' : '(will be created)'}\n\n`);
+  if (!missing.length && !missingDeny.length && !poolPending.length) {
+    process.stdout.write('The evidence-gathering allow/deny rules are already installed. Nothing to do.\n');
+    printSetupNotes();
+    return;
+  }
+
+  process.stdout.write(
+    'Setup is optional hardening: research/review/implement already run unrestricted by default.\n' +
+      'It only matters if you use `--restricted`, which keeps agy\'s permission enforcement on.\n'
+  );
+  process.stdout.write('Evidence-gathering rules for restricted runs — permissions.allow:\n\n');
+  for (const r of EVIDENCE_ALLOWLIST) {
+    process.stdout.write(`  ${r}${current.includes(r) ? '  (already present)' : ''}\n`);
+  }
+  process.stdout.write('\npermissions.deny (AGY evaluates deny before ask before allow):\n\n');
+  for (const r of EVIDENCE_DENYLIST) {
+    process.stdout.write(`  ${r}${denied.includes(r) ? '  (already present)' : ''}\n`);
+  }
+  process.stdout.write(`\nMissing rules will be appended to "permissions.allow" and "permissions.deny" in ${AGY_SETTINGS}.\n`);
+  if (poolTargets.length) {
+    process.stdout.write('The same rules are applied to each pool account settings file:\n');
+    for (const t of poolTargets) process.stdout.write(`  ${t.name}: ${t.file}${t.missing.length || t.missingDeny.length ? '' : '  (already present)'}\n`);
+  }
+  process.stdout.write(
+    'Scope: this file is GLOBAL — the rules apply to every agy run on this machine, not just this repository.\n' +
+      'Broad git/gh grants avoid enumerating every task\'s commands; five deny prefixes block common risky operations.\n' +
+      'These rules are NOT read-only: other command forms, scripts and APIs can still write or cause external effects.\n'
+  );
+
+  if (!opts.apply) {
+    process.stdout.write(
+      policyWritten
+        ? '\nRULES DRY RUN — the global settings file was not touched (only the project policy above was written).\n' +
+            'The settings file will be backed up first. To apply the rules: rerun with --apply after the user confirms.\n'
+        : '\nDRY RUN — nothing written. The settings file will be backed up first.\n' +
+            'To apply: rerun with --apply after the user confirms.\n'
+    );
+    printSetupNotes();
+    return;
+  }
+
+  if (missing.length || missingDeny.length) {
+    if (exists) {
+      const backup = `${AGY_SETTINGS}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+      fs.copyFileSync(AGY_SETTINGS, backup);
+      process.stdout.write(`\nBacked up settings to ${backup}\n`);
+    } else {
+      fs.mkdirSync(path.dirname(AGY_SETTINGS), { recursive: true });
+    }
+
+    settings.permissions = settings.permissions || {};
+    settings.permissions.allow = [...current, ...missing];
+    settings.permissions.deny = [...denied, ...missingDeny];
+    fs.writeFileSync(AGY_SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+    process.stdout.write(`Wrote ${missing.length} allow-rule(s) and ${missingDeny.length} deny-rule(s) to ${AGY_SETTINGS}. Setup complete.\n`);
+  }
+  for (const target of poolTargets) applyPoolRules(target);
+  printSetupNotes();
+}
+
+/** Settings files of every pool account, with the evidence rules each one lacks. */
+function poolSettingsTargets() {
+  if (!poolExists()) return [];
+  return poolSettingsFiles().map(({ name, file }) => {
+    let settings = {};
+    try { settings = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) {
+      if (error.code !== 'ENOENT') die(`cannot read settings ${file}: ${error.message}`);
+    }
+    const allow = settings.permissions?.allow || [];
+    const deny = settings.permissions?.deny || [];
+    return { name, file, settings, allow, deny,
+      missing: EVIDENCE_ALLOWLIST.filter((r) => !allow.includes(r)),
+      missingDeny: EVIDENCE_DENYLIST.filter((r) => !deny.includes(r)) };
+  });
+}
+
+function applyPoolRules(t) {
+  if (!t.missing.length && !t.missingDeny.length) return;
+  if (fs.existsSync(t.file)) fs.copyFileSync(t.file, `${t.file}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+  else fs.mkdirSync(path.dirname(t.file), { recursive: true });
+  t.settings.permissions = t.settings.permissions || {};
+  t.settings.permissions.allow = [...t.allow, ...t.missing];
+  t.settings.permissions.deny = [...t.deny, ...t.missingDeny];
+  fs.writeFileSync(t.file, JSON.stringify(t.settings, null, 2) + '\n');
+  process.stdout.write(`Wrote ${t.missing.length} allow-rule(s) and ${t.missingDeny.length} deny-rule(s) to pool account ${t.name}: ${t.file}\n`);
+}
+
+function printSetupNotes() {
+  process.stdout.write(
+    '\nNotes:\n' +
+      '- Scope: these rules live in the GLOBAL settings file above, so they apply to every agy run on\n' +
+      '  this machine, in any repository — not only where you ran setup.\n' +
+      '- Command rules are prefix-matched by AGY, with deny > ask > allow. Existing rules are preserved.\n' +
+      '  Denied operations stay denied even when requested in the prompt; change the rules explicitly if needed.\n' +
+      '  Other command forms, scripts and APIs are not covered. This is an evidence-gathering setup,\n' +
+      '  not a read-only one or a guarantee that every irreversible action is blocked.\n' +
+      '- Security-sensitive users can scope permissions per project instead: agy supports project-scoped\n' +
+      '  permission rules (highest priority) tied to its --project system, but the exact project-settings\n' +
+      '  file path is undocumented/unverified, so this setup only edits the global file above. If a rule\n' +
+      '  seems ignored, check agy interactively for project-level overrides.\n' +
+      '- This allowlist only affects restricted runs. research/review/implement are unrestricted by\n' +
+      '  default (--dangerously-skip-permissions), and unrestricted runs ignore permission rules entirely.\n' +
+      '- Per-repo policy: `setup --restrict <mode,...>` (e.g. review,research) makes those modes default\n' +
+      '  to the restricted profile in THIS repository only; `setup --restrict none` clears it. The policy\n' +
+      '  lives in .agy-crew/config.json (normally git-ignored — a personal preference, not shared with\n' +
+      '  the team), and a --restricted/--unrestricted flag on a call always wins. It is a run policy for\n' +
+      '  consistency, not a security boundary.\n' +
+      '- Some agy tools ignore allow-rules in headless mode entirely and only work unrestricted. If a\n' +
+      '  --restricted run keeps coming back empty even after setup, drop --restricted.\n'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd) {
+    die(
+      'usage: agy-companion.mjs <staffer|research|review|implement|ask|continue|restart|observe|status|wait|result|cancel|setup|install|uninstall|accounts> [flags]\n' +
+        'flags: --restricted|--unrestricted --model <id> --effort <l|m|h> --timeout <dur> ' +
+        '--prompt <text> --prompt-file <path> --stdin --conversation <id> --continue --json (review) ' +
+        '--account <auto|live|name> (run commands, continue, restart) ' +
+        '--apply --restrict <modes|none> (setup) --hosts <a,b> --all --dry-run --status (install/uninstall)\n' +
+        'accounts <list|login|import|remove|enable|disable|cooldown clear|quota> manages the pool of private agy logins ' +
+        '(login <name>; import <name> --home <dir>; remove <name> --yes; cooldown clear <name> --family <f>; quota [<name>...] --refresh --json; list --json).\n' +
+        'task text for staffer/research/review/implement/ask/continue comes from exactly one of ' +
+        '--prompt <text>, --prompt-file <path>, or --stdin.\n' +
+        'staffer/research/review/implement run unrestricted by default (no setup needed); --restricted is the ' +
+        'hardening opt-in that uses the evidence-gathering allowlist from `setup`. ask is always tool-free. ' +
+        'Per-repo policy: `setup --restrict review,research` makes those modes restricted by default here.'
+    );
+  }
+  const opts = parseFlags(rest, { taskCommand: MODES.includes(cmd) || cmd === 'continue' });
+
+  if (MODES.includes(cmd)) return cmdRun(cmd, opts);
+  switch (cmd) {
+    case 'continue':
+      return cmdContinue(opts);
+    case 'restart':
+      return cmdRestart(opts);
+    case 'observe':
+      return renderJobResponse(findJob(opts._[0]), { observeOnly: true });
+    case 'status':
+      return cmdStatus(opts);
+    case 'wait':
+      return cmdWait(opts);
+    case 'result':
+      return cmdResult(opts);
+    case 'cancel':
+      return cmdCancel(opts);
+    case 'setup':
+      return cmdSetup(opts);
+    case 'install':
+      return cmdInstall(opts);
+    case 'uninstall':
+      return cmdUninstall(opts);
+    case 'accounts':
+      return cmdAccounts(opts, { agyCommand, liveSettings: AGY_SETTINGS });
+    case '_worker':
+      return workerMain(rest[0]);
+    default:
+      die(`unknown subcommand: ${cmd}`);
+  }
+}
+
+Promise.resolve().then(main).catch((error) => {
+  if (!error.alreadyPrinted) process.stderr.write(`${PRODUCT} error: ${error?.message || String(error)}\n`);
+  process.exitCode = error.exitCode || 1;
+});