@hecer/yoke 1.21.1 → 1.22.0

package/dist/observability/invocation.js

@@ -0,0 +1,42 @@
+import { randomUUID } from 'node:crypto';
+import { parseProviderTelemetry } from '../agents/telemetry.js';
+import { appendEvent } from './events.js';
+import { providerTelemetryUsage } from './usage.js';
+/** A single invocation boundary, including failures and injected runner seams. */
+export function measureInvocation(options) {
+    const started = Date.now(), callId = randomUUID(), runId = options.runId ?? randomUUID();
+    let result;
+    let failure;
+    const base = { runId, storyId: options.storyId, attemptId: callId, agent: options.agent, role: options.role };
+    appendEvent(options.root, { ...base, timestamp: new Date(started).toISOString(), type: 'status', data: { callId, parentCallId: options.parentCallId, state: 'started' } });
+    try {
+        result = options.execute(options.invocation);
+        return result;
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        let salvaged;
+        try {
+            const stdout = failure && typeof failure === 'object' && 'stdout' in failure ? failure.stdout : undefined;
+            salvaged = stdout == null ? undefined : providerTelemetryUsage(parseProviderTelemetry(options.agent, String(stdout).split(/\r?\n/u)));
+        }
+        catch { /* Failed measurement must not replace the original provider error. */ }
+        const usage = result?.tokens ?? salvaged;
+        const complete = usage !== undefined && usage.measurementComplete !== false;
+        const durationMs = Date.now() - started;
+        appendEvent(options.root, {
+            ...base, timestamp: new Date().toISOString(), type: 'tokens', durationMs, outcome: result?.success ? 'succeeded' : 'failed',
+            data: {
+                ...usage, callId, parentCallId: options.parentCallId,
+                provider: options.agent, role: options.role,
+                requestedProvider: options.selection?.provider, requestedModel: options.selection?.model,
+                requestedReasoningEffort: options.selection?.reasoningEffort, requestedVariant: options.selection?.variant,
+                actualModel: usage?.model, measurementComplete: complete, usageAvailable: complete,
+                costMeasurementComplete: usage?.costMeasurementComplete ?? (typeof usage?.totalCostUsd === 'number'),
+            },
+        });
+    }
+}

package/dist/observability/usage.js

@@ -0,0 +1,17 @@
+/** Preserve known lower bounds; missing telemetry must never become a free call. */
+export function providerTelemetryUsage(telemetry) {
+    if (!telemetry.tokens && !telemetry.partialUsage)
+        return undefined;
+    const known = { ...telemetry.partialUsage, ...telemetry.tokens };
+    if (!Object.values(known).some(value => typeof value === 'number'))
+        return undefined;
+    const model = known.model ?? (telemetry.reportedModels?.length === 1 ? telemetry.reportedModels[0] : undefined);
+    return {
+        ...known,
+        ...(model ? { model } : {}),
+        inputTokens: known.inputTokens ?? 0,
+        outputTokens: known.outputTokens ?? 0,
+        measurementComplete: telemetry.usageAvailable,
+        costMeasurementComplete: typeof telemetry.tokens?.totalCostUsd === 'number',
+    };
+}

package/dist/prd/command.js

@@ -7,9 +7,11 @@ import { bindAssessments, preparedProblems } from './assess.js';
 import { resolvePlanner } from '../routing/planning.js';
 import { readPlanningFile } from '../routing/contracts.js';
 import { acquireLock, releaseLock } from '../loop/lock.js';
