@hecer/yoke 1.21.1 → 1.23.0

package/dist/retrofit/gitignore.js

@@ -1,8 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
 export const YOKE_IGNORE_LINES = [
+    '.yoke/supervision/',
     '.yoke/worktrees/',
     '.yoke/integration-recovery/',
+    '.yoke/failure-progress/',
     '.yoke/run-state.json',
     '.yoke/run-state.*.tmp',
     '.yoke/backup/',
@@ -31,6 +34,7 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/checks/',
     '.yoke/events/',
     '.yoke/history/', '.yoke/routing/',
+    '.yoke/routing-attempts/',
     '.yoke/goal.json',
     '.yoke/goal.json.*.tmp',
     '.yoke/goal.pause',
@@ -40,6 +44,14 @@ const HEADER = '# Yoke runtime artifacts (managed by yoke retrofit)';
 // lines not already present (matched verbatim, line-wise). Preserves existing
 // content. Returns true if the file changed.
 export function ensureGitignore(targetDir) {
+    if (existsSync(join(targetDir, '.yoke', 'supervision'))) {
+        try {
+            const tracked = execFileSync('git', ['ls-files', '--', '.yoke/supervision/'], { cwd: targetDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            if (tracked)
+                console.warn('Yoke supervision files are already tracked; ignore rules preserve their index entries. Review and explicitly untrack these runtime files before the next loop.');
+        }
+        catch { /* A retrofit may precede git initialization. */ }
+    }
     const file = join(targetDir, '.gitignore');
     const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
     const present = new Set(current.split(/\r?\n/).map((l) => l.trim()));

package/dist/retrofit/planners/codex.js

@@ -1,8 +1,23 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 import { skillPackageActions } from '../skill-actions.js';
+import { mergeJson } from '../merge-json.js';
+function codexHooks(targetDir) {
+    const path = join(targetDir, '.codex/hooks.json');
+    const current = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {};
+    // Remove only the exact Yoke adapter command; keep other hooks in its block.
+    if (Array.isArray(current.hooks?.PreToolUse)) {
+        current.hooks.PreToolUse = current.hooks.PreToolUse.flatMap((block) => {
+            if (!Array.isArray(block.hooks))
+                return [block];
+            const hooks = block.hooks.filter((hook) => hook.command !== 'node "$(git rev-parse --show-toplevel)/.codex/hooks/rtk.mjs"');
+            return hooks.length ? [{ ...block, hooks }] : [];
+        });
+    }
+    return JSON.stringify(mergeJson(current, { hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'rtk hook codex' }] }] } }), null, 2) + '\n';
+}
 function tomlMcp(codeGraph, codeIntelligence, targetDir) {
     const servers = mcpServers(codeGraph, codeIntelligence, targetDir);
     // Codex reads MCP servers from ~/.codex/config.toml. This project-level file is a
@@ -37,23 +52,8 @@ export function planCodex(canonDir, targetDir, codeGraph = 'graphify', codeIntel
     }, {
         kind: 'write',
         target: '.codex/hooks.json',
-        merge: true,
-        content: JSON.stringify({
-            description: 'Yoke command compression for Codex',
-            hooks: {
-                PreToolUse: [{
-                        matcher: '^Bash$',
-                        hooks: [{
-                                type: 'command',
-                                command: 'node "$(git rev-parse --show-toplevel)/.codex/hooks/rtk.mjs"',
-                                commandWindows: 'powershell -NoProfile -ExecutionPolicy Bypass -Command "$root = git rev-parse --show-toplevel; node (Join-Path $root \'.codex/hooks/rtk.mjs\')"',
-                                timeout: 5,
-                                statusMessage: 'Compressing command output with RTK',
-                            }],
-                    }],
-            },
-        }, null, 2) + '\n',
-        reason: 'rtk PreToolUse hook adapter',
+        content: codexHooks(targetDir),
+        reason: 'native RTK Codex hook; preserves foreign hooks and migrates the Yoke adapter',
     }, {
         kind: 'write',
         target: '.codex/hooks/rtk.mjs',
@@ -62,8 +62,8 @@ export function planCodex(canonDir, targetDir, codeGraph = 'graphify', codeIntel
     }, {
         kind: 'write',
         target: 'RTK.md',
-        content: rtkInstruction() + '\n',
-        reason: 'rtk instruction (Codex has no rewrite hook)',
+        content: rtkInstruction() + '\n\nCodex uses `rtk hook codex` when supported by the installed RTK. Run `yoke tools-preflight --json` to check native rewriting. Nested code-mode shell calls remain unverified; explicitly prefix verbose commands with RTK.\n',
+        reason: 'RTK guidance and operational verification',
     });
     for (const [name, description, sandbox, instructions] of roles) {
         actions.push({

package/dist/routing/attempts.js

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { statePath } from '../workspace/state.js';
+const Hash = z.string().regex(/^[a-f0-9]{64}$/u);
+const StoryHash = z.string().regex(/^[a-f0-9]{32}$/u);
+const ReservationSchema = z.object({
+    version: z.literal(1), id: z.string(), contractKey: Hash, storyId: z.string().min(1),
+    ordinal: z.number().int().min(1).max(8), startedAt: z.string().datetime(),
+    limit: z.number().int().min(1).max(8), executionPolicyKey: z.string().optional(),
+    profile: z.string().min(1), provider: z.string().min(1),
+    requestedProvider: z.string().optional(), requestedModel: z.string().optional(),
+    requestedReasoningEffort: z.string().optional(), requestedVariant: z.string().optional(),
+    accountingScope: z.enum(['worker', 'execution-attempt']),
+}).strict();
+const OutcomeSchema = z.object({
+    version: z.literal(1), attemptId: z.string(), finishedAt: z.string().datetime(),
+    verificationSuccess: z.boolean(), failureKind: z.enum(['implementation', 'infrastructure']),
+    actualModel: z.string().optional(),
+}).strict();
+const UsageSchema = z.object({
+    version: z.literal(1), callId: z.string().min(1), role: z.string().min(1),
+    inputTokens: z.number().finite().nonnegative().optional(), outputTokens: z.number().finite().nonnegative().optional(),
+    totalCostUsd: z.number().finite().nonnegative().optional(), durationMs: z.number().finite().nonnegative().optional(),
+    usageAvailable: z.boolean(), costMeasurementComplete: z.boolean(),
+}).strict();
+const taskHash = (storyId) => createHash('sha256').update(storyId).digest('hex').slice(0, 32);
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+function directory(root, story, contract, create = false) {
+    StoryHash.parse(story);
+    Hash.parse(contract);
+    const parts = ['routing-attempts', story, contract];
+    for (let count = 0; count <= parts.length; count++) {
+        const path = statePath(root, ...parts.slice(0, count));
+        if (create && !existsSync(path))
+            mkdirSync(path);
+        if (existsSync(path) && !lstatSync(path).isDirectory())
+            throw Error('Routing attempt state is not a directory');
+    }
+    return statePath(root, ...parts);
+}
+function location(root, attemptId) {
+    const match = /^([a-f0-9]{32})\.([a-f0-9]{64})\.([1-8])$/u.exec(attemptId);
+    if (!match)
+        throw Error('Invalid routing attempt identity');
+    return { directory: directory(root, match[1], match[2]), ordinal: Number(match[3]) };
+}
+function readJson(file) {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65_536)
+        throw Error('Invalid routing attempt state');
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+/** Publish complete JSON without replacing another process's reservation. The
+ * temporary file is flushed before the exclusive link makes it visible. */
+function publishOnce(file, value) {
+    // dirname must also support Windows paths.
+    const safeTemp = file.replace(/[^\\/]+$/u, `.reservation-${randomUUID()}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(safeTemp, 'wx', 0o600);
+        writeFileSync(descriptor, JSON.stringify(value));
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        try {
+            linkSync(safeTemp, file);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        rmSync(safeTemp, { force: true });
+    }
+}
+export function readRoutingAttempts(root, storyId, contractKey) {
+    const dir = directory(root, taskHash(storyId), contractKey);
+    if (!existsSync(dir))
+        return [];
+    const entries = [];
+    for (const name of readdirSync(dir).filter(name => /^attempt-[1-8]\.json$/u.test(name)).sort()) {
+        const reservation = ReservationSchema.parse(readJson(join(dir, name)));
+        if (reservation.storyId !== storyId || reservation.contractKey !== contractKey || reservation.id !== `${taskHash(storyId)}.${contractKey}.${reservation.ordinal}`)
+            throw Error('Routing attempt identity does not match its task');
+        const outcomeFile = join(dir, `outcome-${reservation.ordinal}.json`);
+        const outcome = existsSync(outcomeFile) ? OutcomeSchema.parse(readJson(outcomeFile)) : undefined;
+        if (outcome && outcome.attemptId !== reservation.id)
+            throw Error('Routing outcome identity changed');
+        entries.push({ reservation, ...(outcome ? { outcome } : {}) });
+    }
+    return entries;
+}
+export function reserveRoutingAttempt(input) {
+    if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 8)
+        throw Error('Invalid routing attempt limit');
+    // Corrupt state blocks admission; optional analytics never supplies the budget.
+    readRoutingAttempts(input.root, input.storyId, input.contractKey);
+    const story = taskHash(input.storyId);
+    const dir = directory(input.root, story, input.contractKey, true);
+    for (let ordinal = 1; ordinal <= input.limit; ordinal++) {
+        const reservation = ReservationSchema.parse({
+            version: 1, id: `${story}.${input.contractKey}.${ordinal}`, contractKey: input.contractKey,
+            storyId: input.storyId, ordinal, startedAt: input.startedAt ?? new Date().toISOString(),
+            limit: input.limit, executionPolicyKey: input.executionPolicyKey,
+            profile: input.profile, provider: input.provider,
+            requestedProvider: input.selection?.provider, requestedModel: input.selection?.model,
+            requestedReasoningEffort: input.selection?.reasoningEffort, requestedVariant: input.selection?.variant,
+            accountingScope: input.accountingScope ?? 'worker',
+        });
+        if (publishOnce(join(dir, `attempt-${ordinal}.json`), reservation))
+            return reservation;
+    }
+    throw Error('Routing attempt budget exhausted; revise the task plan before retrying');
+}
+export function recordRoutingAttemptUsage(root, attemptId, usage) {
+    const point = location(root, attemptId);
+    if (!existsSync(join(point.directory, `attempt-${point.ordinal}.json`)))
+        throw Error('Routing usage has no admitted attempt');
+    const dir = join(point.directory, `usage-${point.ordinal}`);
+    if (existsSync(dir) && (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory()))
+        throw Error('Invalid routing usage directory');
+    if (!existsSync(dir))
+        mkdirSync(dir);
+    const explicitCalls = Boolean(usage.calls?.length);
+    const calls = explicitCalls ? usage.calls : [usage];
+    for (const call of calls) {
+        const callId = call.callId ?? usage.callId ?? randomUUID();
+        const complete = (!('usageAvailable' in call) || call.usageAvailable !== false) && ('measurementComplete' in call ? call.measurementComplete !== false : true)
+            && (explicitCalls || usage.measurementComplete !== false);
+        const entry = UsageSchema.parse({
+            version: 1, callId, role: call.role ?? usage.role ?? 'unknown',
+            ...(finite(call.inputTokens) ? { inputTokens: call.inputTokens } : {}),
+            ...(finite(call.outputTokens) ? { outputTokens: call.outputTokens } : {}),
+            ...(finite(call.totalCostUsd) ? { totalCostUsd: call.totalCostUsd } : {}),
+            ...(finite(call.durationMs) ? { durationMs: call.durationMs } : {}),
+            usageAvailable: complete && finite(call.inputTokens) && finite(call.outputTokens),
+            costMeasurementComplete: finite(call.totalCostUsd) && call.costMeasurementComplete !== false && (explicitCalls || usage.costMeasurementComplete !== false),
+        });
+        publishOnce(join(dir, `${createHash('sha256').update(callId).digest('hex')}.json`), entry);
+    }
+}
+export function markRoutingAttemptUsageIncomplete(root, attemptId) {
+    const point = location(root, attemptId);
+    publishOnce(join(point.directory, `incomplete-${point.ordinal}.json`), { version: 1 });
+}
+/** Join role usage only when the story has exactly one open execution. Parallel
+ * candidates require an explicit attempt id; ambiguity can never look complete. */
+export function recordActiveRoutingUsage(root, storyId, usage) {
+    if (usage.routingAttemptId) {
+        recordRoutingAttemptUsage(root, usage.routingAttemptId, usage);
+        return true;
+    }
+    const story = taskHash(storyId);
+    const base = statePath(root, 'routing-attempts', story);
+    if (!existsSync(base))
+        return false;
+    if (!lstatSync(base).isDirectory())
+        throw Error('Invalid routing attempt directory');
+    const active = [];
+    const contracts = readdirSync(base).filter(name => /^[a-f0-9]{64}$/u.test(name));
+    if (contracts.length > 4096)
+        throw Error('Routing accounting history requires maintenance');
+    for (const contract of contracts) {
+        for (const entry of readRoutingAttempts(root, storyId, contract))
+            if (!entry.outcome)
+                active.push(entry.reservation);
+    }
+    if (active.length !== 1) {
+        for (const entry of active)
+            markRoutingAttemptUsageIncomplete(root, entry.id);
+        return false;
+    }
+    recordRoutingAttemptUsage(root, active[0].id, usage);
+    return true;
+}
+export function markActiveRoutingUsageIncomplete(root, storyId) {
+    const base = statePath(root, 'routing-attempts', taskHash(storyId));
+    if (!existsSync(base))
+        return;
+    const contracts = readdirSync(base).filter(name => /^[a-f0-9]{64}$/u.test(name));
+    for (const contract of contracts) {
+        for (const entry of readRoutingAttempts(root, storyId, contract))
+            if (!entry.outcome)
+                markRoutingAttemptUsageIncomplete(root, entry.reservation.id);
+    }
+}
+export function routingAttemptSummary(root, reservation, finishedAt = new Date().toISOString()) {
+    const point = location(root, reservation.id);
+    const dir = join(point.directory, `usage-${point.ordinal}`);
+    if (existsSync(dir) && (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory()))
+        throw Error('Invalid routing usage directory');
+    const names = existsSync(dir) ? readdirSync(dir).filter(name => /^[a-f0-9]{64}\.json$/u.test(name)) : [];
+    if (names.length > 10_000)
+        throw Error('Routing call ledger exceeds its limit');
+    const calls = names.map(name => UsageSchema.parse(readJson(join(dir, name))));
+    const ambiguous = existsSync(join(point.directory, `incomplete-${point.ordinal}.json`));
+    return {
+        calls: calls.length, usageComplete: !ambiguous && calls.length > 0 && calls.every(call => call.usageAvailable),
+        costComplete: !ambiguous && calls.length > 0 && calls.every(call => call.costMeasurementComplete),
+        ...(calls.some(call => call.totalCostUsd !== undefined) ? { totalCostUsd: calls.reduce((sum, call) => sum + (call.totalCostUsd ?? 0), 0) } : {}),
+        inputTokens: calls.reduce((sum, call) => sum + (call.inputTokens ?? 0), 0), outputTokens: calls.reduce((sum, call) => sum + (call.outputTokens ?? 0), 0),
+        durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(reservation.startedAt)), accountingScope: reservation.accountingScope,
+    };
+}
+export function finishRoutingAttempt(root, reservation, outcome) {
+    const point = location(root, reservation.id);
+    const file = join(point.directory, `outcome-${point.ordinal}.json`);
+    const result = OutcomeSchema.parse({ version: 1, attemptId: reservation.id, finishedAt: new Date().toISOString(), verificationSuccess: outcome.verificationSuccess, failureKind: outcome.failureKind ?? 'implementation', actualModel: outcome.actualModel });
+    publishOnce(file, result);
+    const stored = OutcomeSchema.parse(readJson(file));
+    return routingAttemptSummary(root, reservation, stored.finishedAt);
+}
+/** One economic observation covers the whole bounded execution sequence, charged
+ * to the starting profile. Escalation/repair spending is never made free by
+ * assigning it only to the final successful model. */
+export function routingEpisodeSummary(root, reservation) {
+    const entries = readRoutingAttempts(root, reservation.storyId, reservation.contractKey);
+    const initial = entries[0];
+    const last = entries.at(-1);
+    const summaries = entries.map(entry => routingAttemptSummary(root, entry.reservation, entry.outcome?.finishedAt));
+    const complete = entries.every(entry => Boolean(entry.outcome))
+        && (last.outcome?.verificationSuccess === true || entries.length >= last.reservation.limit);
+    return {
+        id: `${taskHash(reservation.storyId)}.${reservation.contractKey}`,
+        initial: initial.reservation, actualInitialModel: initial.outcome?.actualModel,
+        complete, success: last.outcome?.verificationSuccess === true,
+        infrastructureFailure: entries.some(entry => entry.outcome?.failureKind === 'infrastructure'),
+        attempts: entries.length,
+        costComplete: complete && summaries.every(summary => summary.costComplete && summary.usageComplete && summary.accountingScope === 'execution-attempt')
+            && entries.every(entry => entry.reservation.executionPolicyKey === initial.reservation.executionPolicyKey),
+        ...(summaries.some(summary => summary.totalCostUsd !== undefined) ? { totalCostUsd: summaries.reduce((sum, summary) => sum + (summary.totalCostUsd ?? 0), 0) } : {}),
+        durationMs: summaries.reduce((sum, summary) => sum + summary.durationMs, 0),
+    };
+}

package/dist/routing/capability.js

@@ -3,6 +3,8 @@ import { join } from 'node:path';
 import { AssessmentSchema, assessmentKey, requiredTier, tiers } from './assessment.js';
 import { projectHash, readRoutingObservations } from './registry.js';
 import { currentContractKey } from './contracts.js';
+import { readRoutingAttempts } from './attempts.js';
+import { optimizeCapability } from './optimization.js';
 export function knownInfrastructureFailure(summary) {
     return /\bENOENT\b|\bECONNREFUSED\b|\bETIMEDOUT\b|CreateProcess(?:AsUserW|W)? failed|Failed to create unified exec process|command not found|is not recognized as|Missing script:|rate limit exceeded|authentication failed|AuthRequired|No access token was provided|invalid api key|credentials (?:missing|not found)|quota exceeded/i.test(summary);
 }
@@ -48,16 +50,17 @@ export function taskOutcomes(root, story) {
 }
 export function chooseCapability(input) {
     const role = input.role ?? 'implementation';
-    const events = taskOutcomes(input.root, input.story);
-    const lastSuccess = events.map(e => e.verificationSuccess).lastIndexOf(true);
-    const failures = events.slice(lastSuccess + 1).filter(e => e.verificationSuccess === false);
+    const attempts = readRoutingAttempts(input.root, input.story.id, routingAssessmentKey(input.root, input.story));
+    const lastSuccess = attempts.map(entry => entry.outcome?.verificationSuccess).lastIndexOf(true);
+    const failures = attempts.slice(lastSuccess + 1).filter(entry => entry.outcome?.verificationSuccess === false && entry.outcome.failureKind !== 'infrastructure');
     const baseTier = requiredTier(input.assessment, role);
     const level = Math.min(3, tiers.indexOf(baseTier) + Math.max(0, failures.length - 1, (input.repairRound ?? 1) - 1));
-    const exhausted = failures.length >= Math.min(input.maxAttempts ?? 5, 5 - tiers.indexOf(baseTier));
+    const attemptLimit = Math.min(input.maxAttempts ?? 5, 5 - tiers.indexOf(baseTier));
+    const exhausted = attempts.length >= attemptLimit;
     const candidates = input.workers.filter(w => w.tier && tiers.indexOf(w.tier) >= level && (!input.maxTier || tiers.indexOf(w.tier) <= tiers.indexOf(input.maxTier)) && (!w.roles || w.roles.includes(role)) && (!input.story.agent || w.agent === input.story.agent) && (input.available?.(w.agent) ?? true));
-    const history = readRoutingObservations().filter(e => e.projectHash === projectHash(input.root) && e.taskClass === input.assessment.taskClass && e.requiredTier === baseTier && e.role === role && e.failureKind !== 'infrastructure' && Date.now() - Date.parse(e.recordedAt) < 30 * 86400000);
+    const history = readRoutingObservations().filter(e => e.projectHash === projectHash(input.root) && e.taskClass === input.assessment.taskClass && e.requiredTier === baseTier && e.role === role && Date.now() - Date.parse(e.recordedAt) < 30 * 86400000);
     const evidence = (w) => {
-        const matching = history.filter(e => e.provider === w.agent && e.requestedProvider === w.provider && e.requestedModel === w.model && e.requestedReasoningEffort === w.reasoningEffort && e.requestedVariant === w.variant && e.actualModel);
+        const matching = history.filter(e => e.failureKind !== 'infrastructure' && e.provider === w.agent && e.requestedProvider === w.provider && e.requestedModel === w.model && e.requestedReasoningEffort === w.reasoningEffort && e.requestedVariant === w.variant && e.actualModel);
         const actual = matching.at(-1)?.actualModel;
         return actual ? matching.filter(e => e.actualModel === actual) : [];
     };
@@ -65,13 +68,14 @@ export function chooseCapability(input) {
     const reliable = candidates.filter(w => { const rows = evidence(w); return rows.length < 10 || rows.filter(e => e.verificationSuccess).length / rows.length >= 0.8; });
     const cost = { low: 0, medium: 1, high: 2 };
     reliable.sort((a, b) => tiers.indexOf(a.tier) - tiers.indexOf(b.tier) || cost[a.costTier] - cost[b.costTier] || a.id.localeCompare(b.id));
-    const worker = reliable[0];
+    const economic = optimizeCapability({ workers: reliable, observations: history, assessment: input.assessment, settings: input.optimization, executionPolicyKey: input.executionPolicyKey, role });
+    const worker = economic.worker;
     const blocked = !worker && (input.fallback === 'block' || input.maxTier !== undefined);
     const provider = worker?.agent ?? input.story.agent ?? input.parent;
     const selection = worker ? { provider: worker.provider, model: worker.model, reasoningEffort: worker.reasoningEffort, variant: worker.variant, nativeMultiAgent: false, ...(provider !== 'gemini' && provider !== 'qwen' && provider !== 'pi' && provider !== 'hermes' && input.parentSelection?.bare !== undefined ? { bare: input.parentSelection.bare } : {}) }
         : { ...(provider === input.parent ? input.parentSelection : {}), nativeMultiAgent: false };
-    const reason = `${role}: ${tiers[level]}; ${input.assessment.reason}${failures.length ? `; ${failures.length} verified failure(s), ${failures.length === 1 ? 'one targeted repair' : 'escalated'}` : ''}${worker ? '' : '; no eligible profile, parent/provider fallback'}`;
-    return { worker, provider, selection, reason: blocked ? `${role}: no eligible profile within routing limits; execution blocked` : reason, blocked, requiredTier: baseTier, selectedTier: tiers[level], failures: failures.length, exhausted, next: input.maxTier && level >= tiers.indexOf(input.maxTier) ? 'stop at configured tier limit' : level < 3 ? tiers[level + 1] : 'stop after bounded attempts' };
+    const reason = `${role}: ${tiers[level]}; ${input.assessment.reason}${failures.length ? `; ${failures.length} verified failure(s), ${failures.length === 1 ? 'one targeted repair' : 'escalated'}` : ''}${worker ? '' : '; no eligible profile, parent/provider fallback'}${economic.reason ? `; ${economic.reason}` : ''}`;
+    return { worker, provider, selection, reason: blocked ? `${role}: no eligible profile within routing limits; execution blocked` : reason, blocked, requiredTier: baseTier, selectedTier: tiers[level], failures: failures.length, usedAttempts: attempts.length, attemptLimit, exhausted, next: input.maxTier && level >= tiers.indexOf(input.maxTier) ? 'stop at configured tier limit' : level < 3 ? tiers[level + 1] : 'stop after bounded attempts' };
 }
 /** Explicit role models are resolved by callers before consulting this fallback. */
 export function roleSelection(root, config, story, provider, role, repairRound = 1) {

package/dist/routing/optimization.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+export function assessmentSignature(assessment) {
+    const { taskClass, difficulty, uncertainty, risk, scope, testability } = assessment;
+    return createHash('sha256').update(JSON.stringify({ taskClass, difficulty, uncertainty, risk, scope, testability })).digest('hex');
+}
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+/** Compare completed, fully measured execution sequences, including failures and
+ * escalation, attributed to the initial profile. No benchmark probability, tier
+ * price estimate or incomplete successful-only sample is substituted for data. */
+export function optimizeCapability(input) {
+    const baseline = input.workers[0];
+    if (!baseline || !input.settings)
+        return { worker: baseline, reason: '' };
+    if (input.role !== 'implementation')
+        return { worker: baseline, reason: 'economic selection unchanged: independent role-quality evidence is unavailable' };
+    if (!input.executionPolicyKey)
+        return { worker: baseline, reason: 'economic selection unchanged: comparable execution-policy evidence is unavailable' };
+    const required = Math.max(10, input.settings.minSamples ?? 20);
+    const signature = assessmentSignature(input.assessment);
+    const evidence = new Map();
+    for (const worker of input.workers) {
+        const bySequence = new Map();
+        for (const event of input.observations) {
+            const episode = event.economicEpisode;
+            if (!episode || !episode.initial || typeof episode.id !== 'string' || episode.assessmentSignature !== signature || episode.initial.executionPolicyKey !== input.executionPolicyKey)
+                continue;
+            const initial = episode.initial;
+            if (initial.profile !== worker.id || initial.provider !== worker.agent || initial.requestedProvider !== worker.provider
+                || initial.requestedModel !== worker.model || initial.requestedReasoningEffort !== worker.reasoningEffort || initial.requestedVariant !== worker.variant)
+                continue;
+            // Registry records are chronological; a later completion replaces the
+            // earlier open sequence instead of double-counting its repair attempts.
+            bySequence.delete(episode.id);
+            bySequence.set(episode.id, episode);
+        }
+        const rows = [...bySequence.values()];
+        const actual = rows.filter(row => row.actualInitialModel).at(-1)?.actualInitialModel;
+        const latest = rows.filter(row => !row.actualInitialModel || row.actualInitialModel === actual).slice(-required);
+        if (latest.length < required || latest.some(row => !row.complete || !row.costComplete || row.infrastructureFailure || !row.actualInitialModel
+            || row.initial.accountingScope !== 'execution-attempt' || !finite(row.totalCostUsd) || !finite(row.durationMs)))
+            continue;
+        const accepted = latest.filter(row => row.success).length;
+        if (!accepted)
+            continue;
+        evidence.set(worker.id, { samples: latest.length, accepted,
+            costPerAccepted: latest.reduce((sum, row) => sum + row.totalCostUsd, 0) / accepted,
+            durationPerAccepted: latest.reduce((sum, row) => sum + row.durationMs, 0) / accepted, });
+    }
+    const initial = evidence.get(baseline.id);
+    if (!initial)
+        return { worker: baseline, reason: `economic selection unchanged: need ${required} recent complete comparable execution sequences for the baseline; incomplete costs and unknown models are excluded from decisions` };
+    let selected = baseline, best = initial;
+    for (const worker of input.workers.slice(1)) {
+        const candidate = evidence.get(worker.id);
+        // Equal sample windows make the accepted counts comparable. Optimization may
+        // not trade away even the observed completion rate to obtain a lower bill.
+        if (!candidate || candidate.accepted < initial.accepted)
+            continue;
+        const improves = input.settings.objective === 'cost'
+            ? candidate.costPerAccepted < best.costPerAccepted
+            : input.settings.objective === 'speed'
+                ? candidate.durationPerAccepted < best.durationPerAccepted
+                : candidate.costPerAccepted <= best.costPerAccepted && candidate.durationPerAccepted <= best.durationPerAccepted
+                    && (candidate.costPerAccepted < best.costPerAccepted || candidate.durationPerAccepted < best.durationPerAccepted);
+        if (improves) {
+            selected = worker;
+            best = candidate;
+        }
+    }
+    return { worker: selected,
+        reason: `economic ${input.settings.objective}: ${selected.id}; ${best.samples} fully measured comparable execution sequences, ${best.accepted}/${best.samples} accepted; observed $${best.costPerAccepted.toFixed(4)} and ${(best.durationPerAccepted / 1000).toFixed(1)}s per accepted sequence including failed attempts and escalation; observational evidence, not a calibrated forecast`,
+    };
+}

package/dist/routing/registry.js

@@ -45,7 +45,13 @@ export function readRoutingObservations(limit = 1000) {
     const dir = eventsDir();
     if (!existsSync(dir))
         return [];
-    const files = readdirSync(dir).filter(file => file.endsWith('.json')).sort().slice(-limit);
+    let files;
+    try {
+        files = readdirSync(dir).filter(file => file.endsWith('.json')).sort().slice(-limit);
+    }
+    catch {
+        return [];
+    } // Optional evidence must never decide whether a task can run.
     const observations = [];
     for (const file of files) {
         try {