done-done-axi 0.6.13 → 0.6.15

package/README.md

@@ -68,11 +68,13 @@ Every answer is an exit code: **0** pass, **1** fail, **2** usage or config erro
 
 Four more moments from a demo notes app: a capture for the current commit, a judged pass, a check that refuses an older commit and two bad files, and a config error that stops the run. Real output from the current build; these four use a stub judge that says the screen shows the outcome, so no model runs.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/run-dark.svg"><img src="docs/media/run-light.svg" alt="done-done run sync records one screenshot for the current commit." width="400" align="top"></picture>
-<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/pass-dark.svg"><img src="docs/media/pass-light.svg" alt="A Checks block cites the new screenshot, the judge passes it, and done-done check passes." width="400" align="top"></picture>
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/run-dark.svg"><img src="docs/media/run-light.svg" alt="done-done run sync records one screenshot for the current commit." width="505"></picture></p>
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/reasons-dark.svg"><img src="docs/media/reasons-light.svg" alt="done-done check fails: one screenshot is from an older commit, one file is empty, one is a blank frame." width="400" align="top"></picture>
-<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/config-dark.svg"><img src="docs/media/config-light.svg" alt="done-done run stops with exit 2 because the config has an unknown key." width="400" align="top"></picture>
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/pass-dark.svg"><img src="docs/media/pass-light.svg" alt="A Checks block cites the new screenshot, the judge passes it, and done-done check passes." width="505"></picture></p>
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/reasons-dark.svg"><img src="docs/media/reasons-light.svg" alt="done-done check fails: one screenshot is from an older commit, one file is empty, one is a blank frame." width="505"></picture></p>
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/config-dark.svg"><img src="docs/media/config-light.svg" alt="done-done run stops with exit 2 because the config has an unknown key." width="505"></picture></p>
 
 The hero above is a real run of the published CLI on a fresh sample repo, replayed line by line: `run` recorded the capture at commit `ca78363`, the Pi judge on `commandcode/deepseek/deepseek-v4.1-flash` read it and passed it with that reason, `receipt` wrote the receipt, and `init` refused a journey whose only command was `npm test`. [The manual walkthrough](docs/manual-cli.md) does the same by hand.
 
@@ -92,8 +94,10 @@ A journey is the saved script that drives your app and captures what a user sees
 
 ```sh
 done-done journey add "greet Umer and check that Hello Umer is printed"
-done-done journey enhance greet-umer-prints-hello "add checks for an empty name and an unknown command"
-done-done journey improve greet-umer-prints-hello "also check that greeting Zoë prints exactly Hello Zoë"
+done-done journey enhance greet-umer-prints-hello \
+  "add checks for an empty name and an unknown command"
+done-done journey improve greet-umer-prints-hello \
+  "also check that greeting Zoë prints exactly Hello Zoë"
 ```
 
 `add` writes the script, its config entry and its feature in the verify skill; `enhance` deepens one journey; `improve` makes one change to one journey. Each exercise runs once on uncommitted files, which is a trial, not proof: read the script, commit it, then `done-done run <name>`. The saved script needs no agent or model, so CI can replay it; generation runs only on your machine ([worked transcript](docs/manual-cli.md)).
@@ -105,12 +109,14 @@ done-done works the same with or without Firstmate: the skill and CLI behave ide
 ```sh
 npx skills add umeranjum17/done-done-axi --skill done-done -g -a <agent> -y
 npm install -g done-done-axi
-cat "$(npm root -g)/done-done-axi/integrations/firstmate/brief-include.md" >> "$FM_HOME/config/brief-include.md"
-cp "$(npm root -g)/done-done-axi/integrations/firstmate/merge-gate" "$FM_HOME/config/merge-gate"
+DD="$(npm root -g)/done-done-axi/integrations/firstmate"
+cat "$DD/brief-include.md" >> "$FM_HOME/config/brief-include.md"
+cp "$DD/merge-gate" "$FM_HOME/config/merge-gate"
 ```
 
 - **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run the journeys `done-done affected` lists for its committed change, write a `## Checks` block, pass `check`, record a `receipt`, and see `affected` exit 0.
 - **`merge-gate`** (optional): refuses a PR whose head is not the one asked for, then runs `done-done check --from <PR URL>` and `done-done receipt --verify <head>` against your default branch's rules. Upstream Firstmate does not call a merge gate yet, so run it by hand until it does ([details](docs/reference.md#merge-gate-on-the-desktop)).
+- **Model pool**: point `judge.pool_command` and `judge.pool_config` at the fleet's `account-pool/bin/fm-model-pool` and done-done picks the Claude account, moves on a rate or usage limit, and falls over to DeepSeek Goat or Cursor auto ([details](docs/reference.md#config)).
 
 Another fleet works the same way: add the include text to whatever your workers read first, and run `merge-gate` before each merge, with `FM_HOME` set to the folder that holds `data/<task-id>/checks.md` for local-only tasks. Evidence and receipts stay in `~/.done-done/evidence/<app>` after teardown.
 

package/dist/agents.js

@@ -342,9 +342,11 @@ export const agentChoices = () => [...AGENTS, 'acp:<target>'];
 const askError = (kind, choices, rule, save) => new UsageError(`no ${kind} is set: ask the user which ${kind} to use (${choices}); ${rule}`, `Save the user's answer: ${save}`);
 export const noAgent = () => askError('agent', agentChoices().join(', '), 'never pick one for them', `done-done init --agent <agent> --model <model>, e.g. done-done init --agent opencode --model ${CHEAP.opencode.model}`);
 export const modelFor = (cfg, agent) => cfg.agent_config[agent]?.model || CHEAP[agent]?.model || '';
