orcacompass 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,906 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { applyAgentChoice, ConfigError, isChosen, loadConfig, parsePercent, setBans, setPin, setPreferRiskLimit, updateConfigFile, writeAgentChoice, } from './config.js';
+import { parseEffort } from './routing/effort.js';
+import { poolState } from './routing/pace.js';
+import { activeRejections } from './routing/rejection.js';
+import { agentNotFamily, agentSkipReason, banMatches, enabledInOrca, formatLaunch, headroomText, launchIds, rejectedText, route } from './routing/router.js';
+import { AGENT_IDS, DEMANDS, TIERS, } from './types.js';
+import { gather, gatherEnvironment, loadPlacements } from './routing/environment.js';
+import { AA_KEY_ENV } from './placements/sources/artificialanalysis.js';
+import { runCommand } from './system/run.js';
+import { configPath } from './paths.js';
+import { readRejections, recordRejection, writeRejections } from './routing/rejections.js';
+import { install } from './install.js';
+import { setupInfo, setupWizard } from './setup.js';
+import { verifyWorker } from './verify.js';
+const USAGE = `usage: orcacompass <command> [options]
+
+commands:
+  install [-g|--global] [-y|--yes] [-a|--agent <name>]... [--skill-only]
+                                       install the Skill, then the CLI if it is missing
+  route --tier <light|daily|advanced|frontier> [--no-downgrade] [--agent <id>]...
+        [--exclude-agent <id>]... [--demand <low|moderate|high|exceptional>]
+        [--effort <effort>] [--tier-reason <reason>] [--json]
+  verify --dispatch <id> [--wait <seconds>] [--json]
+                                       did a new worker's agent accept its model
+  rejected [--clear] [--json]          models agents refused at launch (skipped)
+  status [--json]
+  tiers [--json]                       every model's tiers, from the placement table
+  agents [--json]                     which agents are used, and why not
+  agents disable|enable|only <id>... [--json]
+  agents reset [--json]                use every agent again
+  prefer [--json]                      preferred route per tier
+  prefer <tier> <agent> [model] [--json]
+  prefer clear <tier>|--all [--json]
+  prefer --risk-limit <percent> [--json]
+  ban [<model-or-family>...] [--json]  never route these models
+  unban <model-or-family>... [--json]
+  refresh [--json]                     refetch metadata and rebuild the placement table
+  setup                                answer a few questions (needs a terminal)
+  setup --json                         what the setup questions need, for a chat setup
+  setup --complete [--json]            finish chat setup, including unchanged defaults
+  setup --skip [--json]                keep the defaults and stop offering setup`;
+class UsageError extends Error {
+}
+/** Runs one command and returns the exit code: 0 answered, 1 usage error, 2 config error. */
+export async function main(argv, io, deps = {}) {
+    const [command, ...rest] = argv;
+    try {
+        if (command === 'help' || command === '--help' || command === '-h') {
+            io.out(USAGE);
+            return 0;
+        }
+        if (command === 'route')
+            return await routeCommand(rest, io, deps);
+        if (command === 'verify')
+            return await verifyCommand(rest, io, deps);
+        if (command === 'rejected')
+            return await rejectedCommand(rest, io, deps);
+        if (command === 'status')
+            return await statusCommand(rest, io, deps);
+        if (command === 'tiers')
+            return await tiersCommand(rest, io, deps);
+        if (command === 'agents')
+            return await agentsCommand(rest, io, deps);
+        if (command === 'prefer')
+            return await preferCommand(rest, io, deps);
+        if (command === 'ban')
+            return await banCommand(rest, io, deps);
+        if (command === 'unban')
+            return await unbanCommand(rest, io, deps);
+        if (command === 'refresh')
+            return await refreshCommand(rest, io, deps);
+        if (command === 'setup')
+            return await setupCommand(rest, io, deps);
+        if (command === 'install')
+            return await installCommand(rest, io, deps);
+        throw new UsageError(command ? `unknown command: ${command}` : 'missing command');
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            io.err(`${e.message}\n\n${USAGE}`);
+            return 1;
+        }
+        if (e instanceof ConfigError) {
+            io.err(`config error: ${e.message}`);
+            return 2;
+        }
+        io.err(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}
+function parse(args, options) {
+    try {
+        return parseArgs({ args, options, strict: true, allowPositionals: false }).values;
+    }
+    catch (e) {
+        throw new UsageError(e.message);
+    }
+}
+// --- route ----------------------------------------------------------------------------------
+async function routeCommand(args, io, deps) {
+    const v = parse(args, {
+        tier: { type: 'string' },
+        'tier-reason': { type: 'string' },
+        'no-downgrade': { type: 'boolean' },
+        agent: { type: 'string', multiple: true },
+        'exclude-agent': { type: 'string', multiple: true },
+        effort: { type: 'string' },
+        demand: { type: 'string' },
+        json: { type: 'boolean' },
+    });
+    if (v.tier === undefined)
+        throw new UsageError(`--tier is required (${TIERS.join(', ')})`);
+    const tier = v.tier.toLowerCase();
+    if (!TIERS.includes(tier))
+        throw new UsageError(`unknown tier "${v.tier}" (expected ${TIERS.join(', ')})`);
+    const tierReason = v['tier-reason']?.trim();
+    if (tierReason === '')
+        throw new UsageError('--tier-reason must contain a short explanation');
+    let effort;
+    if (v.effort !== undefined) {
+        effort = parseEffort(v.effort);
+        if (!effort)
+            throw new UsageError(`unknown effort "${v.effort}"`);
+    }
+    let demand;
+    if (v.demand !== undefined) {
+        demand = v.demand.toLowerCase();
+        if (!DEMANDS.includes(demand))
+            throw new UsageError(`unknown demand "${v.demand}" (expected ${DEMANDS.join(', ')})`);
+    }
+    // An unknown id is not an error: the route goes on and a warning suggests the id that was probably meant.
+    const unknownAgents = [];
+    const agentIds = (raw, flag, effect) => raw?.map((r) => {
+        const id = r.toLowerCase();
+        if (!AGENT_IDS.includes(id)) {
+            const guess = suggestAgent(id);
+            unknownAgents.push(`unknown agent "${r}" in ${flag}: ${effect} (${guess ? `did you mean ${guess}?` : `known: ${AGENT_IDS.join(', ')}`})`);
+        }
+        return id;
+    });
+    const agents = agentIds(v.agent, '--agent', 'not routed');
+    const excludeAgents = agentIds(v['exclude-agent'], '--exclude-agent', 'nothing excluded for it');
+    const req = {
+        tier,
+        ...(tierReason ? { tierReason } : {}),
+        ...(v['no-downgrade'] ? { noDowngrade: true } : {}),
+        ...(agents ? { agents } : {}),
+        ...(excludeAgents ? { excludeAgents } : {}),
+        ...(effort ? { effort } : {}),
+        ...(demand ? { demand } : {}),
+    };
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    const d = route(req, env, config);
+    d.warnings.push(...unknownAgents);
+    if (v.json) {
+        const sources = {
+            catalogSource: env.catalogSource, scoreSource: env.scoreSource ?? 'unavailable', benchmarkSource: env.benchmarkSource ?? 'unavailable',
+            placementsBuiltAt: env.placementsBuiltAt,
+        };
+        io.out(JSON.stringify({ ...d, launch: formatLaunch(d) ?? null, ...sources }, null, 2));
+    }
+    else
+        io.out(decisionText(d, env.now).join('\n'));
+    return 0;
+}
+/** Executable names people use for an agent, e.g. Cursor's CLI is `cursor-agent`. */
+const AGENT_ALIASES = { 'cursor-agent': 'cursor', agy: 'antigravity', 'claude-code': 'claude' };
+/** The agent id an unknown id most likely meant: an executable alias, or a known id within two edits. */
+function suggestAgent(id) {
+    if (AGENT_ALIASES[id])
+        return AGENT_ALIASES[id];
+    const distance = (a, b) => {
+        let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+        for (let i = 1; i <= a.length; i++) {
+            const row = [i];
+            for (let j = 1; j <= b.length; j++)
+                row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = row;
+        }
+        return prev[b.length];
+    };
+    let best;
+    for (const known of AGENT_IDS) {
+        const d = distance(id, known);
+        if (d <= 2 && (!best || d < best.d))
+            best = { id: known, d };
+    }
+    return best?.id;
+}
+function decisionText(d, now) {
+    let head;
+    if (d.status === 'ok' && d.route) {
+        const { agent, model, effort } = d.route;
+        head = `${d.tier} → ${agent} · ${model}${effort ? ` · ${effort}` : ''} (${d.confidence} confidence)`;
+    }
+    else if (d.status === 'wait' && d.waitUntil !== undefined) {
+        head = `${d.requestedTier} → wait until ${new Date(d.waitUntil).toISOString()} (in ${duration(d.waitUntil - now)})`;
+    }
+    else {
+        head = `${d.requestedTier} → no route`;
+    }
+    const launch = formatLaunch(d);
+    return [head, ...d.reasons.map((r) => `  ${r}`), ...d.warnings.map((w) => `  warning: ${w}`), ...(launch ? [launch] : [])];
+}
+// --- verify and rejected --------------------------------------------------------------------
+async function verifyCommand(args, io, deps) {
+    const v = parse(args, { dispatch: { type: 'string' }, wait: { type: 'string' }, json: { type: 'boolean' } });
+    if (!v.dispatch)
+        throw new UsageError('--dispatch <id> is required (the dispatchId worker-start printed)');
+    const wait = v.wait === undefined ? 60 : Number(v.wait);
+    if (!Number.isFinite(wait) || wait < 0 || wait > 60)
+        throw new UsageError(`--wait must be between 0 and 60 seconds (got "${v.wait}")`);
+    const config = loadConfig();
+    const clock = deps.clock ?? Date.now;
+    const verdict = await verifyWorker(v.dispatch, {
+        run: deps.run ?? runCommand,
+        sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        clock,
+    }, { waitMs: wait * 1000 });
+    let skipHours;
+    if (verdict.status === 'rejected' && verdict.agent && verdict.model && verdict.message) {
+        recordRejection({ agent: verdict.agent, model: verdict.model, message: verdict.message, at: clock() }, config.rejectionTtlHours);
+        skipHours = config.rejectionTtlHours;
+    }
+    const next = verifyNext(verdict, skipHours);
+    if (v.json)
+        io.out(JSON.stringify({ ...verdict, ...(skipHours !== undefined ? { skippedForHours: skipHours } : {}), next }, null, 2));
+    else
+        io.out(verifyText(verdict, next).join('\n'));
+    return 0;
+}
+/** What the coordinator does next, in order. */
+function verifyNext(d, skipHours) {
+    const retry = `start the replacement on the same Task: orca orchestration worker-start --task ${d.taskId ?? '<task_id>'} --retry-of ${d.dispatchId} --worktree <same placement> <new launchArgs> --json`;
+    const cleanup = d.cleanup.map((argv) => argv.join(' ')).join(', then ');
+    const exclude = `--exclude-agent ${d.agent ?? '<agent>'}`;
+    switch (d.status) {
+        case 'started':
+        case 'reported':
+            return ['nothing: wait for worker_done as usual'];
+        case 'rejected':
+            return [
+                `clean up: ${cleanup}`,
+                `route again with the same flags; ${d.agent} ${d.model} is skipped${skipHours !== undefined ? ` for ${skipHours}h` : ''}`,
+                retry,
+            ];
+        case 'failed':
+            return [
+                `clean up: ${cleanup}`,
+                `if the tail shows the agent failing to start, route again with ${exclude} for this job`,
+                retry,
+                'tell the user which agent failed to start, why, and how they can fix it',
+            ];
+        case 'stalled':
+            return [
+                'read the tail: the agent ended its turn without worker_done',
+                `if it reports an error (model, account, limits): orca orchestration worker-stop --dispatch ${d.dispatchId} --json, then route again with ${exclude} and start the replacement with --retry-of ${d.dispatchId}`,
+                'if it asks a question, answer it in its terminal; otherwise keep waiting',
+            ];
+        default:
+            return ['keep waiting as usual; run verify again later or read the terminal'];
+    }
+}
+function verifyText(d, next) {
+    const who = d.agent && d.model ? `${d.agent} · ${d.model}` : d.dispatchId;
+    const lines = [`${d.status}: ${who} — ${d.detail}`];
+    if (d.message)
+        lines.push(`  agent said: ${d.message}`);
+    for (const l of d.tail ?? [])
+        lines.push(`  | ${l}`);
+    lines.push('next:', ...next.map((n, i) => `  ${i + 1}. ${n}`));
+    return lines;
+}
+async function rejectedCommand(args, io, deps) {
+    const v = parse(args, { clear: { type: 'boolean' }, json: { type: 'boolean' } });
+    const config = loadConfig();
+    const now = deps.now ?? Date.now();
+    const all = readRejections();
+    if (v.clear)
+        writeRejections([]);
+    const active = v.clear ? [] : activeRejections(all, now, config.rejectionTtlHours);
+    if (v.json) {
+        io.out(JSON.stringify({ rejectionTtlHours: config.rejectionTtlHours, cleared: v.clear ? all.length : 0, rejections: active }, null, 2));
+        return 0;
+    }
+    if (v.clear)
+        io.out(`forgot ${all.length} refused model${all.length === 1 ? '' : 's'}`);
+    else if (active.length === 0)
+        io.out('no refused models');
+    else {
+        io.out([
+            `refused at launch, skipped for ${config.rejectionTtlHours}h after:`,
+            ...active.map((r) => `  ${r.agent} ${r.model}: ${rejectedText(r, now)}`),
+        ].join('\n'));
+    }
+    return 0;
+}
+function buildStatus(gathered, config) {
+    const { env, table } = gathered;
+    const skipped = new Map();
+    const banned = new Map();
+    const tiers = {};
+    for (const tier of TIERS) {
+        const d = route({ tier, noDowngrade: true }, env, config);
+        for (const s of d.skipped) {
+            if (s.model) {
+                if (s.reason === 'banned by you')
+                    banned.set(`${s.agent} ${s.model}`, { agent: s.agent, model: s.model });
+            }
+            else {
+                skipped.set(s.agent, s.reason);
+            }
+        }
+        // A structural upgrade belongs to another tier; this view lists only the tier's own candidates.
+        const own = d.tier === undefined || d.tier === tier;
+        const view = { status: own ? d.status : 'none', alternatives: own ? d.alternatives : [], warnings: own ? d.warnings : [] };
+        if (own && d.route) {
+            const prefix = `${d.route.agent} ${d.route.model}: `;
+            const reason = d.reasons[0] ?? '';
+            view.pick = { ...d.route, confidence: d.confidence, reason: reason.startsWith(prefix) ? reason.slice(prefix.length) : reason };
+        }
+        if (own && d.waitUntil !== undefined)
+            view.waitUntil = d.waitUntil;
+        tiers[tier] = view;
+    }
+    const agents = env.discoveries.map((disc) => {
+        const u = env.usage[disc.agent];
+        const usage = u && {
+            status: u.status,
+            ...(u.updatedAt !== undefined ? { updatedAt: u.updatedAt } : {}),
+            ...(u.error ? { error: u.error } : {}),
+            pools: Object.values(u.pools).map((p) => {
+                const s = poolState(p, env.now, config.thresholds);
+                return { ...p, headroom: Math.round(s.headroom * 100) / 100, expired: s.expired, blocked: s.blocked };
+            }),
+        };
+        const reason = skipped.get(disc.agent);
+        return {
+            agent: disc.agent,
+            installed: disc.installed,
+            enabledInOrca: enabledInOrca(env.orcaAgents, disc.agent),
+            models: disc.models.length,
+            usage: usage ?? null,
+            ...(disc.note ? { note: disc.note } : {}),
+            ...(reason ? { skipped: reason } : {}),
+        };
+    });
+    const unclassified = [];
+    const scored = [];
+    for (const disc of env.discoveries) {
+        for (const m of disc.models) {
+            if (m.placements.length === 0)
+                unclassified.push({ agent: disc.agent, model: m.modelId });
+            for (const cls of m.placements) {
+                if (cls.detail)
+                    scored.push({ agent: disc.agent, model: m.modelId, tier: cls.tier, detail: cls.detail });
+            }
+        }
+    }
+    return {
+        now: env.now,
+        catalog: table.sources.catalog,
+        scores: table.sources.scores,
+        benchmarks: table.sources.benchmarks,
+        placements: placementsView(gathered, env.now),
+        orcaAgents: env.orcaAgents ?? null,
+        agents,
+        banned: [...banned.values()],
+        rejected: env.rejections ?? [],
+        tiers,
+        scored,
+        unclassified,
+    };
+}
+function statusText(s) {
+    const { catalog, now } = s;
+    const lines = [
+        `catalog: ${catalog.source}, ${catalog.models} models, fetched ${duration(now - catalog.fetchedAt)} ago`,
+        s.scores
+            ? `scores: ${s.scores.source}, ${s.scores.models} models (The Model Index, CC BY 4.0), fetched ${duration(now - s.scores.fetchedAt)} ago`
+            : 'scores: unavailable (only the family table assigns tiers)',
+        s.benchmarks
+            ? `benchmarks: ${s.benchmarks.source}, ${s.benchmarks.models} models (Source: Artificial Analysis, artificialanalysis.ai), fetched ${duration(now - s.benchmarks.fetchedAt)} ago`
+            : `benchmarks: unavailable (set ${AA_KEY_ENV} to your Artificial Analysis key and run orcacompass refresh)`,
+        ...placementsLines(s.placements, now),
+        orcaAgentsLine(s.orcaAgents ?? undefined),
+        'agents:',
+    ];
+    const width = Math.max(...s.agents.map((a) => a.agent.length));
+    for (const a of s.agents) {
+        const name = a.agent.padEnd(width);
+        if (!a.installed) {
+            lines.push(`  ${name}  not installed${a.note ? ` (${a.note})` : ''}`);
+            continue;
+        }
+        const u = a.usage;
+        const usage = !u ? 'no usage data' : u.status === 'ok' ? `usage ok${u.updatedAt !== undefined ? `, updated ${duration(now - u.updatedAt)} ago` : ''}` : `usage ${u.status}${u.error ? `: ${u.error}` : ''}`;
+        lines.push(`  ${name}  ${a.models} models, ${usage}${a.skipped ? ` — skipped: ${a.skipped}` : ''}`);
+        if (a.note)
+            lines.push(`  ${' '.repeat(width)}  ${a.note}`);
+        for (const p of u?.pools ?? []) {
+            const state = p.expired ? ' (expired)' : p.blocked ? ' (blocked)' : '';
+            lines.push(`    ${p.name.replace(/^bucket:/, '')}: ${percent(p.usedPercent)} used, resets in ${duration(p.resetsAt - now)}, headroom ${headroomText(p.headroom)}${state}`);
+        }
+    }
+    lines.push('tiers:');
+    for (const tier of TIERS) {
+        const t = s.tiers[tier];
+        const label = tier.padEnd(8);
+        if (t.pick) {
+            const { agent, model, effort, confidence, reason } = t.pick;
+            lines.push(`  ${label}  ${agent} · ${model}${effort ? ` · ${effort}` : ''} (${confidence}) — ${reason}`);
+        }
+        else if (t.status === 'wait' && t.waitUntil !== undefined) {
+            lines.push(`  ${label}  all blocked; wait ${duration(t.waitUntil - now)}`);
+        }
+        else {
+            lines.push(`  ${label}  no candidates`);
+        }
+        for (const w of t.warnings)
+            lines.push(`  ${' '.repeat(8)}    warning: ${w}`);
+        for (const alt of t.alternatives.slice(0, 3)) {
+            lines.push(`  ${' '.repeat(8)}    alt: ${alt.agent} · ${alt.model}${alt.effort ? ` · ${alt.effort}` : ''}${alt.blocked ? ' (blocked)' : ''} — ${alt.reason}`);
+        }
+    }
+    if (s.banned.length > 0)
+        lines.push(`banned by you: ${s.banned.map((b) => `${b.agent} ${b.model}`).join(', ')}`);
+    for (const r of s.rejected)
+        lines.push(`skipped ${r.agent} ${r.model}, ${rejectedText(r, now)} (orcacompass rejected --clear forgets it)`);
+    if (s.scored.length > 0) {
+        lines.push(`placements explained (lineup, benchmarks, capability score): ${s.scored.length}`);
+        // OpenCode can place a hundred OpenRouter models by score: past 30, an agent shows 15.
+        const total = new Map();
+        for (const x of s.scored)
+            total.set(x.agent, (total.get(x.agent) ?? 0) + 1);
+        const shown = new Map();
+        for (const x of s.scored) {
+            const n = (shown.get(x.agent) ?? 0) + 1;
+            shown.set(x.agent, n);
+            if (total.get(x.agent) <= 30 || n <= 15)
+                lines.push(`  ${x.agent} ${x.model}: tier ${x.tier} from ${x.detail}`);
+        }
+        for (const [agent, n] of total)
+            if (n > 30)
+                lines.push(`  ${agent}: … ${n - 15} more (status --json lists them)`);
+    }
+    if (s.unclassified.length > 0) {
+        lines.push(`unclassified (never routed): ${s.unclassified.length}`);
+        const byAgent = new Map();
+        for (const u of s.unclassified)
+            byAgent.set(u.agent, [...(byAgent.get(u.agent) ?? []), u.model]);
+        // OpenCode can list hundreds of OpenRouter models; status --json has them all.
+        for (const [agent, models] of byAgent) {
+            const more = models.length > 15 ? `, … ${models.length - 15} more` : '';
+            lines.push(`  ${agent}: ${models.slice(0, 15).join(', ')}${more}`);
+        }
+    }
+    return lines;
+}
+async function statusCommand(args, io, deps) {
+    const v = parse(args, { json: { type: 'boolean' } });
+    const config = loadConfig();
+    const s = buildStatus(await gather(config, deps), config);
+    io.out(v.json ? JSON.stringify(s, null, 2) : statusText(s).join('\n'));
+    return 0;
+}
+// --- agents ---------------------------------------------------------------------------------
+const ACTIONS = ['disable', 'enable', 'only', 'reset'];
+function orcaAgentsLine(o) {
+    if (!o)
+        return 'orca agent switches: not read; every installed agent counts as enabled';
+    if (!o.known)
+        return `orca agent switches: unknown (${o.reason}); every installed agent counts as enabled`;
+    return `orca agent switches: read from ${o.source} (experimental); disabled: ${o.disabled.join(', ') || 'none'}`;
+}
+async function agentsCommand(args, io, deps) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args, options: { json: { type: 'boolean' } }, strict: true, allowPositionals: true });
+    }
+    catch (e) {
+        throw new UsageError(e.message);
+    }
+    const json = parsed.values.json === true;
+    const [action, ...rawIds] = parsed.positionals;
+    if (action === undefined)
+        return listAgents(json, io, deps);
+    if (!ACTIONS.includes(action))
+        throw new UsageError(`unknown agents action "${action}" (expected ${ACTIONS.join(', ')})`);
+    if (action === 'reset' && rawIds.length > 0)
+        throw new UsageError('agents reset takes no agent ids');
+    if (action !== 'reset' && rawIds.length === 0)
+        throw new UsageError(`agents ${action} needs at least one agent id (${AGENT_IDS.join(', ')})`);
+    const ids = rawIds.map((id) => id.toLowerCase());
+    const bad = rawIds.find((_, i) => !AGENT_IDS.includes(ids[i]));
+    if (bad !== undefined)
+        throw new UsageError(`unknown agent "${bad}" (known: ${AGENT_IDS.join(', ')})`);
+    const next = applyAgentChoice(loadConfig(), action, ids);
+    writeAgentChoice(next);
+    const chosen = AGENT_IDS.filter((a) => isChosen(a, next));
+    const notChosen = AGENT_IDS.filter((a) => !isChosen(a, next));
+    if (json) {
+        io.out(JSON.stringify({ configPath: configPath(), allowAgents: next.allowAgents ?? null, denyAgents: next.denyAgents, chosen, notChosen }, null, 2));
+    }
+    else {
+        io.out([`wrote ${configPath()}`, `chosen: ${chosen.join(', ') || 'none'}`, `not chosen: ${notChosen.join(', ') || 'none'}`].join('\n'));
+    }
+    return 0;
+}
+async function listAgents(json, io, deps) {
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    const agents = env.discoveries.map((d) => {
+        const usage = env.usage[d.agent];
+        const reason = agentSkipReason(d, env, config);
+        return {
+            agent: d.agent,
+            installed: d.installed,
+            enabledInOrca: enabledInOrca(env.orcaAgents, d.agent),
+            orcaUsage: usage?.status ?? 'unknown',
+            ...(usage && usage.status !== 'ok' && usage.error ? { orcaUsageError: usage.error } : {}),
+            chosen: isChosen(d.agent, config),
+            used: reason === undefined,
+            verdict: reason !== undefined ? `not used: ${reason}` : config.lastResortAgents.includes(d.agent) ? 'used as last resort' : 'used',
+        };
+    });
+    if (json) {
+        const choice = { configPath: configPath(), allowAgents: config.allowAgents ?? null, denyAgents: config.denyAgents };
+        io.out(JSON.stringify({ orcaAgents: env.orcaAgents ?? null, ...choice, agents }, null, 2));
+        return 0;
+    }
+    const yes = (b) => (b ? 'yes' : 'no');
+    const rows = [
+        ['agent', 'installed', 'enabled in Orca', 'Orca usage', 'chosen', 'verdict'],
+        ...agents.map((a) => [a.agent, yes(a.installed), a.enabledInOrca, a.orcaUsage, yes(a.chosen), a.verdict]),
+    ];
+    const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    const lines = [orcaAgentsLine(env.orcaAgents), `config: ${configPath()}`, ''];
+    for (const r of rows)
+        lines.push(r.map((cell, i) => (i === r.length - 1 ? cell : cell.padEnd(widths[i]))).join('  '));
+    io.out(lines.join('\n'));
+    return 0;
+}
+// --- prefer ---------------------------------------------------------------------------------
+const prefLabel = (p) => (!p ? 'none' : p.model ? `${p.agent} ${p.model}` : `${p.agent} (its best model)`);
+function parsePositionals(args, options) {
+    try {
+        return parseArgs({ args, options, strict: true, allowPositionals: true });
+    }
+    catch (e) {
+        throw new UsageError(e.message);
+    }
+}
+function agentId(raw) {
+    const id = raw.toLowerCase();
+    if (!AGENT_IDS.includes(id))
+        throw new UsageError(`unknown agent "${raw}" (known: ${AGENT_IDS.join(', ')})`);
+    return id;
+}
+function tierOf(raw) {
+    const tier = raw.toLowerCase();
+    if (!TIERS.includes(tier))
+        throw new UsageError(`unknown tier "${raw}" (expected ${TIERS.join(', ')})`);
+    return tier;
+}
+async function preferCommand(args, io, deps) {
+    const { values, positionals } = parsePositionals(args, { json: { type: 'boolean' }, all: { type: 'boolean' }, 'risk-limit': { type: 'string' } });
+    const json = values.json === true;
+    const show = (config) => {
+        if (json) {
+            io.out(JSON.stringify({ configPath: configPath(), preferRiskLimit: config.preferRiskLimit, pins: config.pins }, null, 2));
+            return;
+        }
+        const lines = [`preferred routes (above ${config.preferRiskLimit}% projected usage, switch only to a known within-limit alternative):`];
+        for (const tier of TIERS)
+            lines.push(`  ${tier.padEnd(8)}  ${prefLabel(config.pins[tier])}`);
+        io.out(lines.join('\n'));
+    };
+    const rawLimit = values['risk-limit'];
+    if (typeof rawLimit === 'string') {
+        if (positionals.length > 0 || values.all)
+            throw new UsageError('use "prefer --risk-limit <percent>" on its own');
+        const limit = parsePercent(rawLimit);
+        if (limit === undefined)
+            throw new UsageError(`--risk-limit must be a non-negative percent (got "${rawLimit}")`);
+        loadConfig();
+        updateConfigFile((raw) => setPreferRiskLimit(raw, limit));
+        if (!json)
+            io.out(`wrote ${configPath()}`);
+        show(loadConfig());
+        return 0;
+    }
+    if (positionals.length === 0) {
+        if (values.all)
+            throw new UsageError('--all only goes with "prefer clear"');
+        show(loadConfig());
+        return 0;
+    }
+    if (positionals[0] === 'clear') {
+        const rest = positionals.slice(1);
+        if (values.all ? rest.length > 0 : rest.length !== 1)
+            throw new UsageError('use "prefer clear <tier>" or "prefer clear --all"');
+        const tier = values.all ? undefined : tierOf(rest[0]);
+        loadConfig();
+        updateConfigFile((raw) => {
+            for (const t of tier ? [tier] : TIERS)
+                setPin(raw, t, undefined);
+        });
+        if (!json)
+            io.out(`wrote ${configPath()}`);
+        show(loadConfig());
+        return 0;
+    }
+    if (values.all)
+        throw new UsageError('--all only goes with "prefer clear"');
+    if (positionals.length < 2 || positionals.length > 3)
+        throw new UsageError('use "prefer <tier> <agent> [model]"');
+    const tier = tierOf(positionals[0]);
+    const agent = agentId(positionals[1]);
+    const model = positionals[2];
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    const disc = env.discoveries.find((d) => d.agent === agent);
+    if (!disc?.installed || disc.models.length === 0) {
+        const state = disc?.installed ? 'lists no models' : 'is not installed';
+        io.err(`warning: ${agent} ${state} right now; saved${model ? ' without checking the model' : ''}`);
+    }
+    else if (model && !disc.models.some((m) => launchIds(m).includes(model))) {
+        const known = disc.models.map((m) => m.modelId);
+        throw new UsageError(`unknown model "${model}" for ${agent} (known: ${known.slice(0, 12).join(', ')}${known.length > 12 ? ', …' : ''})`);
+    }
+    const pin = { agent, ...(model ? { model } : {}) };
+    updateConfigFile((raw) => setPin(raw, tier, pin));
+    if (json)
+        show(loadConfig());
+    else
+        io.out([`wrote ${configPath()}`, `${tier} → ${prefLabel(pin)}`].join('\n'));
+    return 0;
+}
+// --- ban ------------------------------------------------------------------------------------
+async function banCommand(args, io, deps) {
+    const { values, positionals } = parsePositionals(args, { json: { type: 'boolean' } });
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    const entries = [...new Set(positionals.map((e) => e.trim().toLowerCase()))];
+    const next = [...config.banModels];
+    if (entries.length > 0) {
+        const matches = banMatches(entries, env);
+        // An agent id is refused unless it is also a model family (grok); check them all before saying anything.
+        const agent = agentNotFamily(entries, matches);
+        if (agent)
+            throw new UsageError(`"${agent}" is an agent; to stop using it run: orcacompass agents disable ${agent}`);
+        for (const entry of entries) {
+            if (AGENT_IDS.includes(entry)) {
+                io.err(`note: "${entry}" bans the ${entry} model family; to stop using the ${agentName(entry)} agent run: orcacompass agents disable ${entry}`);
+            }
+            if (matches[entry].length === 0)
+                io.err(`warning: "${entry}" matches no model discovered right now; saved anyway`);
+            if (!next.includes(entry))
+                next.push(entry);
+        }
+        writeBans(next);
+    }
+    showBans(next, env, values.json === true, entries.length > 0, io);
+    return 0;
+}
+async function unbanCommand(args, io, deps) {
+    const { values, positionals } = parsePositionals(args, { json: { type: 'boolean' } });
+    if (positionals.length === 0)
+        throw new UsageError('use "unban <model-or-family>..."');
+    const entries = positionals.map((e) => e.trim().toLowerCase());
+    const config = loadConfig();
+    for (const entry of entries)
+        if (!config.banModels.includes(entry))
+            io.err(`warning: "${entry}" was not banned`);
+    const next = config.banModels.filter((b) => !entries.includes(b));
+    writeBans(next);
+    showBans(next, await gatherEnvironment(config, deps), values.json === true, true, io);
+    return 0;
+}
+const agentName = (id) => (id === 'grok' ? 'Grok Build' : id);
+function writeBans(banModels) {
+    updateConfigFile((raw) => setBans(raw, banModels));
+}
+function showBans(banModels, env, json, wrote, io) {
+    const matches = banMatches(banModels, env);
+    if (json) {
+        io.out(JSON.stringify({ configPath: configPath(), banModels, matches }, null, 2));
+        return;
+    }
+    const lines = wrote ? [`wrote ${configPath()}`] : [];
+    if (banModels.length === 0)
+        lines.push('banned by you: none');
+    else {
+        lines.push('banned by you:');
+        for (const entry of banModels) {
+            const found = matches[entry].map((m) => `${m.agent} ${m.model}`);
+            lines.push(`  ${entry}  ${found.length ? found.join(', ') : '(matches nothing discovered right now)'}`);
+        }
+    }
+    io.out(lines.join('\n'));
+}
+// --- refresh --------------------------------------------------------------------------------
+async function refreshCommand(args, io, deps) {
+    const v = parse(args, { json: { type: 'boolean' } });
+    const config = loadConfig();
+    const key = (deps.env ?? process.env)[AA_KEY_ENV];
+    const { table, saveError } = await loadPlacements(config, { ...deps, refresh: true });
+    const { catalog: c, scores: r, benchmarks: b } = table.sources;
+    const at = (t) => new Date(t).toISOString();
+    if (c.source !== 'network')
+        io.err(`could not reach models.dev; still using the ${c.source} from ${at(c.fetchedAt)}`);
+    if (r?.source !== 'network') {
+        io.err(`could not reach themodelindex.org; ${r ? `still using the ${r.source} from ${at(r.fetchedAt)}` : 'no scores available'}`);
+    }
+    // No key is the normal opt-out, reported in the output rather than as an error.
+    if (key && b?.source !== 'network')
+        io.err(`could not reach artificialanalysis.ai; ${b ? `still using the cache from ${at(b.fetchedAt)}` : 'no benchmarks available'}`);
+    if (saveError !== undefined)
+        io.err(`placements: could not be saved: ${saveError}`);
+    const models = table.agents.reduce((n, a) => n + a.models.length, 0);
+    const placements = { builtAt: table.builtAt, models, agents: table.agents.length };
+    if (v.json) {
+        io.out(JSON.stringify({ source: c.source, fetchedAt: c.fetchedAt, models: c.models, scores: r, benchmarks: b, placements }, null, 2));
+    }
+    else {
+        const scoreLine = r ? `${r.source}, ${r.models} rated models (fetched ${at(r.fetchedAt)})` : 'unavailable';
+        const benchLine = b
+            ? `${b.source}, ${b.models} benchmarked models (fetched ${at(b.fetchedAt)})`
+            : `unavailable${key ? '' : ` (set ${AA_KEY_ENV} to your Artificial Analysis key to fetch)`}`;
+        io.out([
+            `models.dev: ${c.source}, ${c.models} models (fetched ${at(c.fetchedAt)})`,
+            `model index: ${scoreLine}`,
+            `artificial analysis: ${benchLine}`,
+            `placements: ${models} models across ${table.agents.length} agents (built now)`,
+        ].join('\n'));
+    }
+    return 0;
+}
+// --- tiers ----------------------------------------------------------------------------------
+/** Plain words for why the table was rebuilt on this call. */
+const REBUILT_WORDS = {
+    missing: 'no table yet',
+    invalid: 'table unreadable',
+    version: 'older version',
+    expired: 'table expired',
+    config: 'config changed',
+    'agent-appeared': 'new agent on PATH',
+    refresh: 'refresh asked',
+};
+function placementsView(g, now) {
+    const { table } = g;
+    return {
+        builtAt: table.builtAt,
+        age: Math.max(0, now - table.builtAt),
+        version: table.version,
+        rebuilt: g.rebuilt ?? null,
+        saveError: g.saveError ?? null,
+        benchmarkScale: table.sources.benchmarkScale,
+        scoreScale: table.sources.scoreScale,
+    };
+}
+function placementsLines(p, now) {
+    const built = p.rebuilt ? `built now: ${REBUILT_WORDS[p.rebuilt]}` : `built ${duration(now - p.builtAt)} ago`;
+    const lines = [`placements: ${built} (orcacompass ${p.version})`];
+    if (p.saveError)
+        lines.push(`placements: could not be saved: ${p.saveError}`);
+    return lines;
+}
+function tiersText(table, view, now) {
+    const { catalog, scores, benchmarks, benchmarkScale } = table.sources;
+    const lines = [
+        ...placementsLines(view, now),
+        `catalog: ${catalog.source}, ${catalog.models} models; scores: ${scores ? `${scores.source}, ${scores.models} models` : 'unavailable'}; benchmarks: ${benchmarks ? `${benchmarks.source}, ${benchmarks.models} models` : 'unavailable'}`,
+    ];
+    if (benchmarkScale) {
+        const median = benchmarkScale.medianValue === null ? 'no prices' : `median ${benchmarkScale.medianValue.toFixed(1)} points per dollar`;
+        lines.push(`benchmark scale: top ${benchmarkScale.top.toFixed(1)}, ${median}`);
+    }
+    const rows = table.agents.flatMap((a) => a.models.flatMap((m) => m.placements.map((c) => ({ agent: a.agent, model: m.modelId, tier: c.tier, detail: c.detail ?? c.source }))));
+    rows.sort((x, y) => (x.agent < y.agent ? -1 : x.agent > y.agent ? 1 : x.model < y.model ? -1 : x.model > y.model ? 1 : 0));
+    for (const tier of TIERS) {
+        lines.push(`${tier}:`);
+        for (const r of rows.filter((x) => x.tier === tier))
+            lines.push(`  ${r.agent} ${r.model}  ${r.detail}`);
+    }
+    const unclassified = table.agents.flatMap((a) => a.models.filter((m) => m.placements.length === 0).map((m) => ({ agent: a.agent, model: m.modelId })));
+    lines.push(`unclassified: ${unclassified.length}`);
+    const byAgent = new Map();
+    for (const u of unclassified)
+        byAgent.set(u.agent, [...(byAgent.get(u.agent) ?? []), u.model]);
+    // OpenCode can list hundreds of OpenRouter models; tiers --json has them all.
+    for (const [agent, models] of byAgent) {
+        const more = models.length > 15 ? `, … ${models.length - 15} more` : '';
+        lines.push(`  ${agent}: ${models.slice(0, 15).join(', ')}${more}`);
+    }
+    return lines;
+}
+async function tiersCommand(args, io, deps) {
+    const v = parse(args, { json: { type: 'boolean' } });
+    const config = loadConfig();
+    const now = deps.now ?? Date.now();
+    const loaded = await loadPlacements(config, { ...deps, now });
+    const view = placementsView(loaded, now);
+    io.out(v.json ? JSON.stringify({ ...loaded.table, age: view.age }, null, 2) : tiersText(loaded.table, view, now).join('\n'));
+    return 0;
+}
+// --- install --------------------------------------------------------------------------------
+async function installCommand(args, io, deps) {
+    const v = parse(args, {
+        global: { type: 'boolean', short: 'g' },
+        yes: { type: 'boolean', short: 'y' },
+        agent: { type: 'string', short: 'a', multiple: true },
+        'skill-only': { type: 'boolean' },
+    });
+    // The installer asks which agents and where; without a terminal nobody can answer.
+    if (!deps.terminal && !v.yes) {
+        io.err('orcacompass install asks questions in a terminal, and this is not one. Run it in a terminal, or add --yes (with --global and --agent <name> to choose).');
+        return 1;
+    }
+    return install({ global: v.global, yes: v.yes, agents: v.agent, skillOnly: v['skill-only'] }, { log: io.out, ...deps.install });
+}
+// --- setup ----------------------------------------------------------------------------------
+async function setupCommand(args, io, deps) {
+    const v = parse(args, { json: { type: 'boolean' }, skip: { type: 'boolean' }, complete: { type: 'boolean' } });
+    if (v.skip && v.complete)
+        throw new UsageError('choose either --complete or --skip');
+    if (v.skip)
+        return skipSetup(v.json, io, deps);
+    if (!v.json && !v.complete && !deps.terminal) {
+        io.err([
+            'orcacompass setup asks its questions in a terminal, and this is not one.',
+            'In chat, ask your orchestrator to set up OrcaCompass: it reads `orcacompass setup --json` and asks the same questions.',
+            'Or set things one at a time: orcacompass agents, orcacompass prefer, orcacompass ban.',
+        ].join('\n'));
+        return 1;
+    }
+    if (v.complete && !existsSync(configPath()))
+        updateConfigFile(() => { });
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    if (v.json) {
+        io.out(JSON.stringify(setupInfo(env, config), null, 2));
+        return 0;
+    }
+    if (v.complete) {
+        io.out(`Setup complete. Config: ${configPath()}`);
+        return 0;
+    }
+    return setupWizard(deps.terminal, env, config);
+}
+/** The user declined setup: create an empty config file, if there is none, so setup is not offered again. */
+async function skipSetup(json, io, deps) {
+    if (!existsSync(configPath()))
+        updateConfigFile(() => { });
+    const config = loadConfig();
+    const env = await gatherEnvironment(config, deps);
+    const used = env.discoveries.filter((d) => !agentSkipReason(d, env, config)).map((d) => d.agent);
+    const orca = env.orcaAgents?.known ? 'they follow the agents enabled in Orca' : "Orca's agent switches could not be read";
+    if (json) {
+        io.out(JSON.stringify({ configPath: configPath(), agentsUsed: used, orcaAgents: env.orcaAgents ?? null }, null, 2));
+    }
+    else {
+        io.out(`Setup skipped; defaults kept in ${configPath()}.
+Agents used now: ${used.join(', ') || 'none'} (${orca}).`);
+    }
+    return 0;
+}
+// --- formatting -----------------------------------------------------------------------------
+const percent = (n) => `${Number.isInteger(n) ? n : n.toFixed(1)}%`;
+function duration(ms) {
+    if (ms <= 0)
+        return '0m';
+    const days = Math.floor(ms / 86_400_000);
+    if (days >= 1)
+        return `${days}d`;
+    const hours = Math.floor(ms / 3_600_000);
+    if (hours >= 1)
+        return `${hours}h`;
+    return `${Math.floor(ms / 60_000)}m`;
+}
+// --- entry ----------------------------------------------------------------------------------
+// Only run when executed directly (also through npm's bin symlinks/shims), never on import.
+function isEntry() {
+    const script = process.argv[1];
+    if (!script)
+        return false;
+    try {
+        return realpathSync(script) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntry()) {
+    const io = { out: (s) => process.stdout.write(`${s}\n`), err: (s) => process.stderr.write(`${s}\n`) };
+    const terminal = process.stdin.isTTY && process.stdout.isTTY ? { input: process.stdin, output: process.stdout } : undefined;
+    void main(process.argv.slice(2), io, terminal ? { terminal } : {}).then((code) => {
+        process.exitCode = code;
+    });
+}