-import { agentInvocation, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
+import { agentInvocation, buildWatchdogInvocation, runCapturedAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
+import { measureInvocation } from '../observability/invocation.js';
+import { statePath } from '../workspace/state.js';
 export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority open story each iteration.
 # Story format (see canon/loop/prd.schema.md):
 # - id: STORY-1
@@ -92,14 +94,25 @@ export function runPrdDraft(targetDir, opts) {
     }
     try {
         const before = readPlanningFile(targetDir, '.yoke/prd.yaml');
-        const rollback = () => { if (before === undefined)
-            rmSync(path, { force: true });
-        else
-            writeFileSync(path, before); };
+        const rollback = () => {
+            const destination = join(statePath(targetDir), 'prd.yaml');
+            // Unlink a provider-created file link instead of writing through it.
+            rmSync(destination, { force: true });
+            if (before !== undefined)
+                writeFileSync(destination, before, { flag: 'wx' });
+        };
         const inv = agentInvocation(agent, buildPrdDraftPrompt(idea, planningBrief), targetDir, 'safe', planner.selection);
         console.log(`Drafting PRD with ${agent}...`);
-        const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
-        const result = run(inv);
+        const run = opts.run ?? ((i) => runCapturedAgent(agent, buildWatchdogInvocation(i, idleMs)));
+        let result;
+        try {
+            result = measureInvocation({ root: targetDir, agent, role: 'prd-draft', selection: planner.selection, invocation: inv, execute: run });
+        }
+        catch (error) {
+            rollback();
+            console.error(`PRD draft failed: ${error.message}`);
+            return 1;
+        }
         if (!result.success) {
             rollback();
             console.error(`PRD draft failed: ${result.summary}`);

package/dist/prd/decompose.js

@@ -11,7 +11,8 @@ import { writeScopesOverlap, validWriteScope } from '../loop/scheduler.js';
 import { withSharedWorkerSync } from '../loop/resource-pool.js';
 import { loadConfig } from '../retrofit/config.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
-import { agentInvocation, buildWatchdogInvocation, isAgentAvailable, runAgent } from '../loop/runner.js';
+import { agentInvocation, buildWatchdogInvocation, isAgentAvailable, runCapturedAgent } from '../loop/runner.js';
+import { measureInvocation } from '../observability/invocation.js';
 const ProposalSchema = z.array(z.object({
     id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u),
     title: z.string().min(1).max(300),
@@ -181,7 +182,9 @@ export function runPrdDecompose(root, options) {
         if (prompt.length > 60_000)
             throw Error('Planning input exceeds 60000 characters; condense .yoke/plan.md first');
         const invocation = agentInvocation(planner.agent, prompt, root, 'safe', planner.selection);
-        const result = withSharedWorkerSync({ targetDir: root, storyId: `prd-decompose:${parent.id}`, provider: planner.agent, role: 'implementation' }, () => (options.run ?? (item => runAgent(buildWatchdogInvocation(item, options.timeoutMinutes === undefined ? 20 * 60_000 : options.timeoutMinutes > 0 ? options.timeoutMinutes * 60_000 : 0))))(invocation));
+        const result = withSharedWorkerSync({ targetDir: root, storyId: `prd-decompose:${parent.id}`, provider: planner.agent, role: 'implementation' }, () => measureInvocation({ root, agent: planner.agent, role: 'prd-decompose', storyId: parent.id, selection: planner.selection, invocation,
+            execute: options.run ?? (item => runCapturedAgent(planner.agent, buildWatchdogInvocation(item, options.timeoutMinutes === undefined ? 20 * 60_000 : options.timeoutMinutes > 0 ? options.timeoutMinutes * 60_000 : 0))),
+        }));
         if (!result.success)
             throw Error(`planning request failed: ${result.summary}`);
         if (!existsSync(proposalPath))

package/dist/retrofit/config.js

@@ -16,7 +16,21 @@ const CodeIntelligenceSchema = z.object({
     policy: z.object({ allowNetwork: z.boolean().default(false), excludePatterns: z.array(z.string().min(1)).max(100).default([]), maxFileBytes: z.number().int().positive().max(20_000_000).optional() }).optional(),
     limits: z.object({ tokenBudget: z.number().int().min(128).max(16000).default(2400), timeoutMs: z.number().int().min(100).max(600000).default(10000), maxBytes: z.number().int().positive().max(10_000_000).default(2_000_000), maxBackends: z.number().int().min(1).max(3).default(3) }).optional(),
 });
-const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() });
+const SmokeStepTimeout = z.number().int().min(1).max(30000).optional();
+const SmokeSelector = z.string().min(1).max(4096);
+const SmokeStepSchema = z.discriminatedUnion('action', [
+    z.object({ action: z.literal('click'), selector: SmokeSelector, timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('fill'), selector: SmokeSelector, value: z.string().max(8192).optional(), valueEnv: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u).optional(), timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('press'), selector: SmokeSelector, key: z.string().min(1).max(128), timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('expect-visible'), selector: SmokeSelector, timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('expect-text'), selector: SmokeSelector, text: z.string().max(8192), exact: z.boolean().optional(), timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('expect-url'), url: z.string().min(1).max(4096), timeoutMs: SmokeStepTimeout }).strict(),
+    z.object({ action: z.literal('reload'), timeoutMs: SmokeStepTimeout }).strict(),
+]).superRefine((step, context) => {
+    if (step.action === 'fill' && (step.value === undefined) === (step.valueEnv === undefined))
+        context.addIssue({ code: 'custom', message: 'A fill step needs exactly one of value or valueEnv' });
+});
+const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional(), timeoutMs: z.number().int().min(1).max(120000).optional(), steps: z.array(SmokeStepSchema).min(1).max(50).optional() });
 const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
 const OutputPolicySchema = z.object({
     previewBytes: z.number().int().positive().optional(),
@@ -56,6 +70,12 @@ const RoutingWorkerSchema = z.object({
     capabilities: z.array(z.string().min(1)).default([]),
     tier: z.enum(['light', 'standard', 'strong', 'frontier']).optional(),
     roles: z.array(z.enum(['implementation', 'reviewer', 'critic', 'repair'])).optional(),
+    profileMetadata: z.object({
+        version: z.literal(1),
+        catalog: z.string().min(1).max(120),
+        source: z.enum(['yoke-default', 'operator']),
+        basis: z.literal('configured-prior'),
+    }).strict().optional(),
 });
 const RoutingRuleSchema = z.object({
     area: z.string().min(1).optional(),
@@ -104,6 +124,11 @@ export const YokeConfigSchema = z.object({
         assessmentPolicy: z.enum(['on-demand', 'prepared']).optional(),
         fallback: z.enum(['parent', 'block']).optional(),
         maxTier: z.enum(['light', 'standard', 'strong', 'frontier']).optional(),
+        optimization: z.object({
+            version: z.literal(1),
+            objective: z.enum(['cost', 'speed', 'balanced']),
+            minSamples: z.number().int().min(10).max(10000).optional(),
+        }).strict().optional(),
         maxCandidates: z.number().int().min(1).max(5).default(3),
         orchestrator: z.object({
             provider: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/).optional(),

package/dist/retrofit/gitignore.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 export const YOKE_IGNORE_LINES = [
     '.yoke/worktrees/',
     '.yoke/integration-recovery/',
+    '.yoke/failure-progress/',
     '.yoke/run-state.json',
     '.yoke/run-state.*.tmp',
     '.yoke/backup/',
@@ -31,6 +32,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',

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 {