+// The configured model pool (judge.pool_command and its helper config), or undefined: standalone users keep today's behaviour.
+export const modelPool = (cfg) => cfg.judge.pool_command ? { command: cfg.judge.pool_command, config: cfg.judge.pool_config, binFor: (agent) => agentPath(agent, cfg) } : undefined;
 export const agentRun = (cfg, agent, model = modelFor(cfg, agent)) => ({
     agent, model, effort: cfg.agent_config[agent]?.effort ?? '', args: cfg.agent_args_override[agent] ?? [], path: agentPath(agent, cfg), override: cfg.agent_path_override[agent] ?? '', timeoutMs: parseDuration(cfg.agent_timeout),
-    ...(agent === 'claude' && cfg.judge.account_command ? { accountCommand: cfg.judge.account_command } : {}),
+    ...(agent === 'claude' && (modelPool(cfg) ? { pool: modelPool(cfg) } : cfg.judge.account_command ? { accountCommand: cfg.judge.account_command } : {})),
 });
 export const notStartable = (agent, override = '') => (override ? `agent_path_override.${agent} ${override} is not an executable file` : `${agent} is not on PATH`);
 // The known agent an agent names, for the judge-independence check: acp:claude-code is claude; a target that
@@ -415,9 +417,24 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
         let error;
         let drain;
         let idle;
+        // pi streams JSON events, and it echoes the whole transcript (prompt and answer included), so on stdout only an event that
+        // reports an error is a limit: never the words it was sent or wrote.
+        const piQuiet = (l) => {
+            if (!l.trimStart().startsWith('{'))
+                return false;
+            try {
+                const parsed = JSON.parse(l);
+                return parsed?.type !== 'error' && parsed?.message?.stopReason !== 'error';
+            }
+            catch {
+                return false;
+            }
+        };
         // A rate-limit line ends the call with that line, whatever the agent does next. On stdout the line must also say when it resets or retries,
         // so an answer that only quotes a 429 from the app's code does not stop the call. A claude call with images streams JSON lines,
-        // and only a rejected rate_limit_event on stdout stops it, so its complete lines are parsed one at a time.
+        // and only a rejected rate_limit_event on stdout stops it, so its complete lines are parsed one at a time. pi streams its whole
+        // transcript at the end (agent_end carries the prompt and the answer), so only its own error event is a limit there: a judge
+        // asked about rate limits must not be stopped by the words it was sent.
         let pendingStdout = '';
         const limited = (chunk, stdoutLine) => {
             let line;
@@ -430,7 +447,8 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
                 line = text.slice(0, end).split('\n').find(isRejectedRateLimit);
             }
             else {
-                line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l)));
+                line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l))
+                    && (!stdoutLine || c.agent !== 'pi' || !piQuiet(l)));
                 if (line)
                     line = limitText(line);
             }
@@ -510,6 +528,97 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
         child.stdin.end(input);
     });
 }
