@hecer/yoke 1.21.1 → 1.23.0

package/dist/loop/worker.js

@@ -1,8 +1,12 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
 import { knownInfrastructureFailure } from "../routing/capability.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { acceptanceProtectionProblem } from "../check/command.js";
 import { isAcceptanceCriterion } from './prd.js';
+import { observeFailure } from './failure.js';
+import { consumeAmbiguity } from './loop.js';
+import { gateIdentity, snapshotGates, reuseGates } from './gate-snapshot.js';
 import { runQualityRepairLoop } from '../quality/loop.js';
 function emptyEvidence() { return { criteria: [] }; }
 function errorMessage(error) {
@@ -40,6 +44,10 @@ function reviewOutcome(result) {
     return { kind: 'malformed', summary: result.summary };
 }
 function runMechanicalGates(input, context, evidence) {
+    evidence.criteria = [];
+    const cacheProblem = input.failureRoot && input.failureRoot !== context.targetDir ? cacheIsolationProblem(context.targetDir) : undefined;
+    if (cacheProblem)
+        return { kind: 'failed', stage: 'verify', summary: cacheProblem };
     const criteria = context.story.acceptance.filter(isAcceptanceCriterion);
     if (criteria.length === 0) {
         if (input.requireCriterionEvidence)
@@ -170,8 +178,13 @@ export async function runStoryWorker(input) {
         return finalResult(input, { ...baseResult(input, evidence, preflight.summary), kind: 'mechanical-failure', stage: 'quality' });
     }
     let implementation;
+    let verified;
+    let failure;
     try {
-        implementation = await runWorkerImplementation(input, context, evidence);
+        const outcome = await runWorkerImplementation(input, context, evidence);
+        implementation = outcome.result;
+        verified = outcome.gates;
+        failure = outcome.failure;
     }
     catch (error) {
         return finalResult(input, {
@@ -185,110 +198,158 @@ export async function runStoryWorker(input) {
     if (implementation.infrastructureFailure)
         implementation.routing?.recordOutcome(false, 'infrastructure');
     if (implementation.infrastructureFailure || implementation.routing?.blocked)
-        return finalResult(input, { ...baseResult(input, evidence, implementation.summary), kind: "mechanical-failure", stage: "implementation" });
-    const afterImplementationCancellation = cancellationReason(input.cancellation);
-    if (afterImplementationCancellation) {
-        return finalResult(input, { ...baseResult(input, evidence, afterImplementationCancellation), kind: 'cancelled' });
-    }
-    const decision = input.beforeGates?.(context);
-    if (decision) {
-        return finalResult(input, { ...baseResult(input, evidence, decision), kind: 'paused', reason: 'decision' });
-    }
-    const gates = runMechanicalGates(input, context, evidence);
-    if (gates.kind === 'cancelled') {
-        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'cancelled' });
-    }
-    if (gates.kind === 'failed') {
-        implementation.routing?.recordOutcome(false);
-        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'mechanical-failure', stage: gates.stage });
-    }
-    const summary = implementation.success
-        ? implementation.summary
-        : `${implementation.summary} (runner exited non-zero but verify is green)`;
-    if (!qualityEnabled && !input.review) {
-        return finalResult(input, {
-            ...baseResult(input, evidence, summary),
-            kind: 'candidate',
-            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
-            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+        return finalResult(input, { ...baseResult(input, evidence, implementation.summary), kind: "mechanical-failure", stage: "implementation", ...(failure ? { failure } : {}) });
+    try {
+        const afterImplementationCancellation = cancellationReason(input.cancellation);
+        if (afterImplementationCancellation) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, afterImplementationCancellation), kind: 'cancelled' });
+        }
+        const ambiguity = consumeAmbiguity(context.targetDir);
+        if (ambiguity) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, {
+                ...baseResult(input, evidence, `story ${context.story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`),
+                kind: 'paused', reason: 'ambiguity',
+            });
+        }
+        const decision = input.beforeGates?.(context);
+        if (decision) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, decision), kind: 'paused', reason: 'decision' });
+        }
+        if (input.pause?.()) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, 'worker paused before acceptance checks'), kind: 'paused' });
+        }
+        const gates = reuseGates(context.targetDir, context.story, verified) ?? runMechanicalGates(input, context, evidence);
+        if (gates.kind === 'cancelled') {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'cancelled' });
+        }
+        if (gates.kind === 'failed') {
+            implementation.routing?.recordOutcome(false);
+            const observed = input.failureRoot ? observeFailure({ root: input.failureRoot, scope: input.failureScope, directory: context.targetDir, story: context.story, stage: gates.stage, summary: gates.summary }) : undefined;
+            return finalResult(input, { ...baseResult(input, evidence, observed?.feedback ?? gates.summary), kind: 'mechanical-failure', stage: gates.stage, ...(observed ? { failure: observed.failure } : {}) });
+        }
+        const summary = implementation.success
+            ? implementation.summary
+            : `${implementation.summary} (runner exited non-zero but verify is green)`;
+        if (!qualityEnabled && !input.review) {
+            return finalResult(input, {
+                ...baseResult(input, evidence, summary),
+                kind: 'candidate',
+                routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+                ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+            });
+        }
+        const beforeQualityCancellation = cancellationReason(input.cancellation);
+        if (beforeQualityCancellation) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, beforeQualityCancellation), kind: 'cancelled' });
+        }
+        const qualityStage = qualityEnabled ? input.qualityStage : undefined;
+        const review = input.review;
+        let qualityFailure;
+        const quality = runQualityRepairLoop({
+            ...(qualityStage
+                ? { quality: (round) => {
+                        input.reporter?.phase('comparing');
+                        return qualityStage(context, round);
+                    } }
+                : {}),
+            ...(review
+                ? { review: () => {
+                        input.reporter?.phase('reviewing');
+                        return reviewOutcome(review(context));
+                    } }
+                : {}),
+            repair: request => {
+                if (!input.repair)
+                    return { kind: 'blocked', summary: 'repair callback is not configured' };
+                input.reporter?.phase('repairing');
+                const observed = input.failureRoot ? observeFailure({ root: input.failureRoot, scope: input.failureScope, directory: context.targetDir, story: context.story, stage: 'quality', summary: JSON.stringify(request.finding) }) : undefined;
+                if (observed?.action === 'blocked') {
+                    qualityFailure = observed.failure;
+                    return { kind: 'blocked', summary: observed.feedback };
+                }
+                const targetedRequest = observed?.action === 'diagnose' ? { ...request, finding: { ...request.finding, message: observed.feedback } } : request;
+                const repair = input.repair(context, targetedRequest);
+                return repair.success ? { kind: 'repaired' } : { kind: 'blocked', summary: repair.summary };
+            },
+            rerunGates: () => {
+                const rerun = runMechanicalGates(input, context, evidence);
+                if (rerun.kind === 'passed')
+                    return { kind: 'passed' };
+                if (rerun.kind === 'cancelled')
+                    return rerun;
+                return { kind: 'failed', stage: rerun.stage, summary: rerun.summary };
+            },
+            ...(input.repairLimits ? { limits: input.repairLimits } : {}),
+            pause: input.pause,
+            onStatus: status => {
+                const metadata = input.qualityMetadata?.(context);
+                input.reporter?.quality({ ...status, ...(metadata ?? { policy: 'blocking' }) });
+            },
         });
