@hecer/yoke 1.22.0 → 1.23.0

package/dist/loop/parallel-command.js

@@ -1,3 +1,4 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
 import { existsSync, rmSync } from 'node:fs';
 import { observeFailure, clearFailureProgress } from './failure.js';
 import { acceptanceProtectionProblem } from '../check/command.js';
@@ -15,11 +16,23 @@ import { runStoryWorker } from './worker.js';
 import { acquireSharedWorker, sharedPoolStatus } from './resource-pool.js';
 import { providerTelemetryUsage } from '../observability/usage.js';
 export async function runParallelLoopCommand(input) {
-    const originalVerify = input.verify;
+    const originalVerify = input.verify, originalCriterion = input.verifyCriterion;
+    const cacheProblem = (path) => !input.git && path !== input.targetDir ? cacheIsolationProblem(path) : undefined;
     input = { ...input, verify: path => {
-            const problem = acceptanceProtectionProblem(path, input.targetDir);
+            const problem = cacheProblem(path) ?? acceptanceProtectionProblem(path, input.targetDir);
             return problem ? { passed: false, summary: problem } : originalVerify(path);
+        }, verifyCriterion: (path, story, criterion) => {
+            const problem = cacheProblem(path);
+            return problem ? { passed: false, summary: problem } : originalCriterion(path, story, criterion);
         } };
+    for (const name of ['design', 'perf', 'audit']) {
+        const gate = input[name];
+        if (gate)
+            input = { ...input, [name]: (path) => {
+                    const problem = cacheProblem(path);
+                    return problem ? { passed: false, summary: problem } : gate(path);
+                } };
+    }
     const adapters = makeParallelAdapters(input.targetDir, input.identity, input.git);
     if (!adapters.git.isClean(input.targetDir)) {
         input.reporter.blocked('target working tree is not clean');
@@ -137,6 +150,8 @@ export async function runParallelLoopCommand(input) {
             const gate = input.completion(input.targetDir);
             if (!gate.passed)
                 reason = `integrated system did not verify: ${gate.summary}`;
+            else if (!adapters.git.isClean(input.targetDir))
+                reason = 'completion command left source or final assets dirty; preserve changes and move rerun proofs to ignored runtime paths before resuming';
         }
         catch (error) {
             reason = `integrated completion gate failed: ${error instanceof Error ? error.message : String(error)}`;

package/dist/loop/proof-retention.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { workspaceFingerprint } from '../workspace/fingerprint.js';
+import { storyPathSegment } from './prd.js';
+const hash = (data) => createHash('sha256').update(data).digest('hex');
+function safePath(root, path) {
+    const rel = relative(resolve(root), resolve(path));
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\'))
+        throw new Error('Proof path escaped workspace');
+    let current = root;
+    for (const segment of rel.split(/[\\/]/u).filter(Boolean)) {
+        current = join(current, segment);
+        try {
+            if (lstatSync(current).isSymbolicLink())
+                throw new Error(`Proof path must not contain a link: ${current}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+/** Copy selected proof into an immutable runtime snapshot; errors preserve the candidate. */
+export function retainRuntimeProof(directory, storyId, targetDirectory) {
+    const entries = [];
+    const walk = (dir, base, prefix = '') => {
+        safePath(directory, dir);
+        if (!existsSync(dir))
+            return;
+        for (const name of readdirSync(dir).sort()) {
+            const file = join(dir, name);
+            safePath(directory, file);
+            const stat = lstatSync(file);
+            if (stat.isDirectory())
+                walk(file, base, prefix);
+            else if (stat.isFile()) {
+                const bytes = readFileSync(file);
+                entries.push({ path: (prefix + relative(base, file)).replace(/\\/gu, '/'), sha256: hash(bytes), bytes });
+            }
+            else
+                throw new Error(`Unsupported proof entry: ${file}`);
+        }
+    };
+    const artifacts = join(directory, '.yoke/artifacts'), proof = join(directory, '.yoke/proof');
+    walk(artifacts, artifacts);
+    walk(proof, proof, 'proof/');
+    if (!entries.length)
+        return;
+    const config = ['config.yaml', 'acceptance.yaml', 'prd.yaml'].map(name => {
+        const path = join(directory, '.yoke', name);
+        safePath(directory, path);
+        return [name, existsSync(path) ? hash(readFileSync(path)) : 'missing'];
+    });
+    const manifest = JSON.stringify({ version: 1, source: workspaceFingerprint(directory), config: hash(JSON.stringify(config)), environment: hash(JSON.stringify({ platform: process.platform, arch: process.arch, versions: process.versions })), files: entries.map(({ path, sha256 }) => ({ path, sha256 })) }, null, 2) + '\n';
+    const destination = join(targetDirectory, '.yoke/proof', storyPathSegment(storyId), 'runtime-artifacts', hash(manifest));
+    for (const { path, sha256, bytes } of [...entries, { path: 'manifest.json', sha256: hash(manifest), bytes: Buffer.from(manifest) }]) {
+        const copied = join(destination, path);
+        safePath(targetDirectory, copied);
+        mkdirSync(dirname(copied), { recursive: true });
+        if (existsSync(copied)) {
+            if (hash(readFileSync(copied)) !== sha256)
+                throw new Error(`Retained proof hash mismatch: ${path}`);
+        }
+        else
+            writeFileSync(copied, bytes, { mode: 0o600, flag: 'wx' });
+        if (hash(readFileSync(copied)) !== sha256)
+            throw new Error(`Proof copy hash mismatch: ${path}`);
+    }
+}

package/dist/loop/reporter.js

@@ -335,7 +335,7 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
                 return;
             }
             const { integrator: _integrator, ...withoutIntegrator } = parallel;
-            persist({ ...base, parallel: withoutIntegrator, updatedAt: now().toISOString() }, 'parallel-integrator', '  · integration complete');
+            persist({ ...base, parallel: withoutIntegrator, updatedAt: now().toISOString() }, 'parallel-integrator', '  · integrator idle');
         },
         addTokens(usage) {
             if (![usage.inputTokens, usage.outputTokens].every(value => Number.isFinite(value) && value >= 0))

package/dist/loop/run-command.js

@@ -76,7 +76,12 @@ export function loopStatus(targetDir, now = () => new Date(), opts) {
     if (opts?.compact) {
         if (!st)
             return `state=${enabled ? 'enabled' : 'disabled'} prd="${prog}"`;
-        return `state=${st.state} story=${st.story ?? 'none'} progress=${st.progress.passed}/${st.progress.total} phase=${st.phase} updated=${relativeTime(st.updatedAt, now())}`;
+        const workers = [...(st.parallel?.workers ?? [])].sort((a, b) => a.story.localeCompare(b.story));
+        const work = (worker) => `${encodeURIComponent(worker.story)}:${worker.phase ?? 'working'}`;
+        const integrator = st.parallel?.integrator;
+        const story = st.story ?? integrator?.story ?? workers[0]?.story ?? 'none';
+        const parallel = st.parallel ? ` workers=${workers.map(work).join(',') || 'none'} integrator=${integrator ? work(integrator) : 'none'} waiting=${st.parallel.waitingWorkers ?? 0} queued=${st.parallel.queuedIntegrations ?? st.parallel.queuedCandidates}` : '';
+        return `state=${st.state} story=${encodeURIComponent(story)} progress=${st.progress.passed}/${st.progress.total} phase=${st.phase ?? (st.parallel ? 'parallel' : st.state)}${parallel} updated=${relativeTime(st.updatedAt, now())}`;
     }
     const sharedPoolLine = () => {
         try {

package/dist/loop/runner.js

@@ -32,7 +32,7 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfC
     ];
     if (context)
         lines.push('', context);
-    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, ...(story.assessment ? ['Planner approach:', story.assessment.approach] : []), '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, ...(story.assessment ? ['Planner approach:', story.assessment.approach] : []), '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Use worktree-local writable dependency/runtime caches. Do not link node_modules to a target checkout when tools write .vite-temp or other caches there. Shared package download caches are allowed; preserve the configured sandbox. Report offline cache misses and network failures explicitly instead of blindly retrying.', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
         ? '- If an acceptance criterion is genuinely undecidable, do NOT guess: write the open question(s) to .yoke/ambiguity.md, change nothing else, and stop.'
         : onAmbiguity === 'critical'
             ? [

package/dist/loop/worker.js

@@ -1,3 +1,4 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
 import { knownInfrastructureFailure } from "../routing/capability.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -44,6 +45,9 @@ function reviewOutcome(result) {
 }
 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)
@@ -317,6 +321,9 @@ async function runWorkerImplementation(input, context, evidence) {
     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 };
         if (["decision-request.yaml", "ambiguity.md", "loop.pause"].some(name => existsSync(join(context.targetDir, ".yoke", name))) || acceptanceProtectionProblem(context.targetDir))

package/dist/observability/history.js

@@ -31,6 +31,7 @@ export function archiveMeasurement(root, event) {
     }
     const data = event.data ?? {};
     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/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

@@ -13,5 +13,7 @@ export function providerTelemetryUsage(telemetry) {
         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/retrofit/config.js

@@ -31,7 +31,9 @@ const SmokeStepSchema = z.discriminatedUnion('action', [
         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 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(),

package/dist/retrofit/gitignore.js

@@ -1,6 +1,8 @@
 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/',
@@ -42,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/router.js

@@ -114,6 +114,8 @@ function callUsage(role, provider, selection, tokens, durationMs, profile) {
         ...(selection.reasoningEffort ? { requestedReasoningEffort: selection.reasoningEffort } : {}),
         ...(selection.variant ? { requestedVariant: selection.variant } : {}),
         ...(tokens?.model ? { actualModel: tokens.model } : {}),
+        usageMissingFields: tokens?.usageMissingFields ?? (!tokens ? ['inputTokens', 'outputTokens', 'cachedInputTokens', 'reasoningOutputTokens', 'totalCostUsd'] : []),
+        ...(tokens?.usagePartialFields ? { usagePartialFields: tokens.usagePartialFields } : {}),
         inputTokens: tokens?.inputTokens ?? 0,
         ...(tokens?.cachedInputTokens !== undefined ? { cachedInputTokens: tokens.cachedInputTokens } : {}),
         ...(tokens?.cacheWriteInputTokens !== undefined ? { cacheWriteInputTokens: tokens.cacheWriteInputTokens } : {}),

package/dist/smoke/command.js

@@ -16,21 +16,36 @@ const CONFIG_GUIDANCE = [
     '      landmark: "main h1"',
 ].join('\n');
 export async function launchPlaywright(targetDir) {
+    const req = createRequire(join(resolve(targetDir), 'package.json'));
     try {
-        // createRequire needs an absolute anchor — a relative targetDir (the CLI
-        // default '.') would throw and masquerade as "playwright not found".
-        // Playwright is CJS, so load it with native require() rather than a
-        // file:// dynamic import — the URL round-trip breaks under Windows 8.3
-        // short paths (e.g. RUNNER~1 on CI) and test-runner import interception.
-        const req = createRequire(join(resolve(targetDir), 'package.json'));
-        const pw = req('playwright');
-        const chromium = pw.chromium ?? pw.default?.chromium;
-        if (!chromium)
+        req.resolve('playwright');
+    }
+    catch (error) {
+        if (error.code === 'MODULE_NOT_FOUND')
             return null;
+        throw Object.assign(new Error(`Playwright resolution failed: ${String(error)}`, { cause: error }), { code: 'browser-package-failed' });
+    }
+    // Native CJS loading also preserves Windows short-path compatibility.
+    let chromium;
+    try {
+        const pw = req('playwright');
+        chromium = pw.chromium ?? pw.default?.chromium;
+    }
+    catch (error) {
+        throw Object.assign(new Error(`Playwright package could not load: ${String(error)}`, { cause: error }), { code: 'browser-package-failed' });
+    }
+    if (!chromium)
+        throw Object.assign(new Error('Installed Playwright package has no chromium export'), { code: 'browser-export-missing' });
+    try {
         return await chromium.launch({ headless: true, timeout: 30_000 });
     }
-    catch {
-        return null;
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = /executable doesn't exist|executable does not exist/i.test(detail) ? 'browser-binary-missing'
+            : /no usable sandbox|running as root without --no-sandbox/i.test(detail) ? 'browser-sandbox-failed'
+                : /\bEPERM\b|\bEACCES\b|permission denied|operation not permitted/i.test(detail) ? 'browser-permission-denied'
+                    : 'browser-launch-failed';
+        throw Object.assign(new Error(detail, { cause: error }), { code });
     }
 }
 // Flow names come from user config and become filenames — keep them safe.
@@ -44,6 +59,32 @@ export function safeLabel(label) {
     const cleaned = label.replace(/[^\w-]+/g, '-').replace(/^-+|-+$/g, '');
     return cleaned || 'latest';
 }
+async function verifyServedSource(baseUrl, identity) {
+    const origin = new URL(baseUrl);
+    const url = new URL(identity.path, origin);
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== origin.origin)
+        return false;
+    const response = await fetch(url, { signal: AbortSignal.timeout(5000), redirect: 'error' });
+    if (!response.ok || !response.body)
+        return false;
+    const reader = response.body.getReader(), hash = createHash('sha256');
+    let bytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > 1024 * 1024)
+                return false;
+            hash.update(value);
+        }
+        return hash.digest('hex') === identity.sha256;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
 class SmokeFailure extends Error {
     code;
     constructor(code) {
@@ -271,12 +312,33 @@ export async function runFlowSmoke(targetDir, opts = {}) {
     const configDigest = createHash('sha256').update(JSON.stringify({ smoke, baseUrl, resolvedFillValues: [...fillValues.values()] })).digest('hex');
     const redact = (text) => [...fillValues.values()].filter((value) => !!value).sort((a, b) => b.length - a.length).reduce((current, value) => current.split(value).join('[redacted]'), text);
     const launch = opts.launch ?? launchPlaywright;
+    if (!opts.launch && !smoke.sourceIdentity) {
+        console.error('Smoke sourceIdentity is required for a production browser run: configure a served path and expected SHA-256 for this source build; previous evidence was preserved.');
+        return 2;
+    }
+    if (smoke.sourceIdentity) {
+        let matched = false;
+        try {
+            matched = await verifyServedSource(baseUrl, smoke.sourceIdentity);
+        }
+        catch { /* Unavailable identity cannot pass. */ }
+        if (!matched) {
+            console.error('Smoke served-source identity could not be verified; previous evidence was preserved.');
+            return 2;
+        }
+    }
     let browser;
     try {
         browser = await bounded(() => launch(targetDir), 30_000);
     }
-    catch {
-        console.error('Smoke browser could not start; previous evidence was preserved.');
+    catch (error) {
+        const rawCode = error?.code;
+        const code = typeof rawCode === 'string' && ['browser-package-failed', 'browser-export-missing', 'browser-binary-missing', 'browser-sandbox-failed', 'browser-permission-denied'].includes(rawCode) ? rawCode : 'browser-launch-failed';
+        const detail = redact(error instanceof Error ? error.message : String(error))
+            .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[redacted]@')
+            .replace(/\b((?:access_|refresh_|id_)?token|password|secret|api[_-]?key)=([^\s&]+)/gi, '$1=[redacted]')
+            .replace(/\b(authorization\s*:\s*(?:bearer|basic)\s+)[^\s,;]+/gi, '$1[redacted]');
+        console.error(`Smoke browser could not start (${code}): ${detail.slice(0, 2000)}; previous evidence was preserved.`);
         return 2;
     }
     if (!browser) {
@@ -311,6 +373,7 @@ export async function runFlowSmoke(targetDir, opts = {}) {
     }
     catch { /* Optional runtime metadata. */ }
     const report = {
+        serverIdentity: smoke.sourceIdentity ? 'verified' : 'unverified',
         version: 1, startedAt: new Date(started).toISOString(), generatedAt: '', durationMs: 0, status: 'failed',
         sourceFingerprint, afterSourceFingerprint: null, sourceStable: false, configDigest,
         environment: { platform: process.platform, architecture: process.arch, nodeVersion: process.version, driver: opts.launch ? 'injected' : 'playwright-chromium', ...(browserVersion ? { browserVersion } : {}), baseOrigin: redact(baseOrigin), viewport: { width: 1280, height: 720 } },
@@ -348,6 +411,17 @@ export async function runFlowSmoke(targetDir, opts = {}) {
         report.afterSourceFingerprint = workspaceFingerprint(targetDir);
     }
     catch { /* Missing identity prevents a pass. */ }
+    if (smoke.sourceIdentity) {
+        let matched = false;
+        try {
+            matched = await verifyServedSource(baseUrl, smoke.sourceIdentity);
+        }
+        catch { /* Fail closed. */ }
+        if (!matched) {
+            report.serverIdentity = 'failed';
+            report.failure ??= 'server-identity-failed';
+        }
+    }
     report.sourceStable = report.sourceFingerprint === report.afterSourceFingerprint;
     if (!report.sourceStable)
         report.failure ??= 'source-changed-or-unavailable';

package/dist/update/check.js

@@ -69,7 +69,7 @@ export function maybeNotifyUpdate(currentVersion, opts = {}) {
     if (env.YOKE_NO_UPDATE_CHECK || env.CI)
         return;
     const argv = opts.argv ?? process.argv;
-    if (argv.includes('--json'))
+    if (argv.some(arg => ['--json', '--help', '-h'].includes(arg)))
         return;
     const tty = opts.tty ?? process.stderr.isTTY === true;
     if (!tty)

package/docs/DELIVERY-JOURNEYS.md

@@ -2,7 +2,7 @@
 
 Use executable acceptance criteria to decide whether a release is ready. A build command shows that an artifact can be produced; a journey checks a specific user interaction. Yoke can now record the relationship between those criteria, named journeys and the exact artifact files present during a check.
 
-The delivery declaration belongs in `.yoke/acceptance.yaml`. Browser smoke steps belong in `.yoke/config.yaml`. Existing smoke flows containing only `name`, `path` and an optional `landmark` continue to work.
+The delivery declaration belongs in `.yoke/acceptance.yaml`. Browser smoke steps belong in `.yoke/config.yaml`. Existing flow definitions containing only `name`, `path` and an optional `landmark` remain valid, but production browser runs now also require `smoke.sourceIdentity`.
 
 ## Optional browser steps
 
@@ -13,6 +13,9 @@ For example, add this section to the project's existing `.yoke/config.yaml`:
 ```yaml
 smoke:
   baseUrl: http://localhost:3000
+  sourceIdentity:
+    path: /assets/app-specific-static-source.js
+    sha256: "<replace with SHA-256 of the served bytes>"
   flows:
     - name: profile-survives-reload
       path: /login
@@ -51,6 +54,10 @@ smoke:
           exact: true
 ```
 
+Replace the source resource path and hash placeholder before running this example. Confirm the intended server's checkout/build and port, then fetch a stable, app-specific source resource from the effective `baseUrl` origin and calculate the SHA-256 of the exact served body bytes. Dev servers may transform local source, so hashing a local file alone is insufficient. Set `sha256` to the resulting 64-character lowercase hexadecimal digest. The resource must return a successful HTTP response without redirects, finish within five seconds and contain at most 1 MiB. It must remain stable through the run. Production smoke checks the pin before browser launch and again after the flows; a missing or mismatching pin prevents valid smoke evidence.
+
+After an intentional source/build change, verify the server serves that change and explicitly refresh the pin. Do not update it automatically on a mismatch or accept a foreign process occupying the expected port. Choose a resource that changes with the relevant app source, rather than a shared health response or an unchanged marker. The static pin checks only that resource's bytes before and after the run; it does not independently prove the identity of every module, backend or dynamic response. Source fingerprints and other acceptance checks remain necessary.
+
 Supply `SMOKE_TEST_PASSWORD` through the environment using credentials for a dedicated test account, then run:
 
 ```sh