+// A fall-over route as this machine runs it: the helper names a route id, done-done runs the agent and model it has here.
+const POOL_ROUTES = {
+    'route:openai-codex/gpt-6.1-sol': { agent: 'codex', model: 'gpt-6.1-sol' },
+    'route:deepseek/deepseek-goat': { agent: 'pi', model: 'commandcode/deepseek/deepseek-v4.1-flash' },
+    'route:cursor/auto': { agent: 'pi', model: 'cursor/auto' },
+};
+// A typed limit moves the call to the next account or route; usage credits and overage stop it with their own cause.
+const USAGE_CREDITS = /usage[ _-]?credits?|overage|credit balance|\bcredits?\b|insufficient (?:credits?|funds)|\b402\b/i;
+const TYPED_LIMIT = /rate[ -]?limit|usage limit|too many requests|quota exceeded|\b429\b/i;
+const poolKey = (p) => `${p.command}\0${p.config}`;
+let poolFirst; // one first answer per process, as the account command is
+let poolInUse; // the account or route this process is on now
+// One helper call: the request JSON on stdin, one answer JSON. Nothing but the configured command passes through a shell.
+function poolAsk(pool, verb, req) {
+    const fail = (why, unavailable = false) => {
+        throw new (unavailable ? ClaudeUnavailable : UsageError)(`judge.pool_command: ${why}`, 'Fix judge.pool_command and judge.pool_config in the global config, or remove them for plain Claude sign-in');
+    };
+    const r = spawnSync(`${pool.command} ${verb} --json`, { shell: true, encoding: 'utf8', input: JSON.stringify(req), timeout: 30_000, maxBuffer: 64 * 1024 });
+    if (r.error)
+        fail(r.error.code ?? 'command could not start');
+    const said = typeof r.stderr === 'string' ? errorLine(r.stderr) : '';
+    let a;
+    try {
+        a = JSON.parse(r.stdout);
+    }
+    catch {
+        fail(r.status === 0 ? 'invalid JSON' : `command exited ${r.status}: ${said || 'no answer'}`);
+    }
+    const reason = typeof a?.reason === 'string' ? errorLine(a.reason) : said || 'no answer';
+    const billing = String(a?.billing_classification ?? a?.billing ?? '');
+    // The helper refuses credits-enabled accounts and routes; a call that reached one anyway is refused the same way.
+    if (USAGE_CREDITS.test(billing) || USAGE_CREDITS.test(typeof a?.reason === 'string' ? a.reason : ''))
+        fail(`the pool answered ${typeof a?.id === 'string' ? a.id : 'a route'} on usage credits or overage, which done-done never spends${reason === 'no answer' ? '' : `: ${reason}`}`);
+    if (r.status !== 0 || a?.ok !== true)
+        fail(reason, a?.ok === false || a === null);
+    if (typeof a.id !== 'string' || !/^[A-Za-z0-9_:./-]{1,128}$/.test(a.id))
+        fail('invalid account or route id');
+    const set = a.set ?? {};
+    const unset = a.unset ?? [];
+    if (!set || typeof set !== 'object' || Array.isArray(set) || !Object.entries(set).every(([k, v]) => /^[A-Za-z_]\w*$/.test(k) && typeof v === 'string'))
+        fail('set must be a map of environment variable names to strings');
+    if (!Array.isArray(unset) || !unset.every((n) => typeof n === 'string' && /^[A-Za-z_]\w*$/.test(n)))
+        fail('unset must be a list of environment variable names');
+    if (unset.includes('CLAUDE_CONFIG_DIR'))
+        fail('cannot unset CLAUDE_CONFIG_DIR');
+    const route = typeof a.provider === 'string' && a.provider !== 'claude';
+    // A known route id runs on the agent and model this tool has here; any other route runs its own harness when done-done knows it.
+    const mapped = route ? POOL_ROUTES[a.id] ?? (AGENTS.includes(a.harness) ? { agent: a.harness, model: String(a.model ?? '') } : undefined) : undefined;
+    if (route && !mapped)
+        fail(`route ${a.id} names no agent done-done can run`, true);
+    if (!route) {
+        const folder = set.CLAUDE_CONFIG_DIR;
+        let directory = false;
+        try {
+            directory = typeof folder === 'string' && isAbsolute(folder) && statSync(folder).isDirectory();
+        }
+        catch { }
+        if (!directory)
+            fail('set.CLAUDE_CONFIG_DIR must be an absolute existing folder');
+    }
+    return { id: a.id, set, unset, agent: mapped?.agent ?? 'claude', model: mapped?.model ?? '', route, raw: a };
+}
+// The account or fall-over route a pooled call starts on: the first answer is shared by every call in this process.
+function poolPickFor(pool, model, deadlineMs) {
+    if (poolInUse)
+        return Promise.resolve(poolInUse);
+    const key = poolKey(pool);
+    if (poolFirst?.key !== key)
+        poolFirst = { key, pick: Promise.resolve().then(() => poolAsk(pool, 'pick', { v: 1, purpose: 'work', pool_config: pool.config, model, capabilities: ['text'], deadline: Math.floor(deadlineMs / 1000) })).then((p) => (poolInUse = p)) };
+    return poolFirst.pick;
+}
+// The account id or fall-over route a Claude call answers on, named in the judge's result detail; '' when none is configured.
+export async function accountDetail(cfg, agent, model) {
+    const pool = agent === 'claude' ? modelPool(cfg) : undefined;
+    if (pool) {
+        const deadline = Date.now() + parseDuration(cfg.agent_timeout);
+        const attempted = [];
+        let pick = await poolPickFor(pool, model, deadline);
+        // A route this machine cannot start (Codex is out until 30 Oct, for one) is not the one that would answer, so the
+        // pre-check asks for the next one exactly as the call does, and fails closed when none can start.
+        while (pick.route && !pool.binFor(pick.agent)) {
+            if (attempted.length === 5)
+                throw new ClaudeUnavailable(`judge.pool_command: no account or route the helper answered can start on this machine (${attempted.join(', ')})`, 'Install one of the route agents, or remove judge.pool_command and judge.pool_config');
+            attempted.push(pick.id);
+            pick = poolAsk(pool, 'next', { v: 1, purpose: 'work', pool_config: pool.config, model, capabilities: ['text'], deadline: Math.floor(deadline / 1000), selection: pick.raw, cause: 'unavailable', attempted: [...attempted] });
+        }
+        return pick.route ? `pool route ${pick.id}` : `Claude account ${pick.id}`;
+    }
+    const account = await claudeAccount(agent, cfg.judge.account_command);
+    return account ? `Claude account ${account.id}` : '';
+}
 // A valid picker refusal is availability, not a malformed account configuration.
 export class ClaudeUnavailable extends UsageError {
 }