+        evidence.quality = quality;
+        const afterQualityCancellation = cancellationReason(input.cancellation);
+        if (afterQualityCancellation) {
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+            return finalResult(input, { ...baseResult(input, evidence, afterQualityCancellation), kind: 'cancelled' });
+        }
+        const result = { ...resultFromQuality(input, evidence, summary, quality), ...(qualityFailure ? { failure: qualityFailure } : {}) };
+        if (result.kind === 'paused' || result.kind === 'cancelled' || result.kind === 'review-failure' || result.kind === 'quality-failure')
+            implementation.routing?.recordOutcome(false, 'infrastructure');
+        else if (result.kind !== 'candidate')
+            implementation.routing?.recordOutcome(false);
+        if (result.kind === 'candidate') {
+            return finalResult(input, {
+                ...result,
+                routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+                ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+            });
+        }
+        return finalResult(input, result);
     }
-    const beforeQualityCancellation = cancellationReason(input.cancellation);
-    if (beforeQualityCancellation) {
-        return finalResult(input, { ...baseResult(input, evidence, beforeQualityCancellation), kind: 'cancelled' });
-    }
-    const qualityStage = qualityEnabled ? input.qualityStage : undefined;
-    const review = input.review;
-    const quality = runQualityRepairLoop({
-        ...(qualityStage
-            ? { quality: (round) => {
-                    input.reporter?.phase('comparing');
-                    return qualityStage(context, round);
-                } }
-            : {}),
-        ...(review
-            ? { review: () => {
-                    input.reporter?.phase('reviewing');
-                    return reviewOutcome(review(context));
-                } }
-            : {}),
-        repair: request => {
-            if (!input.repair)
-                return { kind: 'blocked', summary: 'repair callback is not configured' };
-            input.reporter?.phase('repairing');
-            const repair = input.repair(context, request);
-            return repair.success ? { kind: 'repaired' } : { kind: 'blocked', summary: repair.summary };
-        },
-        rerunGates: () => {
-            const rerun = runMechanicalGates(input, context, evidence);
-            if (rerun.kind === 'passed')
-                return { kind: 'passed' };
-            if (rerun.kind === 'cancelled')
-                return rerun;
-            return { kind: 'failed', stage: rerun.stage, summary: rerun.summary };
-        },
-        ...(input.repairLimits ? { limits: input.repairLimits } : {}),
-        pause: input.pause,
-        onStatus: status => {
-            const metadata = input.qualityMetadata?.(context);
-            input.reporter?.quality({ ...status, ...(metadata ?? { policy: 'blocking' }) });
-        },
-    });
-    evidence.quality = quality;
-    const afterQualityCancellation = cancellationReason(input.cancellation);
-    if (afterQualityCancellation) {
-        return finalResult(input, { ...baseResult(input, evidence, afterQualityCancellation), kind: 'cancelled' });
-    }
-    const result = resultFromQuality(input, evidence, summary, quality);
-    if (result.kind !== 'candidate' && result.kind !== 'paused')
-        implementation.routing?.recordOutcome(false);
-    if (result.kind === 'candidate') {
-        return finalResult(input, {
-            ...result,
-            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
-            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
-        });
+    catch (error) {
+        implementation.routing?.recordOutcome(false, 'infrastructure');
+        throw error;
     }
-    return finalResult(input, result);
 }
 async function runWorkerImplementation(input, context, evidence) {
-    let feedback;
+    let feedback = input.feedback;
     for (let attempt = 0;; attempt++) {
         const result = await input.runner({ ...context, feedback });
+        const cacheProblem = input.failureRoot && input.failureRoot !== context.targetDir ? cacheIsolationProblem(context.targetDir) : undefined;
+        if (cacheProblem)
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: cacheProblem } };
         if (!result.routing?.canRetry || result.routing.blocked || attempt >= 7 || cancellationReason(input.cancellation) || input.pause?.())
