@hecer/yoke 1.1.0 → 1.2.0

package/dist/loop/run-command.js

@@ -13,6 +13,7 @@ import { resolveCommitIdentity } from './identity.js';
 import { runAudit } from '../audit/command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
 import { clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
+import { makeAdaptiveRunner } from '../routing/router.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -142,6 +143,11 @@ export function runLoopCommand(targetDir, opts) {
     }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
     const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
+    const routingEnabled = opts.routing ?? config.routing?.enabled ?? false;
+    if (routingEnabled && (!config.routing || config.routing.workers.length === 0)) {
+        console.error('Adaptive routing was requested, but no worker profiles are configured. Run yoke setup . --routing or add routing.workers to .yoke/config.yaml.');
+        return 2;
+    }
     let runner = opts.runner;
     if (!runner) {
         if (!available(runnerAgent)) {
@@ -150,14 +156,34 @@ export function runLoopCommand(targetDir, opts) {
         }
         // Token reporting is part of the machine interface: in --json mode a claude
         // runner switches to stream-json so cumulative usage rides on every status.
-        runner = makeRunner(runnerAgent, idleMs, {
+        const runnerOpts = {
             tokenReport: opts.json === true,
             onAmbiguity: opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto',
             perfCommand: config.perf?.command,
             permissions,
-        });
+            selection: {
+                model: config.runner?.model,
+                reasoningEffort: config.runner?.reasoningEffort,
+                bare: config.runner?.bare,
+                ...((routingEnabled || opts.routing === false) ? { nativeMultiAgent: false } : {}),
+            },
+        };
+        runner = routingEnabled && config.routing
+            ? makeAdaptiveRunner({
+                parent: runnerAgent,
+                parentSelection: runnerOpts.selection,
+                orchestratorSelection: config.routing.orchestrator ?? runnerOpts.selection,
+                workers: config.routing.workers,
+                strategy: config.routing.strategy,
+                maxCandidates: config.routing.maxCandidates,
+                idleTimeoutMs: idleMs,
+                permissions,
+                runnerOpts,
+                isAvailable: available,
+            })
+            : makeRunner(runnerAgent, idleMs, runnerOpts);
         const announce = opts.json ? console.error : console.log;
-        announce(`Runner: ${runnerAgent} · permissions: ${permissions} · cwd: ${targetDir}`);
+        announce(`Runner: ${runnerAgent} · permissions: ${permissions} · routing: ${routingEnabled ? 'on' : 'off'} · cwd: ${targetDir}`);
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
@@ -196,6 +222,7 @@ export function runLoopCommand(targetDir, opts) {
     }
     try {
         const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
+        const maxIterations = opts.maxIterations ?? Number.POSITIVE_INFINITY;
         const result = runLoop({
             prdPath: path,
             targetDir,
@@ -205,7 +232,7 @@ export function runLoopCommand(targetDir, opts) {
             verify,
             perf,
             audit,
-            maxIterations: opts.maxIterations,
+            maxIterations,
             isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
             reporter,
@@ -218,7 +245,7 @@ export function runLoopCommand(targetDir, opts) {
                     storyId: pendingDecision.storyId,
                     requestId: decisionRequestId(pendingDecision),
                     answered: false,
-                    maxIterations: opts.maxIterations,
+                    ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
                     agent: runnerAgent,
                     isolate: opts.isolate ?? false,
                     reviewer: opts.reviewer,
@@ -237,6 +264,7 @@ export function runLoopCommand(targetDir, opts) {
                             : config.loop.decisionPolicy),
                     permissions,
                     parallel: opts.parallel ?? 1,
+                    routing: routingEnabled,
                 });
             }
             else
@@ -252,8 +280,8 @@ export function runLoopCommand(targetDir, opts) {
         say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
         if (result.reason)
             say(`Reason: ${result.reason}`);
-        if (result.reason && /api key|please run \/login|not logged in/i.test(result.reason)) {
-            say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY or log the agent in for headless use.');
+        if (result.reason && /api key|please run \/login|not logged in|auth/i.test(result.reason)) {
+            say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY, or log the agent in for headless use.');
         }
         // Exit codes: 0 complete · 1 blocked/cap-reached · 2 config error (handled above) · 3 paused (loop.pause consumed at a story boundary)
         if (result.status === 'complete')

package/dist/loop/runner.js

@@ -40,7 +40,9 @@ export function buildReviewPrompt(story, context, verdictPath) {
     ];
     if (context)
         lines.push('', context);
-    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve ONLY if every acceptance criterion is met and the change is sound.', 'If you find ANY blocking issue (an unmet criterion, a bug, a missing test), reject.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve ONLY if every acceptance criterion is met and the change is sound.', 'If you find ANY blocking issue (an unmet criterion, a bug, a missing test), reject.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', verdictPath
+        ? 'Do not modify project source, tests, configuration, or generated artifacts. The verdict file named below is the only permitted write. Do not commit.'
+        : 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
     if (verdictPath)
         lines.push('', formatReviewContract(verdictPath));
     return lines.join('\n');
@@ -53,7 +55,9 @@ export function buildStandaloneReviewPrompt(scope, focus, verdictPath) {
     ];
     if (focus)
         lines.push(`Pay particular attention to: ${focus}.`);
-    lines.push('', 'Approve by exiting 0 ONLY if the change is sound and complete.', 'If you find ANY blocking issue, exit non-zero to reject and explain what is wrong.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
+    lines.push('', 'Approve by exiting 0 ONLY if the change is sound and complete.', 'If you find ANY blocking issue, exit non-zero to reject and explain what is wrong.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', verdictPath
+        ? 'Do not modify project source, tests, configuration, or generated artifacts. The verdict file named below is the only permitted write. Do not commit.'
+        : 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
     if (verdictPath)
         lines.push('', formatReviewContract(verdictPath));
     return lines.join('\n');
@@ -64,8 +68,8 @@ export function buildStandaloneReviewPrompt(scope, focus, verdictPath) {
 // and falsely marks the story done. Granting autonomous permissions makes the
 // implementer actually able to write files and run the verify command.
 // (The loop is opt-in and scoped to the target project dir.)
-export function agentInvocation(agent, prompt, cwd, permissions = 'safe') {
-    return buildProviderInvocation(agent, prompt, cwd, permissions);
+export function agentInvocation(agent, prompt, cwd, permissions = 'safe', selection = {}) {
+    return buildProviderInvocation(agent, prompt, cwd, permissions, selection);
 }
 export function claudeInvocation(prompt, cwd) {
     return agentInvocation('claude', prompt, cwd);
@@ -82,8 +86,8 @@ export function claudeStreamJsonInvocation(prompt, cwd) {
 // the user saw dead air the whole time. stream-json emits per-message output,
 // which doubles as liveness. Token usage rides along for free. Other agents
 // keep their plain invocation (no machine-readable stream to gain).
-export function runnerInvocation(agent, prompt, cwd, _tokenReport = false, permissions = 'safe') {
-    return buildProviderInvocation(agent, prompt, cwd, permissions);
+export function runnerInvocation(agent, prompt, cwd, _tokenReport = false, permissions = 'safe', selection = {}) {
+    return buildProviderInvocation(agent, prompt, cwd, permissions, selection);
 }
 // Parse claude stream-json output into cumulative token usage. Defensive by design:
 // non-JSON lines and unknown message shapes are ignored. The final "result" message
@@ -200,6 +204,51 @@ function runCliCapture(inv) {
         ? execSync(win32CommandString(inv.command, inv.args), opts)
         : execFileSync(inv.command, inv.args, opts);
 }
+// Reviews have a machine-readable result file, so their console stream is not
+// the result channel. Buffer stderr to preserve the provider's actual failure
+// (authentication, sandbox startup, quota, etc.) in loop-status.json instead of
+// reducing every failure to Node's generic "Command failed" message. The inner
+// watchdog still observes child output live and enforces the idle timeout.
+function runReviewCli(inv) {
+    const opts = {
+        cwd: inv.cwd,
+        input: inv.input,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    };
+    if (process.platform === 'win32')
+        execSync(win32CommandString(inv.command, inv.args), opts);
+    else
+        execFileSync(inv.command, inv.args, opts);
+}
+function processFailureSummary(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const value = error?.stderr;
+    const stderr = Buffer.isBuffer(value) ? value.toString('utf8') : typeof value === 'string' ? value : '';
+    const clean = stderr.replace(/\x1B\[[0-?]*[ -/]*[@-~]/gu, '').trim();
+    if (!clean)
+        return message;
+    const tail = clean.length > 4_000 ? `…${clean.slice(-4_000)}` : clean;
+    return `${message}; stderr: ${tail}`;
+}
+/** Run a provider invocation with stdout captured for structured control-plane calls. */
+export function runCapturedAgent(agent, inv) {
+    try {
+        const output = runCliCapture(inv);
+        return { success: true, output, summary: 'exited 0', tokens: parseProviderTelemetry(agent, output.split(/\r?\n/)).tokens };
+    }
+    catch (error) {
+        const partial = error.stdout;
+        const output = partial == null ? '' : String(partial);
+        return {
+            success: false,
+            output,
+            summary: error.message,
+            tokens: output ? parseProviderTelemetry(agent, output.split(/\r?\n/)).tokens : undefined,
+        };
+    }
+}
 // Probe whether a CLI is on PATH via `<command> --version`. Same win32/other split
 // as runCli to stay DEP0190-free. Never throws. Timeout is generous because some
 // agent CLIs cold-start slowly (gemini needs ~6s on Windows; 5s misreported it
@@ -229,13 +278,23 @@ export function runAgent(inv) {
         return { success: false, summary: e.message };
     }
 }
+/** Run a reviewer while retaining bounded stderr diagnostics on failure. */
+export function runReviewAgent(inv) {
+    try {
+        runReviewCli(inv);
+        return { success: true, summary: 'exited 0' };
+    }
+    catch (error) {
+        return { success: false, summary: processFailureSummary(error) };
+    }
+}
 export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     // Claude always streams (see runnerInvocation) — capture the stream so tokens are
     // always reported; other agents keep inherit stdio. opts.tokenReport is now
     // redundant for claude and meaningless elsewhere; kept for caller compatibility.
     const captureTokens = true;
     return (ctx) => {
-        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity, opts.perfCommand), ctx.targetDir, captureTokens, opts.permissions ?? 'safe');
+        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity, opts.perfCommand), ctx.targetDir, captureTokens, opts.permissions ?? 'safe', opts.selection);
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
         if (captureTokens) {
             const capture = opts.execCapture ?? runCliCapture;
@@ -264,7 +323,7 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     };
 }
 export const claudeRunner = makeRunner('claude');
-export function makeReviewRunner(agent, idleTimeoutMs = 0, exec = runCli) {
+export function makeReviewRunner(agent, idleTimeoutMs = 0, exec = runReviewCli) {
     return (ctx) => {
         const verdictPath = reviewVerdictPath(ctx.targetDir);
         mkdirSync(join(ctx.targetDir, '.yoke'), { recursive: true });
@@ -276,7 +335,7 @@ export function makeReviewRunner(agent, idleTimeoutMs = 0, exec = runCli) {
             exec(inv);
         }
         catch (e) {
-            processFailure = e.message;
+            processFailure = processFailureSummary(e);
         }
         try {
             const verdict = readReviewVerdict(verdictPath);

package/dist/retrofit/config.js

@@ -6,6 +6,14 @@ const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
 const CodeGraphSchema = z.enum(['graphify', 'serena']);
 const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() });
 const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
+const RoutingWorkerSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    agent: AgentSchema,
+    model: z.string().min(1).optional(),
+    reasoningEffort: z.string().min(1).optional(),
+    costTier: z.enum(['low', 'medium', 'high']).default('medium'),
+    capabilities: z.array(z.string().min(1)).default([]),
+});
 export const YokeConfigSchema = z.object({
     canonVersion: z.string().min(1),
     agents: z.array(AgentSchema),
@@ -19,8 +27,21 @@ export const YokeConfigSchema = z.object({
     }),
     runner: z.object({
         agent: AgentSchema.optional(),
+        model: z.string().min(1).optional(),
+        reasoningEffort: z.string().min(1).optional(),
+        bare: z.boolean().optional(),
         permissions: z.enum(['safe', 'unsafe', 'read-only']).optional(),
     }).optional(),
+    routing: z.object({
+        enabled: z.boolean(),
+        strategy: z.enum(['balanced', 'cost', 'speed', 'quality']).default('balanced'),
+        maxCandidates: z.number().int().min(1).max(5).default(3),
+        orchestrator: z.object({
+            model: z.string().min(1).optional(),
+            reasoningEffort: z.string().min(1).optional(),
+        }).optional(),
+        workers: z.array(RoutingWorkerSchema).max(12).default([]),
+    }).optional(),
     commit: z.object({
         authorName: z.string().min(1).optional(),
         authorEmail: z.string().email().optional(),

package/dist/review/command.js

@@ -1,4 +1,4 @@
-import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
+import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runReviewAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
 import { existsSync, mkdirSync, rmSync, rmdirSync } from 'node:fs';
 import { join } from 'node:path';
@@ -46,7 +46,7 @@ export function runReview(targetDir, opts = {}) {
     const inv = agentInvocation(reviewer, prompt, targetDir, 'safe');
     const say = opts.json ? console.error : console.log;
     say(`Reviewing ${scope} with ${reviewer}...`);
-    const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
+    const run = opts.run ?? ((i) => runReviewAgent(buildWatchdogInvocation(i, idleMs)));
     const processResult = run(inv);
     let verdict;
     try {

package/dist/routing/registry.js

@@ -0,0 +1,92 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+const HISTORY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+export function registryDir() {
+    if (process.env.YOKE_REGISTRY_DIR)
+        return resolve(process.env.YOKE_REGISTRY_DIR);
+    const base = process.env.LOCALAPPDATA || process.env.XDG_STATE_HOME || join(homedir(), '.yoke');
+    return join(base, 'Yoke', 'routing-registry');
+}
+function eventsDir() {
+    return join(registryDir(), 'events');
+}
+export function projectHash(targetDir) {
+    return createHash('sha256').update(`${process.platform}\0${resolve(targetDir)}`).digest('hex').slice(0, 16);
+}
+export function storyHash(project, storyId) {
+    return createHash('sha256').update(`${project}\0${storyId}`).digest('hex').slice(0, 16);
+}
+/**
+ * Immutable one-file-per-event writes avoid a shared mutable JSON file. Concurrent
+ * Yoke processes never hold a registry lock and cannot overwrite each other.
+ */
+export function recordRoutingObservation(observation) {
+    try {
+        const dir = eventsDir();
+        mkdirSync(dir, { recursive: true });
+        const event = {
+            schemaVersion: 1,
+            eventId: randomUUID(),
+            recordedAt: new Date().toISOString(),
+            ...observation,
+        };
+        const stamp = event.recordedAt.replace(/[:.]/g, '-');
+        writeFileSync(join(dir, `${stamp}-${process.pid}-${event.eventId}.json`), JSON.stringify(event), { flag: 'wx' });
+        return event;
+    }
+    catch {
+        // Routing evidence is observability. A registry failure must never block a story.
+        return null;
+    }
+}
+export function readRoutingObservations(limit = 1000) {
+    const dir = eventsDir();
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter(file => file.endsWith('.json')).sort().slice(-limit);
+    const observations = [];
+    for (const file of files) {
+        try {
+            const value = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            if (value.schemaVersion === 1 && typeof value.selected === 'string')
+                observations.push(value);
+        }
+        catch { /* ignore partial/corrupt evidence without affecting routing */ }
+    }
+    return observations;
+}
+export function historyForWorkers(workers) {
+    const wanted = new Map(workers.map(worker => [worker.id, worker]));
+    const grouped = new Map();
+    const oldestUseful = Date.now() - HISTORY_MAX_AGE_MS;
+    for (const event of readRoutingObservations()) {
+        const worker = wanted.get(event.selected);
+        if (!worker)
+            continue;
+        // Capability evidence belongs to the provider/model that produced it. This
+        // prevents a reused worker id from inheriting scores from a retired model.
+        if (event.provider !== worker.agent
+            || event.requestedModel !== worker.model
+            || event.requestedReasoningEffort !== worker.reasoningEffort)
+            continue;
+        if (typeof event.verificationSuccess !== 'boolean')
+            continue;
+        if (Date.parse(event.recordedAt) < oldestUseful)
+            continue;
+        grouped.set(event.selected, [...(grouped.get(event.selected) ?? []), event]);
+    }
+    const result = new Map();
+    for (const [id, events] of grouped) {
+        const successes = events.filter(event => event.verificationSuccess).length;
+        result.set(id, {
+            runs: events.length,
+            successes,
+            successRate: events.length ? successes / events.length : 0,
+            averageDurationMs: Math.round(events.reduce((sum, event) => sum + event.workerDurationMs, 0) / events.length),
+            averageTokens: Math.round(events.reduce((sum, event) => sum + event.inputTokens + event.outputTokens, 0) / events.length),
+        });
+    }
+    return result;
+}

package/dist/routing/router.js

@@ -0,0 +1,195 @@
+import { buildWatchdogInvocation, makeRunner, runCapturedAgent, runnerInvocation, } from '../loop/runner.js';
+import { historyForWorkers, projectHash, recordRoutingObservation, storyHash } from './registry.js';
+const costRank = { low: 0, medium: 1, high: 2 };
+export function rankWorkers(workers, strategy, maxCandidates) {
+    const history = historyForWorkers(workers);
+    const ranked = [...workers].sort((a, b) => {
+        const ah = history.get(a.id);
+        const bh = history.get(b.id);
+        if (strategy === 'quality') {
+            const aq = ah?.successRate ?? 0.5;
+            const bq = bh?.successRate ?? 0.5;
+            return bq - aq || costRank[b.costTier] - costRank[a.costTier] || a.id.localeCompare(b.id);
+        }
+        if (strategy === 'speed') {
+            const ad = ah?.averageDurationMs ?? costRank[a.costTier] * 1_000_000;
+            const bd = bh?.averageDurationMs ?? costRank[b.costTier] * 1_000_000;
+            return ad - bd || costRank[a.costTier] - costRank[b.costTier] || a.id.localeCompare(b.id);
+        }
+        if (strategy === 'cost')
+            return costRank[a.costTier] - costRank[b.costTier] || a.id.localeCompare(b.id);
+        const as = (ah?.successRate ?? 0.75) * 10 - costRank[a.costTier];
+        const bs = (bh?.successRate ?? 0.75) * 10 - costRank[b.costTier];
+        return bs - as || a.id.localeCompare(b.id);
+    });
+    return ranked.slice(0, Math.max(1, maxCandidates));
+}
+export function buildRoutingPrompt(ctx, workers, strategy) {
+    const history = historyForWorkers(workers);
+    const candidates = workers.map(worker => {
+        const observed = history.get(worker.id);
+        const evidence = observed
+            ? `observed=${observed.successes}/${observed.runs} gate-verified avg=${observed.averageDurationMs}ms`
+            : 'observed=unproven';
+        return `- ${worker.id}: provider=${worker.agent}; cost=${worker.costTier}; capabilities=${worker.capabilities.join(',') || 'general'}; ${evidence}`;
+    });
+    return [
+        'You are Yoke\'s routing controller. Choose who should execute one bounded coding story.',
+        'Do not inspect files, use tools, implement code, or explain your reasoning at length.',
+        `Optimization strategy: ${strategy}. SELF is the strong parent and is appropriate when risk or ambiguity outweighs savings.`,
+        '',
+        `Story ${ctx.story.id}: ${ctx.story.title}`,
+        'Acceptance criteria:',
+        ...ctx.story.acceptance.map(item => `- ${item}`),
+        '',
+        'Allowed candidates:',
+        '- SELF: strong parent; highest confidence; highest expected cost',
+        ...candidates,
+        '',
+        'Return exactly one line and nothing else:',
+        'YOKE_ROUTE {"worker":"SELF-or-candidate-id","reason":"max 100 characters"}',
+    ].join('\n');
+}
+function allStrings(value, out) {
+    if (typeof value === 'string') {
+        out.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            allStrings(item, out);
+        return;
+    }
+    if (value && typeof value === 'object')
+        for (const item of Object.values(value))
+            allStrings(item, out);
+}
+export function parseRouteDecision(output, allowedWorkerIds) {
+    const strings = [output];
+    for (const line of output.split(/\r?\n/)) {
+        try {
+            allStrings(JSON.parse(line), strings);
+        }
+        catch { /* raw provider output is also searched */ }
+    }
+    const allowed = new Set(['SELF', ...allowedWorkerIds]);
+    for (const text of strings.reverse()) {
+        const match = text.match(/YOKE_ROUTE\s*(\{[^\r\n]*\})/);
+        if (!match)
+            continue;
+        try {
+            const value = JSON.parse(match[1]);
+            if (typeof value.worker !== 'string' || !allowed.has(value.worker))
+                continue;
+            return {
+                worker: value.worker,
+                reason: typeof value.reason === 'string' ? value.reason.slice(0, 100) : 'selected by orchestrator',
+            };
+        }
+        catch { /* try an earlier provider string */ }
+    }
+    return null;
+}
+function callUsage(role, provider, selection, tokens, durationMs, profile) {
+    return {
+        role,
+        provider,
+        ...(profile ? { profile } : {}),
+        ...(selection.model ? { requestedModel: selection.model } : {}),
+        ...(selection.reasoningEffort ? { requestedReasoningEffort: selection.reasoningEffort } : {}),
+        ...(tokens?.model ? { actualModel: tokens.model } : {}),
+        inputTokens: tokens?.inputTokens ?? 0,
+        ...(tokens?.cachedInputTokens !== undefined ? { cachedInputTokens: tokens.cachedInputTokens } : {}),
+        ...(tokens?.cacheWriteInputTokens !== undefined ? { cacheWriteInputTokens: tokens.cacheWriteInputTokens } : {}),
+        outputTokens: tokens?.outputTokens ?? 0,
+        ...(tokens?.reasoningOutputTokens !== undefined ? { reasoningOutputTokens: tokens.reasoningOutputTokens } : {}),
+        ...(tokens?.totalCostUsd !== undefined ? { totalCostUsd: tokens.totalCostUsd } : {}),
+        durationMs,
+    };
+}
+export function makeAdaptiveRunner(options) {
+    const now = options.now ?? Date.now;
+    const available = options.isAvailable ?? (() => true);
+    const eligibleWorkers = options.workers.filter(worker => available(worker.agent));
+    const makeWorker = options.makeWorker ?? ((agent, selection) => makeRunner(agent, options.idleTimeoutMs ?? 0, {
+        ...options.runnerOpts,
+        permissions: options.permissions ?? 'safe',
+        selection,
+    }));
+    return (ctx) => {
+        // Re-rank per story so a long-running loop can use gate outcomes learned by
+        // earlier stories without rebuilding the runner.
+        const candidates = rankWorkers(eligibleWorkers, options.strategy, options.maxCandidates);
+        if (candidates.length === 0) {
+            return makeWorker(options.parent, options.parentSelection ?? {})(ctx);
+        }
+        const prompt = buildRoutingPrompt(ctx, candidates, options.strategy);
+        const orchestratorSelection = { ...(options.parentSelection ?? {}), ...(options.orchestratorSelection ?? {}), nativeMultiAgent: false };
+        const orchestratorStarted = now();
+        const routeRun = options.captureRoute
+            ? options.captureRoute(options.parent, ctx, prompt, orchestratorSelection)
+            : runCapturedAgent(options.parent, buildWatchdogInvocation(runnerInvocation(options.parent, prompt, ctx.targetDir, true, 'read-only', orchestratorSelection), options.idleTimeoutMs ?? 0));
+        const orchestratorDurationMs = Math.max(0, now() - orchestratorStarted);
+        const decision = routeRun.success ? parseRouteDecision(routeRun.output, candidates.map(worker => worker.id)) : null;
+        const selected = decision?.worker ?? 'SELF';
+        const worker = selected === 'SELF' ? undefined : candidates.find(candidate => candidate.id === selected);
+        const provider = worker?.agent ?? options.parent;
+        const selection = worker
+            ? { model: worker.model, reasoningEffort: worker.reasoningEffort, nativeMultiAgent: false, bare: options.parentSelection?.bare }
+            : { ...(options.parentSelection ?? {}), nativeMultiAgent: false };
+        const workerStarted = now();
+        const result = makeWorker(provider, selection)(ctx);
+        const workerDurationMs = Math.max(0, now() - workerStarted);
+        const calls = [
+            callUsage('orchestrator', options.parent, orchestratorSelection, routeRun.tokens, orchestratorDurationMs),
+            callUsage(worker ? 'worker' : 'parent', provider, selection, result.tokens, workerDurationMs, selected),
+        ];
+        const tokens = {
+            inputTokens: (routeRun.tokens?.inputTokens ?? 0) + (result.tokens?.inputTokens ?? 0),
+            ...((routeRun.tokens?.cachedInputTokens !== undefined || result.tokens?.cachedInputTokens !== undefined)
+                ? { cachedInputTokens: (routeRun.tokens?.cachedInputTokens ?? 0) + (result.tokens?.cachedInputTokens ?? 0) }
+                : {}),
+            ...((routeRun.tokens?.cacheWriteInputTokens !== undefined || result.tokens?.cacheWriteInputTokens !== undefined)
+                ? { cacheWriteInputTokens: (routeRun.tokens?.cacheWriteInputTokens ?? 0) + (result.tokens?.cacheWriteInputTokens ?? 0) }
+                : {}),
+            outputTokens: (routeRun.tokens?.outputTokens ?? 0) + (result.tokens?.outputTokens ?? 0),
+            ...((routeRun.tokens?.reasoningOutputTokens !== undefined || result.tokens?.reasoningOutputTokens !== undefined)
+                ? { reasoningOutputTokens: (routeRun.tokens?.reasoningOutputTokens ?? 0) + (result.tokens?.reasoningOutputTokens ?? 0) }
+                : {}),
+            ...((routeRun.tokens?.totalCostUsd !== undefined || result.tokens?.totalCostUsd !== undefined)
+                ? { totalCostUsd: (routeRun.tokens?.totalCostUsd ?? 0) + (result.tokens?.totalCostUsd ?? 0) }
+                : {}),
+            ...(result.tokens?.model ? { model: result.tokens.model } : routeRun.tokens?.model ? { model: routeRun.tokens.model } : {}),
+            calls,
+        };
+        let recorded = false;
+        const recordOutcome = (verificationSuccess) => {
+            if (recorded)
+                return;
+            recorded = true;
+            const project = projectHash(ctx.targetDir);
+            recordRoutingObservation({
+                projectHash: project,
+                storyHash: storyHash(project, ctx.story.id),
+                strategy: options.strategy,
+                selected,
+                provider,
+                ...(selection.model ? { requestedModel: selection.model } : {}),
+                ...(selection.reasoningEffort ? { requestedReasoningEffort: selection.reasoningEffort } : {}),
+                ...(result.tokens?.model ? { actualModel: result.tokens.model } : {}),
+                orchestratorProvider: options.parent,
+                ...(orchestratorSelection.model ? { orchestratorModel: orchestratorSelection.model } : {}),
+                orchestratorDurationMs,
+                workerDurationMs,
+                processSuccess: result.success,
+                verificationSuccess,
+                inputTokens: tokens.inputTokens,
+                outputTokens: tokens.outputTokens,
+            });
+        };
+        const routeSummary = decision
+            ? `route=${selected} (${decision.reason})`
+            : `route=SELF (${routeRun.success ? 'invalid routing response' : 'orchestrator failed'})`;
+        return { ...result, summary: `${routeSummary}; ${result.summary}`, tokens, routing: { recordOutcome } };
+    };
+}

package/dist/setup/command.js

@@ -5,6 +5,17 @@ import { loadConfig, saveConfig } from '../retrofit/config.js';
 import { detectProject } from '../retrofit/detect.js';
 import { runRetrofit } from '../retrofit/command.js';
 const ALL_AGENTS = ['claude', 'codex', 'gemini'];
+export function defaultRoutingWorkers(agents) {
+    const workers = {
+        claude: { id: 'claude-fast', agent: 'claude', model: 'haiku', costTier: 'low', capabilities: ['exploration', 'mechanical-edits', 'tests'] },
+        // Inherit the account's current Codex model and lower only its supported effort.
+        // This avoids pinning a model id that will age out of the provider catalog.
+        codex: { id: 'codex-light', agent: 'codex', reasoningEffort: 'low', costTier: 'medium', capabilities: ['exploration', 'mechanical-edits', 'tests'] },
+        // Gemini CLI's default/Auto route tracks the models available to the active account.
+        gemini: { id: 'gemini-auto', agent: 'gemini', costTier: 'low', capabilities: ['large-context', 'exploration', 'implementation'] },
+    };
+    return agents.map(agent => workers[agent]).filter((worker) => worker !== undefined);
+}
 function parseAgents(value, fallback) {
     if (value.trim().toLowerCase() === 'all')
         return [...ALL_AGENTS];
@@ -35,6 +46,7 @@ export async function runSetup(targetDir, opts = {}) {
     const defaultLoop = opts.loop ?? existing?.loop.enabled ?? true;
     const defaultRunner = opts.runner ?? existing?.runner?.agent ?? (host && defaultAgents.includes(host) ? host : defaultAgents[0] ?? host ?? 'claude');
     const defaultPolicy = opts.decisionPolicy ?? existing?.loop.decisionPolicy ?? (existing?.loop.onAmbiguity === 'abort' ? 'critical' : 'auto');
+    const defaultRouting = opts.routing ?? existing?.routing?.enabled ?? false;
     const interactive = opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
     let close;
     let ask = opts.ask;
@@ -49,6 +61,7 @@ export async function runSetup(targetDir, opts = {}) {
         let loop = defaultLoop;
         let runner = defaultRunner;
         let decisionPolicy = defaultPolicy;
+        let routing = defaultRouting;
         if (interactive && ask) {
             agents = parseAgents(await ask(`Agents [${defaultAgents.join(',')}] (claude,codex,gemini|all): `), defaultAgents);
             const graphAnswer = (await ask(`Code graph [${defaultGraph}] (graphify|serena): `)).trim().toLowerCase();
@@ -61,6 +74,7 @@ export async function runSetup(targetDir, opts = {}) {
             const policyAnswer = (await ask(`Decision mode [${decisionPolicy}] (auto|critical): `)).trim().toLowerCase();
             if (policyAnswer === 'auto' || policyAnswer === 'critical')
                 decisionPolicy = policyAnswer;
+            routing = yes(await ask(`Enable adaptive multi-model routing? [${defaultRouting ? 'yes' : 'no'}]: `), defaultRouting);
         }
         if (!agents.includes(runner))
             agents = [...agents, runner];
@@ -72,8 +86,16 @@ export async function runSetup(targetDir, opts = {}) {
             return 1;
         config.loop = { ...config.loop, enabled: loop, decisionPolicy };
         config.runner = { ...config.runner, agent: runner };
+        const existingWorkers = config.routing?.workers ?? [];
+        config.routing = {
+            enabled: routing,
+            strategy: config.routing?.strategy ?? 'balanced',
+            maxCandidates: config.routing?.maxCandidates ?? 3,
+            ...(config.routing?.orchestrator ? { orchestrator: config.routing.orchestrator } : {}),
+            workers: existingWorkers.length > 0 ? existingWorkers : defaultRoutingWorkers(agents),
+        };
         saveConfig(targetDir, config);
-        console.log(`Yoke setup complete: agents=${agents.join(',')} · runner=${runner} · loop=${loop ? 'on' : 'off'} · decisions=${decisionPolicy}`);
+        console.log(`Yoke setup complete: agents=${agents.join(',')} · runner=${runner} · loop=${loop ? 'on' : 'off'} · routing=${routing ? 'on' : 'off'} · decisions=${decisionPolicy}`);
         return 0;
     }
     finally {

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cross-agent coding harness: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
   "contextFileName": "GEMINI-EXTENSION.md"
 }