@@ -552,8 +661,44 @@ export function claudeAccount(agent, command) {
     });
 }
 export async function askAgent(c) {
-    const adapter = adapterFor(c.agent);
-    const argv = (d) => (adapter ? [...adapter.argv(c, d), ...(c.effort ? EFFORT_FLAGS[c.agent]?.(c.effort) ?? [] : []), ...(c.args ?? [])] : []);
+    // The model pool owns the call's agent, model and account environment: a typed limit moves it to the helper's next
+    // account or fall-over route, and the call's own timeout is the one deadline that whole chain shares.
+    const deadline = Date.now() + c.timeoutMs;
+    let call = c;
+    let picked;
+    const attempted = [];
+    const argv = (d) => {
+        const adapter = adapterFor(call.agent);
+        return adapter ? [...adapter.argv(call, d), ...(call.effort ? EFFORT_FLAGS[call.agent]?.(call.effort) ?? [] : []), ...(call.args ?? [])] : [];
+    };
+    // The helper's next account or route that can run here, inside the one deadline: a route whose agent this machine cannot
+    // start (Codex is out until 30 Oct, for one) joins `attempted` and the helper is asked for the next one.
+    const poolStep = (cause) => {
+        const pool = call.pool;
+        while (pool && picked && Date.now() + 5_000 < deadline) {
+            const prior = picked;
+            const next = poolAsk(pool, 'next', { v: 1, purpose: 'work', pool_config: pool.config, model: c.model, capabilities: ['text'], deadline: Math.floor(deadline / 1000), selection: prior.raw, cause, attempted: [...attempted] });
+            const bin = next.agent === c.agent ? c.path : pool.binFor(next.agent);
+            if (bin) {
+                picked = poolInUse = next;
+                call = { ...call, agent: next.agent, model: next.model || c.model, path: bin, effort: next.agent === c.agent ? c.effort : '' };
+                return true;
+            }
+            attempted.push(next.id);
+        }
+        return false;
+    };
+    // One move on a typed limit: the helper rests the limited account and answers the next account or fall-over route.
+    const moveOn = async (text) => {
+        if (!call.pool || !picked)
+            return false;
+        if (USAGE_CREDITS.test(text))
+            throw new UsageError(`done-done never spends usage credits or overage: ${picked.id} answered (${errorLine(text)})`, 'Use an account or route on your plan, then re-run; nothing is charged');
+        if (!TYPED_LIMIT.test(text))
+            return false;
+        attempted.push(picked.id);
+        return poolStep('rate_limit');
+    };
     const started = Date.now();
     let dir = '';
     let cwd = c.cwd;
@@ -564,43 +709,69 @@ export async function askAgent(c) {
     try {
         dir = mkdtempSync(join(tmpdir(), 'done-done-agent-'));
         cwd = c.tools === 'none' ? dir : c.cwd;
-        if (!adapter)
-            throw new Error(`no adapter for ${c.agent} yet`);
-        const bin = c.path;
-        if (!bin)
-            throw new Error(c.agent.startsWith('acp:') ? `${c.agent} needs acpx, and acpx is not startable; ${ACPX_INSTALL}` : notStartable(c.agent, c.override));
-        const account = await claudeAccount(c.agent, c.accountCommand);
-        const env = { ...process.env, ...c.env, ...adapter.env?.(c), ...(account && { CLAUDE_CONFIG_DIR: account.folder }) };
-        for (const name of account?.unset ?? [])
-            delete env[name];
-        if (adapter.readsImages)
-            for (const i of c.images ?? [])
-                writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
-        for (const [name, text] of Object.entries(adapter.files?.(c) ?? {}))
-            writeFileSync(join(dir, name), text, { mode: 0o600 });
+        if (call.pool) {
+            // The pool's first answer, or the next one when the route it names cannot start here.
+            const pool = call.pool;
+            picked = await poolPickFor(pool, call.model, deadline);
+            const bin = picked.agent === c.agent ? c.path : pool.binFor(picked.agent);
+            if (bin)
+                call = { ...call, agent: picked.agent, model: picked.model || call.model, path: bin, effort: picked.agent === c.agent ? c.effort : '' };
+            else {
+                attempted.push(picked.id);
+                if (!poolStep('unavailable'))
+                    throw new ClaudeUnavailable(`judge.pool_command: no account or route the helper answered can start on this machine (${[...attempted].join(', ')})`, 'Install one of the route agents, or remove judge.pool_command and judge.pool_config');
+            }
+        }
         let lastError = '';
         for (;;) {
+            const adapter = adapterFor(call.agent);
+            if (!adapter)
+                throw new Error(`no adapter for ${call.agent} yet`);
+            const bin = call.path;
+            if (!bin)
+                throw new Error(call.agent.startsWith('acp:') ? `${call.agent} needs acpx, and acpx is not startable; ${ACPX_INSTALL}` : notStartable(call.agent, call.override));
+            const account = call.accountCommand ? await claudeAccount(call.agent, call.accountCommand) : undefined;
+            const env = { ...process.env, ...call.env, ...adapter.env?.(call), ...(account && { CLAUDE_CONFIG_DIR: account.folder }) };
+            for (const name of account?.unset ?? [])
+                delete env[name];
+            if (picked) {
+                for (const [name, value] of Object.entries(picked.set))
+                    env[name] = value;
+                for (const name of picked.unset)
+                    delete env[name];
+            }
+            if (adapter.readsImages)
+                for (const i of call.images ?? [])
+                    writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
+            for (const [name, text] of Object.entries(adapter.files?.(call) ?? {}))
+                writeFileSync(join(dir, name), text, { mode: 0o600 });
             attempts++;
             // An ask-again names what was wrong with the last answer. The trailer ends on words, not the schema: a weak model
             // (seen with one opencode model) copied a schema that closed the prompt back as its answer.
-            const schemaTrailer = `\n\nAnswer with only one JSON object that matches this JSON schema:\n${JSON.stringify(c.schema)}\nThat object holds your own values, never the schema itself, and you send no other text.\n`;
-            const prompt = c.tools === 'edit' && adapter.editNote ? `${c.prompt}\n\n${adapter.editNote}` : c.prompt;
+            const schemaTrailer = `\n\nAnswer with only one JSON object that matches this JSON schema:\n${JSON.stringify(call.schema)}\nThat object holds your own values, never the schema itself, and you send no other text.\n`;
+            const prompt = call.tools === 'edit' && adapter.editNote ? `${call.prompt}\n\n${adapter.editNote}` : call.prompt;
             const promptText = (attempts === 1 ? prompt : `${prompt}\n\nYour previous answer was not valid (${lastError}).`) + schemaTrailer;
             if (adapter.file)
                 writeFileSync(join(dir, 'prompt.md'), promptText, { mode: 0o600 });
-            const input = adapter.file ? '' : adapter.stdin ? adapter.stdin(c, promptText) : promptText;
-            res = await start(bin, argv(dir), c, cwd, input, env, adapter.streams ? c.idleMs ?? AGENT_IDLE_MS : 0);
-            if (res.error)
+            const input = adapter.file ? '' : adapter.stdin ? adapter.stdin(call, promptText) : promptText;
+            const remain = Math.max(1_000, Math.min(call.timeoutMs, deadline - Date.now()));
+            res = await start(bin, argv(dir), { ...call, timeoutMs: remain }, cwd, input, env, adapter.streams ? call.idleMs ?? AGENT_IDLE_MS : 0);
+            if (res.error) {
+                if (await moveOn(res.error.message)) {
+                    attempts--;
+                    continue;
+                }
                 throw res.error;
+            }
             // A permission the run refused explains a call with no answer; name it rather than the exit code text.
             const refused = adapter.reject?.(String(res.stderr ?? '')) ?? '';
             if (res.status !== 0 && refused)
-                throw new ProviderError(refused, `${c.agent} exited ${res.status}: `);
+                throw new ProviderError(refused, `${call.agent} exited ${res.status}: `);
             if (res.status !== 0) {
                 // An agent that exits non-zero may still say why in its own output (claude: a usage limit, a bad model).
                 let text = String(res.stderr || res.stdout).trim().slice(-500);
                 try {
-                    adapter.answer(String(res.stdout), c);
+                    adapter.answer(String(res.stdout), call);
                 }
                 catch (e) {
                     if (e instanceof ProviderError)
@@ -608,16 +779,20 @@ export async function askAgent(c) {
                     else if (!(e instanceof SyntaxError))
                         text = e.message;
                 }
-                throw new ProviderError(text, `${c.agent} exited ${res.status}: `, adapter.hint && c.tools !== 'none' ? `; ${adapter.hint}` : '');
+                if (await moveOn(text)) {
+                    attempts--;
+                    continue;
+                }
+                throw new ProviderError(text, `${call.agent} exited ${res.status}: `, adapter.hint && call.tools !== 'none' ? `; ${adapter.hint}` : '');
             }
             try {
-                const answer = adapter.answer(String(res.stdout), c);
+                const answer = adapter.answer(String(res.stdout), call);
                 if (!answer || typeof answer !== 'object' || Array.isArray(answer))
                     throw new Error(`the answer is not a JSON object: ${JSON.stringify(answer)}`);
-                const missing = (c.schema.required ?? []).filter((k) => !(k in answer));
+                const missing = (call.schema.required ?? []).filter((k) => !(k in answer));
                 if (missing.length)
                     throw new Error(`the answer does not match the schema (missing ${missing.join(', ')}): ${JSON.stringify(answer).slice(0, 200)}`);
-                out = { ok: true, answer: answer };
+                out = { ok: true, answer: answer, ...(picked && (picked.route ? { route: picked.id } : { account: picked.id })) };
                 break;
             }
             catch (e) {
@@ -625,10 +800,10 @@ export async function askAgent(c) {
                     throw e;
                 // A refused permission is why there is no usable answer, not a bad answer: name it instead of "no JSON object".
                 if (refused)
-                    throw new ProviderError(refused, `${c.agent} did not finish: `);
+                    throw new ProviderError(refused, `${call.agent} did not finish: `);
                 // Only a tool-less call is asked again: an edit or read step may already have changed the repo or read it.
                 lastError = e.message;
-                if (c.tools !== 'none' || attempts >= (c.attempts ?? ASK_ATTEMPTS))
+                if (call.tools !== 'none' || attempts >= (call.attempts ?? ASK_ATTEMPTS))
                     throw new Error(`the agent did not answer with valid JSON after ${attempts} ${attempts === 1 ? 'try' : 'tries'}: ${lastError}`);
             }
         }
@@ -638,7 +813,7 @@ export async function askAgent(c) {
         // carries its own line, so it is left as it is.
         const said = stderrHead(String(res?.stderr ?? ''));
         const provider = e instanceof ProviderError;
-        const note = (text) => (!provider && said && !text.includes(said.split(' | ')[0]) ? `${text}; ${c.agent} stderr: ${said}` : text);
+        const note = (text) => (!provider && said && !text.includes(said.split(' | ')[0]) ? `${text}; ${call.agent} stderr: ${said}` : text);
         out = { ok: false, error: note(e.message), ...(!provider && said ? { stderr: said } : {}) };
         failure = note(e instanceof ProviderError ? e.detail : e.message);
     }
@@ -647,9 +822,9 @@ export async function askAgent(c) {
             rmSync(dir, { recursive: true, force: true });
     }
     // The record holds what ran and what came back, never the prompt text or an image.
-    const { prompt, images, ...call } = c;
+    const { prompt, images, pool, ...spec } = c;
     try {
-        const record = { ...call, ...(images && { images: images.map((i) => i.name) }), cwd, prompt_bytes: Buffer.byteLength(prompt), argv: argv('<tmp>'), ms: Date.now() - started, exit: res?.status ?? null, attempts, ...out, error: failure, stderr: String(res?.stderr ?? '').slice(-2000) };
+        const record = { ...spec, agent: call.agent, model: call.model, ...(picked && (picked.route ? { route: picked.id } : { account: picked.id })), ...(images && { images: images.map((i) => i.name) }), cwd, prompt_bytes: Buffer.byteLength(prompt), argv: argv('<tmp>'), ms: Date.now() - started, exit: res?.status ?? null, attempts, ...out, error: failure, stderr: String(res?.stderr ?? '').slice(-2000) };
         mkdirSync(dirname(c.record), { recursive: true });
         writeFileSync(c.record, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
         out = { ...out, record: c.record };

package/dist/cli.js

@@ -118,6 +118,7 @@ const CONFIG_TEXT = `config: ~/.done-done/config.yaml (global; DONE_DONE_HOME mo
   global only: agent_config.<agent>.{model,effort} (effort: minimal, low, medium, high, xhigh, max), agent_args_override.<agent>
   (extra flags), agent_path_override.<agent> (binary), acpx_path, agent_timeout (one agent call, default 30m; a streaming agent that prints nothing for 5m is stopped early),
   judge.account_command (optional Claude account pick; exported CLAUDE_CONFIG_DIR wins),
+  judge.pool_command with judge.pool_config (optional shared model pool: the Claude account, a move on a rate/usage limit, and a fall-over route),
   judge.fallback_route (optional second judge, same values as judge.route; Claude usage/rate/sign-in limits or an empty pool trigger it;
   e.g. answerer:pi with agent_config.pi.model: openai-codex/gpt-6.1-sol; unset keeps Claude failures as errors; no fallback chains),
   evidence.local_root, judge.{route,model,floor} (the judge and shared confidence floor, set by the user with

package/dist/config.js

@@ -89,6 +89,8 @@ const KEYS = {
     'judge.floor': { scope: 'global', type: 'number' },
     'judge.env_file': { scope: 'global', type: 'string' },
     'judge.account_command': { scope: 'global', type: 'string' },
+    'judge.pool_command': { scope: 'global', type: 'string' },
+    'judge.pool_config': { scope: 'global', type: 'string' },
     'judge.fallback_route': { scope: 'global', type: 'route' },
 };
 const SECTIONS = new Set(['evidence', 'secrets', 'checks', 'judge', 'signoff']);
@@ -369,7 +371,7 @@ function defaultConfig(repo) {
         secrets: { patterns: {}, allow: [] },
         checks: { fix_title: '^(fix|bugfix|hotfix)\\b', upstream_catch_up: false, moved_from: false, generated_paths: [] },
         signoff: { post: false, board: '' },
-        judge: { route: '', fallback_route: '', model: '', floor: 0.7, env_file: '', account_command: '' },
+        judge: { route: '', fallback_route: '', model: '', floor: 0.7, env_file: '', account_command: '', pool_command: '', pool_config: '' },
         trusted: false,
         from: {},
     };
@@ -382,6 +384,18 @@ export function loadConfig(repo, projectText) {
     apply(cfg, readOptional(globalFile), globalFile, 'global');
     const projectFile = join(repo, '.done-done.yaml');
     apply(cfg, projectText ?? readOptional(projectFile), projectFile, 'repo');
+    // The model pool needs both its helper command and the helper's own pool config; it replaces the Claude account command.
+    if (cfg.judge.pool_config) {
+        cfg.judge.pool_config = tilde(cfg.judge.pool_config);
+        if (!isAbsolute(cfg.judge.pool_config))
+            throw new UsageError(`${globalFile}: judge.pool_config must be the absolute path of the model pool helper's config/account-pool`, 'Set judge.pool_config in the global config, or remove it');
+    }
+    if (cfg.judge.pool_command) {
+        if (!cfg.judge.pool_config)
+            throw new UsageError(`${globalFile}: judge.pool_command needs judge.pool_config, the absolute path of the helper's config/account-pool`, 'Set judge.pool_config in the global config, or remove judge.pool_command');
+        if (cfg.judge.account_command)
+            throw new UsageError(`${globalFile}: judge.pool_command and judge.account_command are both set: the model pool already picks the Claude account`, 'Delete the judge.account_command line in the global config');
+    }
     // A skill dir an older init wrote (verify-<app>) is still read until init renames it to the prefixed name.
     cfg.skill ||= existsSync(join(repo, `.agents/skills/done-done-verify-${cfg.app}`)) || !existsSync(join(repo, `.agents/skills/verify-${cfg.app}`))
         ? `.agents/skills/done-done-verify-${cfg.app}` : `.agents/skills/verify-${cfg.app}`;
@@ -460,5 +474,9 @@ judge:
   # env_file: ~/.config/done-done/judge.env
   # Optional shell command printing one account-pick JSON for Claude judge and agent calls; an exported CLAUDE_CONFIG_DIR wins.
   # account_command: account-picker pick claude --json
+  # Optional shared model pool (firstmate-addons account-pool/bin/fm-model-pool): it picks the Claude account, moves on a
+  # rate/usage limit, and falls over to another route; pool_config is the helper's own config/account-pool file.
+  # pool_command: fm-model-pool
+  # pool_config: ~/firstmate/config/account-pool
 `;
 }

package/dist/judge.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { accessSync, constants, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, delimiter, isAbsolute, join } from 'node:path';
-import { agentRun, askAgent, claudeAccount, ClaudeUnavailable, notStartable } from './agents.js';
+import { accountDetail, agentRun, askAgent, ClaudeUnavailable, notStartable } from './agents.js';
 import { home, KEY_ROUTES, parseDuration, tilde, UsageError } from './config.js';
 import { downscaleToPng } from './media.js';
 const MAX_SIDE = 1280; // long edge sent to the model, in pixels
@@ -146,7 +146,7 @@ export async function backend(cfg, choice, record = () => '', questions = { rele
     const claude = choice.agent === 'claude';
     if (!bin)
         throw new UsageError(`judge: ${notStartable(choice.agent, override)}`, claude ? (override ? 'Fix agent_path_override.claude in ~/.done-done/config.yaml, or install Claude Code' : 'Install Claude Code, or set agent_path_override.claude to its absolute path') : `Install ${choice.agent}, or ask the user for another judge and save it: done-done init --judge <agent> --judge-model <model>`);
-    const account = await claudeAccount(choice.agent, cfg.judge.account_command);
+    const account = await accountDetail(cfg, choice.agent, choice.model);
     const { answerer, resolve } = await kit();
     let lastError = '';
     // The kit hides a failed call's message from the verdict, so the real cause is kept here for the result.
@@ -168,7 +168,7 @@ export async function backend(cfg, choice, record = () => '', questions = { rele
             return { text: JSON.stringify(a.answer) };
         },
     }).ask;
-    return { ask, resolve, lastError: () => lastError, detail: account ? `Claude account ${account.id}` : claude ? `claude binary at ${bin} and the judge kit are present; it judges with your own claude sign-in` : `${choice.agent} at ${bin} and the judge kit are present; it judges with every tool off` };
+    return { ask, resolve, lastError: () => lastError, detail: account || (claude ? `claude binary at ${bin} and the judge kit are present; it judges with your own claude sign-in` : `${choice.agent} at ${bin} and the judge kit are present; it judges with every tool off`) };
 }
 // The parts list as the model gave it: labels trimmed and in its own order, so a cover position still names its label.
 const labels = (x) => (Array.isArray(x) && x.every((s) => typeof s === 'string') ? x.map((s) => s.trim()) : undefined);
@@ -354,16 +354,21 @@ async function judgeBatch(cfg, choice, outcome, captures, records, dir) {
     return { judged, notJudged, choice, missing };
 }
 async function judgeOn(cfg, choose, outcome, captures, records) {
-    // Check the account even on a verdict cache hit: a broken configured picker must never produce a pass.
-    const account = await claudeAccount(choose().agent, cfg.judge.account_command);
-    const detail = account ? { detail: `Claude account ${account.id}` } : {};
+    // Check the account or pool route even on a verdict cache hit: a broken configured picker must never produce a pass.
+    const first = choose();
+    await accountDetail(cfg, first.agent, first.model);
+    // After the calls, the detail names the account id or fall-over route that actually answered.
+    const named = async (result) => {
+        const detail = await accountDetail(cfg, first.agent, first.model);
+        return detail ? { ...result, detail } : result;
+    };
     const dir = join(home(), 'runs', cfg.app, 'judge');
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const judged = [];
     const notJudged = [];
     const batchChoice = captures.filter(judgeable).length > 1 ? choose() : undefined;
     if (batchChoice && batchChoice.route !== 'openai:key')
-        return { ...await judgeBatch(cfg, batchChoice, outcome, captures, records, dir), ...detail };
+        return named(await judgeBatch(cfg, batchChoice, outcome, captures, records, dir));
     let choice;
     let be;
     let calls = 0;
@@ -423,5 +428,5 @@ async function judgeOn(cfg, choose, outcome, captures, records) {
         judged.push(verdict);
     }
     // Only openai:key can have several independent calls here; it returns no coverage fields.
-    return { judged, notJudged, choice, missing: missingParts(judged), ...detail };
+    return named({ judged, notJudged, choice, missing: missingParts(judged) });
 }

package/docs/reference.md

@@ -795,10 +795,14 @@ judge:                                # done-done's own judge; check, receipt, v
   floor: 0.7                          # every judge's pick must reach this probability to count; below it the verdict is unsure (inconclusive), never a pass
   # env_file: ~/.config/done-done/judge.env  # KEY=value lines (a provider API key) handed to the judge for names your shell has not exported; the key stays in that file
   # account_command: account-picker pick claude --json  # optional shell command for Claude judge and agent calls (verify/maintain too), once per process; exported CLAUDE_CONFIG_DIR wins
+  # pool_command: fm-model-pool       # optional shared model pool (Firstmate account-pool/bin/fm-model-pool): the Claude account, limit moves and fall-over
+  # pool_config: ~/firstmate/config/account-pool  # the helper's own config/account-pool, absolute; needs pool_command
 ```
 
 `judge.account_command` must print one JSON object: `{"ok":true,"id":"pool-1","set":{"CLAUDE_CONFIG_DIR":"/absolute/existing/folder"},"unset":["ANTHROPIC_API_KEY"]}`. Only the selected folder is set, and each `unset` name is deleted from the spawned environment; it cannot unset `CLAUDE_CONFIG_DIR`. The detail names only the account id. A pick returning `ok: false` (or JSON `null`) is an unavailable Claude route and uses `judge.fallback_route` when configured; otherwise it stops with the same cause and no verdict. An invalid pick still stops the call. Neither case falls back to the default Claude login. Unset, it preserves normal Claude sign-in behavior; other agents and API-key routes do not run it.
 
+**Shared model pool.** Global `judge.pool_command` opts a home into a pool helper that picks the Claude account, moves on a rate/usage limit and falls over to another model route; `judge.pool_config` is the helper's own `config/account-pool`, absolute. It speaks the pool's protocol v1: done-done runs `<pool_command> pick --json` with one request JSON on stdin (`v: 1`, `purpose: work`, `pool_config`, the call's `model` and one overall deadline) and later `<pool_command> next --json` with the prior answer, `cause: rate_limit` and every account or route already `attempted`. The answer is either a Claude account (`id`, `set`, `unset`, as `judge.account_command` above) or a fall-over route (`provider` other than `claude`, `harness`, `model`). One answer per process is shared by the Claude judge, readers and drives; each call's environment gets that account's folder and its `unset` names removed, and nothing else. On a typed rate or usage limit the helper's next account or route runs that same call, once per account, inside the call's single `agent_timeout` deadline. A route the helper answers runs on the agent and model done-done has here: `route:deepseek/deepseek-goat` is `pi` at `commandcode/deepseek/deepseek-v4.1-flash`, `route:cursor/auto` is `pi` at `cursor/auto`, and any other route runs its own harness when that is an agent done-done knows. A route whose agent is not installed here is skipped and the helper is asked for the next one. Usage credits and overage are never spent: an account or route that enables them stops the call with a plain error naming it, and nothing is charged. The result's detail names the account id or the route id that answered, never a folder or a token. A pick returning `ok: false` (or JSON `null`) is an unavailable Claude route and uses `judge.fallback_route` when configured; invalid JSON or a malformed answer stops the call. Unset, plain Claude sign-in is unchanged. `judge.account_command` and `judge.pool_command` cannot both be set.
+
 An `agent_config` entry merges with the defaults field by field, so `claude: { model: claude-sonnet-5-5 }` keeps `effort: low`; the other maps merge entry by entry. `done-done doctor` shows which file set each agent setting.
 
 **Project:** `<repo>/.done-done.yaml`.
@@ -856,6 +860,6 @@ npx -y --allow-git=all github:umeranjum17/done-done-axi --help
 
 `dist/` is committed, so installing from GitHub needs no build step. `npm test` rebuilds it and fails while the rebuilt `dist/` differs from the commit or has files git does not track, so `git add` the new `dist/` files with your change.
 
-The first-screen terminal images (`docs/media/hero-*.png`, and the animated `hero.gif`) are real output from the published CLI, captured in a sample repo. `node docs/media/hero.mjs` rebuilds their pages from the captured transcripts beside it (`hero-run.txt`, `hero-refuse.txt`) and fails when a shown value is not in them; screenshot `.hero/hero-desktop.html` (828x596) and `.hero/hero-phone.html` (418x792) at device scale factor 2, in light and dark. The GIF replays the same lines a step at a time on that page, ending on the judge's pass and the receipt. The four lower terminal illustrations (`hero`, `run`, `pass`, `reasons`, `config`) use a stub judge, so no model runs; redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
+The first-screen terminal images (`docs/media/hero-*.png`, and the animated `hero.gif`) are real output from the published CLI, captured in a sample repo. `node docs/media/hero.mjs` rebuilds their pages from the captured transcripts beside it (`hero-run.txt`, `hero-refuse.txt`) and fails when a shown value is not in them; screenshot `.hero/hero-desktop.html` (828x596) and `.hero/hero-phone.html` (418x792) at device scale factor 2, in light and dark. The GIF replays the same lines a step at a time on that page; its first frame is the finished screen, so a still capture or a social preview never shows an empty terminal, and it ends on the judge's pass and the receipt. The four lower terminal illustrations (`hero`, `run`, `pass`, `reasons`, `config`) use a stub judge, so no model runs; redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
 
 The demo notes app behind those pictures: start one with `node docs/media/demo.mjs <fresh-scratch-directory> 0` (the server prints its owned port), open a native run in its `app/` repo, drive the checklist in the browser, save `app.png` at 400×140 DPR 2 into the run's evidence folder, seal it and run `check` with your configured judge. Save the open result as `<scratch>/open.json` and the check result as `<scratch>/check.json`; `/proof` displays that screenshot and verdict and refuses to show a pass without a real passing result. Capture `/proof` at 400×230 DPR 2 with `chrome-devtools-axi`, keep the scratch outside the repo and stop the server afterwards.

package/docs/releasing.md

@@ -1,5 +1,5 @@
-# 0.6.13 patch release
+# 0.6.15 patch release
 
-This release carries the rewritten README to the npm page: a real judged run on the first screen, the hero images rendered from captured CLI transcripts, and reference detail moved into the docs.
+This release carries the audited README to the npm page: the hero GIF opens on the finished screen, the four lower terminal pictures sit one per row at one width, and the journey and Firstmate commands wrap so no line is clipped in the README column.
 
-Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.13 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.
+Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.15 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "license": "Apache-2.0",
   "description": "Prove your app really works: done-done drives your app the way a user does, a fresh judge checks every capture, and the proof is tied to a commit.",
   "type": "module",

package/skills/done-done/SKILL.md

@@ -98,6 +98,8 @@ fresh session of its own, looks at each capture. `check` and `receipt` start the
 and nothing turns it off: there is no result without it. When it says no judge is set, ask the user which
 judge (and model) to use and save their answer with the command it prints; never choose one for them. When
 the judge fails, report its error to the user; never call the work proven without a judge pass.
+An optional shared model pool (`judge.pool_command` and `judge.pool_config`) picks the Claude account, moves on a rate or usage
+limit, and falls over to DeepSeek Goat or Cursor auto; results name the account or route that answered, and usage credits are never spent.
 An explicitly configured `judge.fallback_route` can judge when Claude has no eligible account, sign-in or usage left;
 `answerer:pi` with `agent_config.pi.model: openai-codex/gpt-6.1-sol` uses the existing Codex login.
 Read `done-done --help` for fallback configuration; results name the route that actually answered.