-            return result;
+            return { result };
         if (["decision-request.yaml", "ambiguity.md", "loop.pause"].some(name => existsSync(join(context.targetDir, ".yoke", name))) || acceptanceProtectionProblem(context.targetDir))
-            return result;
-        const gates = runMechanicalGates(input, context, evidence);
-        if (gates.kind !== "failed")
-            return result;
+            return { result };
+        const before = gateIdentity(context.targetDir, context.story);
+        let gates;
+        try {
+            gates = runMechanicalGates(input, context, evidence);
+        }
+        catch (error) {
+            result.routing.recordOutcome(false, 'infrastructure');
+            throw error;
+        }
+        if (gates.kind !== 'failed') {
+            return { result, ...(gates.kind === 'passed' ? { gates: snapshotGates(context.targetDir, context.story, before, gates) } : {}) };
+        }
         if (knownInfrastructureFailure(gates.summary)) {
             result.routing.recordOutcome(false, 'infrastructure');
-            return { ...result, success: false, infrastructureFailure: true, summary: gates.summary, routing: { ...result.routing, blocked: true, canRetry: false } };
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: gates.summary, routing: { ...result.routing, blocked: true, canRetry: false } } };
         }
         result.routing.recordOutcome(false);
+        const observed = input.failureRoot ? observeFailure({ root: input.failureRoot, scope: input.failureScope, directory: context.targetDir, story: context.story, stage: gates.stage, summary: gates.summary }) : undefined;
+        if (observed?.action === 'blocked')
+            return { result: { ...result, success: false, summary: observed.feedback, routing: { ...result.routing, blocked: true, canRetry: false } }, failure: observed.failure };
         if (result.tokens)
             input.reporter?.addTokens(result.tokens);
-        feedback = gates.summary;
+        feedback = observed?.feedback ?? gates.summary;
     }
 }

package/dist/observability/history.js

@@ -30,7 +30,8 @@ export function archiveMeasurement(root, event) {
             throw error;
     }
     const data = event.data ?? {};
-    const allowed = ['inputTokens', 'outputTokens', 'cachedInputTokens', 'cacheWriteInputTokens', 'reasoningOutputTokens', 'totalCostUsd', 'agent', 'provider', 'model', 'actualModel', 'requestedModel', 'variant', 'role', 'calls', 'measurementComplete', 'costMeasurementComplete', 'usageAvailable', 'prediction', 'errorMs', 'withinObservedRange', 'escalated'];
+    const allowed = ['inputTokens', 'outputTokens', 'cachedInputTokens', 'cacheWriteInputTokens', 'reasoningOutputTokens', 'totalCostUsd', 'agent', 'provider', 'model', 'actualModel', 'requestedProvider', 'requestedModel', 'requestedReasoningEffort', 'requestedVariant', 'variant', 'role', 'callId', 'parentCallId', 'calls', 'measurementComplete', 'costMeasurementComplete', 'usageAvailable', 'prediction', 'errorMs', 'withinObservedRange', 'escalated'];
+    allowed.push('usageSource', 'usageMissingFields', 'usagePartialFields', 'failureCategory');
     const compact = { ...event, data: Object.fromEntries(allowed.filter(key => data[key] !== undefined).map(key => [key, data[key]])) };
     appendFileSync(file, JSON.stringify(compact) + '\n');
 }

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/local-report.js

@@ -0,0 +1,120 @@
+import { EVENT_CAP, readEvents } from './events.js';
+import { readMeasurements } from './history.js';
+const fields = ['inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningOutputTokens', 'totalCostUsd'];
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const text = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+function intervalTotals(events) {
+    const intervals = events.flatMap(event => {
+        const end = Date.parse(event.timestamp);
+        return finite(event.durationMs) && Number.isFinite(end) ? [[end - event.durationMs, end]] : [];
+    }).sort((a, b) => a[0] - b[0]);
+    if (!intervals.length)
+        return { sumMs: null, unionMs: null };
+    let sumMs = 0, unionMs = 0, end = -Infinity;
+    for (const [start, stop] of intervals) {
+        sumMs += stop - start;
+        unionMs += Math.max(0, stop - Math.max(start, end));
+        end = Math.max(end, stop);
+    }
+    return { sumMs, unionMs };
+}
+/** Recorded evidence only. Parent views conservatively cover their identified children. */
+export function summarizeUsageEvents(input) {
+    const events = [...new Map(input.map(event => [event.id, event])).values()];
+    const byId = new Map();
+    for (const event of events) {
+        if (event.type !== 'tokens')
+            continue;
+        const data = event.data ?? {};
+        const breakdown = Array.isArray(data.calls) && data.calls.length > 0;
+        const records = breakdown ? data.calls : [data];
+        records.forEach((record, index) => {
+            if (!record || typeof record !== 'object' || Array.isArray(record))
+                return;
+            const raw = record;
+            const callId = text(raw.callId) ?? `${event.id}:${index}`;
+            // IDs identify views of the same invocation even across reporter run IDs.
+            const durationMs = finite(raw.durationMs) ? raw.durationMs : !breakdown && finite(event.durationMs) ? event.durationMs : null;
+            const previous = byId.get(callId);
+            if (previous) {
+                previous.durationMs ??= durationMs;
+                return;
+            }
+            const missing = Array.isArray(raw.usageMissingFields) ? raw.usageMissingFields : [];
+            const partial = Array.isArray(raw.usagePartialFields) ? raw.usagePartialFields : [];
+            const metrics = Object.fromEntries(fields.map(field => [field, !missing.includes(field) && finite(raw[field]) ? raw[field] : null]));
+            const complete = raw.usageAvailable !== false && raw.measurementComplete !== false
+                && (breakdown || (data.usageAvailable !== false && data.measurementComplete !== false))
+                && metrics.inputTokens !== null && metrics.outputTokens !== null;
+            const coverage = complete ? 'measured' : fields.some(field => metrics[field] !== null) ? 'partial' : 'unknown';
+            byId.set(callId, {
+                ...metrics, callId, parentCallId: text(raw.parentCallId ?? data.parentCallId), runId: event.runId,
+                attemptId: event.attemptId, storyId: event.storyId,
+                role: text(raw.role ?? event.role ?? data.role) ?? 'unknown',
+                provider: text(raw.provider ?? event.provider ?? data.provider ?? event.agent),
+                source: text(raw.usageSource ?? data.usageSource) ?? 'local-event', coverage,
+                costCoverage: metrics.totalCostUsd === null ? 'unknown' : raw.costMeasurementComplete === false || (!breakdown && data.costMeasurementComplete === false) ? 'partial' : 'measured',
+                missingFields: fields.filter(field => metrics[field] === null),
+                fieldCoverage: Object.fromEntries(fields.map(field => [field, metrics[field] === null ? 'unknown' : partial.includes(field) ? 'partial' : 'measured'])),
+                durationMs,
+                counted: true,
+            });
+        });
+    }
+    const calls = [...byId.values()];
+    for (const call of calls) {
+        if (call.parentCallId && byId.has(call.parentCallId)) {
+            call.counted = false;
+            call.exclusion = 'parent-view-overlap';
+        }
+    }
+    const counted = calls.filter(call => call.counted);
+    const sum = (key, values = counted) => {
+        const measured = values.map(call => call[key]).filter((value) => value !== null);
+        return measured.length ? measured.reduce((total, value) => total + value, 0) : null;
+    };
+    const coverage = (values) => !values.length || values.every(call => call.coverage === 'unknown') ? 'unknown' : values.every(call => call.coverage === 'measured') ? 'measured' : 'partial';
+    const unmeasuredAttempts = events.filter(event => event.type === 'attempt-ended' && !calls.some(call => call.runId === event.runId && call.attemptId === event.attemptId)).length;
+    const inputTokens = sum('inputTokens'), outputTokens = sum('outputTokens');
+    const phases = events.filter(event => event.type === 'phase-ended');
+    const phaseTime = intervalTotals(phases), attemptTime = intervalTotals(events.filter(event => event.type === 'attempt-ended'));
+    const failures = { observer: 0, infrastructure: 0, product: 0, unknown: 0 };
+    for (const event of events) {
+        if (!['failed', 'blocked', 'rejected', 'error'].includes(event.outcome ?? ''))
+            continue;
+        const category = event.data?.failureCategory;
+        failures[category === 'observer' || category === 'infrastructure' || category === 'product' ? category : 'unknown']++;
+    }
+    return {
+        calls,
+        total: { inputTokens, cachedInputTokens: sum('cachedInputTokens'), outputTokens, reasoningOutputTokens: sum('reasoningOutputTokens'),
+            totalTokens: inputTokens !== null && outputTokens !== null ? inputTokens + outputTokens : null,
+            totalCostUsd: sum('totalCostUsd'), coverage: unmeasuredAttempts && coverage(counted) === 'measured' ? 'partial' : coverage(counted),
+            costCoverage: !counted.length || counted.every(call => call.costCoverage === 'unknown') ? 'unknown' : counted.every(call => call.costCoverage === 'measured') && !unmeasuredAttempts ? 'measured' : 'partial', },
+        hostCoverage: { guardian: coverage(calls.filter(call => call.role === 'guardian')), approval: coverage(calls.filter(call => call.role === 'approval')) },
+        // Serial makeRunner labels story implementation as parent; routing controllers use orchestrator.
+        time: { workerProcessDurationMs: sum('durationMs', counted.filter(call => call.role === 'worker' || (call.role === 'parent' && call.storyId !== undefined))),
+            phaseDurationSumMs: phaseTime.sumMs, phaseDurationUnionMs: phaseTime.unionMs,
+            attemptDurationSumMs: attemptTime.sumMs, attemptDurationUnionMs: attemptTime.unionMs,
+            phases: [...new Set(phases.map(event => event.phase ?? 'unknown'))].sort().map(phase => ({ phase, ...intervalTotals(phases.filter(event => (event.phase ?? 'unknown') === phase)) })),
+        },
+        failures, unmeasuredAttempts,
+        limitations: ['Recorded local events only; unrecorded host sessions and approvals remain unknown.',
+            'Totals are known lower bounds when coverage is partial; missing prices remain unknown.',
+            'Cache read is contained in input; reasoning is contained in output.',
+            'Identified child views are excluded when a parent view exists; disjoint usage is not assumed.',
+            'Intervals derive from recorded end times and durations; unrecorded waiting time is unknown.'],
+    };
+}
+/** No model/provider invocation: reads bounded local history and recent events. */
+export function localUsageReport(root, options) {
+    const { from, to, runId } = options;
+    if (!Number.isFinite(from) || !Number.isFinite(to) || from >= to || to - from > 366 * 86400000)
+        throw Error('Choose a valid period of at most 366 days');
+    const history = readMeasurements(root, from, to);
+    const events = [...history.events, ...readEvents(root, EVENT_CAP)].filter(event => {
+        const time = Date.parse(event.timestamp);
+        return time >= from && time < to && (!runId || event.runId === runId);
+    });
+    return { from: new Date(from).toISOString(), to: new Date(to).toISOString(), ...summarizeUsageEvents(events), errors: history.errors };
+}

package/dist/observability/usage.js

@@ -0,0 +1,19 @@
+/** 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',
+        usageMissingFields: ['inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningOutputTokens', 'totalCostUsd'].filter(field => typeof known[field] !== 'number'),
+        usagePartialFields: Object.keys(telemetry.partialUsage ?? {}).filter(field => typeof telemetry.tokens?.[field] !== 'number' && typeof known[field] === '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,8 +16,24 @@ 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 SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
+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),
+    sourceIdentity: z.object({ path: z.string().regex(/^\/(?!\/)/).max(4096), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).optional(),
+});
 const OutputPolicySchema = z.object({
     previewBytes: z.number().int().positive().optional(),
     artifactThresholdBytes: z.number().int().positive().optional(),
@@ -56,6 +72,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 +126,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(),