@hecer/yoke 1.21.1 → 1.23.0

package/dist/check/command.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parse } from 'yaml';
@@ -15,10 +15,17 @@ import { writeOutputArtifact } from '../output/artifact.js';
 import { DEFAULT_OUTPUT_POLICY } from '../output/types.js';
 import { createProviderProcessRecord, filesystemProviderProcessRecordAdapter } from '../agents/process-record.js';
 import { trackProcessRecordIdentity } from '../agents/process-record-identity.js';
+import { DeliverySchema, startDelivery, finishDelivery } from './delivery.js';
 const Criterion = z.object({ id: z.string().min(1).max(120), text: z.string().min(1).max(8000), commands: z.array(z.string().min(1).max(8000)).max(30) }).strict();
-const Acceptance = z.object({ version: z.literal(1), criteria: z.array(Criterion).max(200), protected: z.array(z.string().min(1)).max(500).default([]) }).strict().superRefine((value, ctx) => {
+const Acceptance = z.object({ version: z.literal(1), criteria: z.array(Criterion).max(200), protected: z.array(z.string().min(1)).max(500).default([]), delivery: DeliverySchema.optional() }).strict().superRefine((value, ctx) => {
     if (new Set(value.criteria.map(c => c.id)).size !== value.criteria.length)
         ctx.addIssue({ code: 'custom', message: 'Duplicate acceptance criterion id' });
+    const ids = new Set(value.criteria.map(criterion => criterion.id));
+    for (const item of [...(value.delivery?.artifacts ?? []), ...(value.delivery?.journeys ?? [])]) {
+        for (const id of item.criteria)
+            if (!ids.has(id))
+                ctx.addIssue({ code: 'custom', path: ['delivery'], message: `Delivery references unknown criterion: ${id}` });
+    }
 });
 export async function checkProjectAsync(directory, options = {}) {
     const controller = new AbortController();
@@ -162,8 +169,36 @@ function verifyCommandAsync(command, root, signal) {
     });
 }
 export function loadAcceptance(root) {
+    return loadAcceptanceSnapshot(root).manifest;
+}
+/** Hash the exact bounded bytes that were parsed; never reread an untrusted path for the digest. */
+function loadAcceptanceSnapshot(root) {
     const file = statePath(root, 'acceptance.yaml');
-    return existsSync(file) ? Acceptance.parse(parse(readFileSync(file, 'utf8'))) : null;
+    if (!existsSync(file))
+        return { manifest: null, digest: null };
+    const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const before = fstatSync(fd);
+        if (!before.isFile() || before.size > 64 * 1024 * 1024)
+            throw Error('Acceptance must be a regular file of at most 64 MiB');
+        const bytes = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const count = readSync(fd, bytes, length, bytes.length - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        const after = fstatSync(fd), named = lstatSync(statePath(root, 'acceptance.yaml'));
+        if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs ||
+            named.ino !== before.ino || named.dev !== before.dev || named.size !== before.size || named.mtimeMs !== before.mtimeMs || named.ctimeMs !== before.ctimeMs)
+            throw Error('Acceptance changed while loading');
+        const content = bytes.subarray(0, length);
+        return { manifest: Acceptance.parse(parse(content.toString('utf8'))), digest: createHash('sha256').update(content).digest('hex') };
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 function protectedPath(root, path) {
     if (isAbsolute(path))
@@ -209,17 +244,41 @@ export function acceptanceProtectionProblem(root, baselineRoot = root) {
         return `Protected acceptance cannot be verified: ${error.message}`;
     }
 }
+function finalizeDelivery(root, manifest, start, fingerprint, criteria, options = {}) {
+    let changed = false;
+    const delivery = finishDelivery(root, manifest, start, fingerprint, criteria, { ...options, checkIntegrity: () => {
+            let problem = null;
+            try {
+                changed = workspaceFingerprint(root) !== fingerprint;
+            }
+            catch (error) {
+                changed = true;
+                problem = `Checked source cannot be verified: ${error.message}`;
+            }
+            problem = problem ?? acceptanceProtectionProblem(root) ?? (changed ? 'Source changed during verification; run check again on a stable tree' : null);
+            if (problem)
+                criteria.push({ id: 'source-integrity', text: 'Checked source remained stable', commands: [], status: 'failed', summary: problem });
+            if (options.signal?.aborted || (options.deadline !== undefined && Date.now() >= options.deadline)) {
+                const cancelled = 'Verification cancelled or deadline reached';
+                criteria.push({ id: 'verification-cancelled', text: 'Verification completed within its allowed run', commands: [], status: 'failed', summary: cancelled });
+                problem = problem ?? cancelled;
+            }
+            return problem;
+        } });
+    return { delivery, changed };
+}
 export function checkProject(directory, options = {}) {
     const root = realpathSync(directory);
     const started = Date.now();
     const before = workspaceFingerprint(root);
     const problem = acceptanceProtectionProblem(root);
+    const { manifest, digest } = problem ? { manifest: null, digest: null } : loadAcceptanceSnapshot(root);
+    const deliveryStart = startDelivery(root, manifest, digest);
     const criteria = [];
     const execute = options.execute ?? ((command, cwd) => commandVerifier(command, { phase: 'verify' })(cwd));
     if (problem)
         criteria.push({ id: 'protected-acceptance', text: 'Acceptance infrastructure unchanged', commands: [], status: 'failed', summary: problem });
     else {
-        const manifest = loadAcceptance(root);
         for (const criterion of manifest?.criteria ?? []) {
             const results = criterion.commands.map(command => {
                 try {
@@ -247,14 +306,11 @@ export function checkProject(directory, options = {}) {
         if (criteria.length === 0)
             criteria.push({ id: 'acceptance', text: 'Project acceptance', commands: [], status: 'unverified', summary: 'No acceptance manifest or project verification command found' });
     }
-    const changed = workspaceFingerprint(root) !== before;
-    const afterProblem = acceptanceProtectionProblem(root);
-    if (changed || afterProblem)
-        criteria.push({ id: 'source-integrity', text: 'Checked source remained stable', commands: [], status: 'failed', summary: afterProblem ?? 'Source changed during verification; run check again on a stable tree' });
+    const { changed, delivery } = finalizeDelivery(root, manifest, deliveryStart, before, criteria);
     const status = criteria.some(c => c.status === 'failed') ? 'failed' : criteria.some(c => c.status === 'unverified') ? 'unverified' : 'passed';
     const id = randomUUID();
     const evidencePath = statePath(root, 'checks', `${id}.json`);
-    const report = { version: 1, id, generatedAt: new Date().toISOString(), fingerprint: before, status, summary: changed ? 'Source changed during verification' : `${criteria.filter(c => c.status === 'passed').length}/${criteria.length} checks passed; ${status}`, criteria, durationMs: Date.now() - started, evidencePath };
+    const report = { version: 1, id, generatedAt: new Date().toISOString(), fingerprint: before, status, summary: changed ? 'Source changed during verification' : `${criteria.filter(c => c.status === 'passed').length}/${criteria.length} checks passed; ${status}`, criteria, delivery, durationMs: Date.now() - started, evidencePath };
     mkdirSync(dirname(evidencePath), { recursive: true });
     writeFileSync(evidencePath, JSON.stringify(report, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
     return report;
@@ -265,6 +321,8 @@ async function checkProjectAsyncAdmitted(directory, options) {
     const started = Date.now();
     const before = workspaceFingerprint(root);
     const problem = acceptanceProtectionProblem(root);
+    const { manifest, digest } = problem ? { manifest: null, digest: null } : loadAcceptanceSnapshot(root);
+    const deliveryStart = startDelivery(root, manifest, digest, options);
     const criteria = [];
     let cleanupUnconfirmed = false;
     const rawExecute = options.execute ?? ((command, cwd) => verifyCommandAsync(command, cwd, options.signal));
@@ -281,7 +339,6 @@ async function checkProjectAsyncAdmitted(directory, options) {
     if (problem)
         criteria.push({ id: 'protected-acceptance', text: 'Acceptance infrastructure unchanged', commands: [], status: 'failed', summary: problem });
     else {
-        const manifest = loadAcceptance(root);
         for (const criterion of manifest?.criteria ?? []) {
             const results = [];
             for (const command of criterion.commands) {
@@ -316,16 +373,11 @@ async function checkProjectAsyncAdmitted(directory, options) {
         if (criteria.length === 0)
             criteria.push({ id: 'acceptance', text: 'Project acceptance', commands: [], status: 'unverified', summary: 'No acceptance manifest or project verification command found' });
     }
-    const changed = workspaceFingerprint(root) !== before;
-    const afterProblem = acceptanceProtectionProblem(root);
-    if (changed || afterProblem)
-        criteria.push({ id: 'source-integrity', text: 'Checked source remained stable', commands: [], status: 'failed', summary: afterProblem ?? 'Source changed during verification; run check again on a stable tree' });
-    if (options.signal?.aborted)
-        criteria.push({ id: 'verification-cancelled', text: 'Verification completed within its allowed run', commands: [], status: 'failed', summary: 'Verification cancelled or deadline reached' });
+    const { changed, delivery } = finalizeDelivery(root, manifest, deliveryStart, before, criteria, options);
     const status = criteria.some(c => c.status === 'failed') ? 'failed' : criteria.some(c => c.status === 'unverified') ? 'unverified' : 'passed';
     const id = randomUUID();
     const evidencePath = statePath(root, 'checks', `${id}.json`);
-    const report = { ...(cleanupUnconfirmed ? { cleanupUnconfirmed: true } : {}), version: 1, id, generatedAt: new Date().toISOString(), fingerprint: before, status, summary: changed ? 'Source changed during verification' : `${criteria.filter(c => c.status === 'passed').length}/${criteria.length} checks passed; ${status}`, criteria, durationMs: Date.now() - started, evidencePath };
+    const report = { ...(cleanupUnconfirmed ? { cleanupUnconfirmed: true } : {}), version: 1, id, generatedAt: new Date().toISOString(), fingerprint: before, status, summary: changed ? 'Source changed during verification' : `${criteria.filter(c => c.status === 'passed').length}/${criteria.length} checks passed; ${status}`, criteria, delivery, durationMs: Date.now() - started, evidencePath };
     mkdirSync(dirname(evidencePath), { recursive: true });
     writeFileSync(evidencePath, JSON.stringify(report, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
     return report;

package/dist/check/delivery.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+const References = z.array(z.string().min(1).max(120)).min(1).max(200);
+export const DeliverySchema = z.object({
+    version: z.literal(1),
+    artifacts: z.array(z.object({ path: z.string().min(1).max(1000), criteria: References }).strict()).max(32).default([]),
+    journeys: z.array(z.object({ id: z.string().min(1).max(120), text: z.string().min(1).max(8000), criteria: References }).strict()).max(100).default([]),
+    environment: z.object({ name: z.string().min(1).max(200), url: z.string().url().max(2000).optional() }).strict().optional(),
+}).strict().superRefine((value, context) => {
+    if (new Set(value.artifacts.map(item => item.path)).size !== value.artifacts.length)
+        context.addIssue({ code: 'custom', message: 'Duplicate delivery artifact path' });
+    if (new Set(value.journeys.map(item => item.id)).size !== value.journeys.length)
+        context.addIssue({ code: 'custom', message: 'Duplicate delivery journey id' });
+});
+export const DELIVERY_HASH_LIMITS = Object.freeze({ fileBytes: 512 * 1024 * 1024, totalBytes: 1024 * 1024 * 1024, timeoutMs: 10_000 });
+function snapshotBudget(options) {
+    return { signal: options.signal, remaining: DELIVERY_HASH_LIMITS.totalBytes, deadline: Math.min(options.deadline ?? Infinity, Date.now() + DELIVERY_HASH_LIMITS.timeoutMs) };
+}
+function checkBudget(budget) {
+    if (budget.signal?.aborted || Date.now() >= budget.deadline)
+        throw Error('Artifact hashing cancelled or deadline reached');
+}
+function artifactPath(root, path) {
+    if (isAbsolute(path))
+        throw Error('Artifact path must be relative');
+    const full = resolve(root, path), rel = relative(root, full);
+    if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw Error('Artifact path escapes project');
+    let current = root;
+    for (const component of rel.split(sep)) {
+        current = join(current, component);
+        if (lstatSync(current).isSymbolicLink())
+            throw Error('Artifact paths must not contain symbolic links');
+    }
+    if (realpathSync(full) !== full)
+        throw Error('Artifact path is not canonical');
+    return full;
+}
+/** Bounded bytes and constant memory; the deadline is checked between synchronous reads. */
+function snapshotArtifact(root, path, budget) {
+    let fd;
+    try {
+        checkBudget(budget);
+        const full = artifactPath(root, path);
+        const named = lstatSync(full);
+        if (!named.isFile())
+            throw Error('Artifact must be a regular file');
+        if (named.size > DELIVERY_HASH_LIMITS.fileBytes)
+            throw Error(`Artifact exceeds the ${DELIVERY_HASH_LIMITS.fileBytes} byte file limit`);
+        if (named.size > budget.remaining)
+            throw Error(`Artifact exceeds the remaining aggregate hash budget (${budget.remaining} bytes)`);
+        fd = openSync(full, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const before = fstatSync(fd);
+        if (!before.isFile() || before.ino !== named.ino || before.dev !== named.dev || before.size !== named.size)
+            throw Error('Artifact changed before hashing');
+        const hash = createHash('sha256'), buffer = Buffer.alloc(256 * 1024);
+        let bytes = 0;
+        while (bytes < before.size) {
+            checkBudget(budget);
+            const count = readSync(fd, buffer, 0, Math.min(buffer.length, before.size - bytes), null);
+            if (!count)
+                break;
+            hash.update(buffer.subarray(0, count));
+            bytes += count;
+            budget.remaining -= count;
+        }
+        checkBudget(budget);
+        const after = fstatSync(fd);
+        const finalNamed = lstatSync(artifactPath(root, path));
+        if (bytes !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs ||
+            !finalNamed.isFile() || finalNamed.ino !== before.ino || finalNamed.dev !== before.dev || finalNamed.size !== before.size || finalNamed.mtimeMs !== before.mtimeMs || finalNamed.ctimeMs !== before.ctimeMs)
+            throw Error('Artifact changed while hashing');
+        return { sha256: hash.digest('hex'), bytes };
+    }
+    catch (error) {
+        return { problem: `Artifact cannot be bound: ${error.message}` };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* Preserve the snapshot failure. */ }
+        }
+    }
+}
+export function startDelivery(root, manifest, acceptanceDigest, options = {}) {
+    const budget = snapshotBudget(options);
+    return { acceptanceDigest, artifacts: (manifest?.delivery?.artifacts ?? []).map(item => snapshotArtifact(root, item.path, budget)) };
+}
+export function finishDelivery(root, manifest, start, fingerprint, criteria, options = {}) {
+    const budget = snapshotBudget(options);
+    const snapshots = (manifest?.delivery?.artifacts ?? []).map((artifact, index) => {
+        const before = start.artifacts[index], after = snapshotArtifact(root, artifact.path, budget);
+        const stable = !!before?.sha256 && before.sha256 === after.sha256;
+        const problem = before?.problem ?? after.problem ?? (!stable ? 'Artifact changed during verification; rebuild and check the stable artifact again' : undefined);
+        if (problem)
+            criteria.push({ id: `delivery-artifact-${index + 1}`, text: `Artifact ${artifact.path} remained stable`, commands: [], status: 'failed', summary: problem });
+        return { artifact, before, after, stable, problem };
+    });
+    // Recheck source and cancellation after the final artifact I/O, before assigning proof status.
+    const bindingProblem = options.checkIntegrity?.() ?? snapshots.find(item => item.problem)?.problem;
+    const statusFor = (ids) => {
+        const statuses = ids.flatMap(id => { const matches = criteria.filter(criterion => criterion.id === id); return matches.length ? matches.map(item => item.status) : ['unverified']; });
+        return statuses.some(status => status === 'failed') ? 'failed' : !bindingProblem && statuses.every(status => status === 'passed') ? 'passed' : 'unverified';
+    };
+    const artifacts = snapshots.map(({ artifact, before, after, stable, problem }) => {
+        return { ...artifact, binding: 'declared-criteria', status: problem ? 'failed' : statusFor(artifact.criteria), stable, sha256: before?.sha256, bytes: before?.bytes, afterSha256: after.sha256, summary: problem ?? bindingProblem ?? 'Artifact hashes matched before and after checking its declared criteria; the project commands define how this artifact is exercised' };
+    });
+    const requirements = manifest?.criteria.map(item => item.id) ?? [];
+    return {
+        version: 1, sourceFingerprint: fingerprint, acceptanceDigest: start.acceptanceDigest, ...(bindingProblem ? { bindingProblem } : {}),
+        environment: { platform: process.platform, architecture: process.arch, nodeVersion: process.version, declared: manifest?.delivery?.environment },
+        artifacts, journeys: (manifest?.delivery?.journeys ?? []).map(journey => ({ ...journey, status: statusFor(journey.criteria) })),
+        passedRequirementIds: requirements.filter(id => statusFor([id]) === 'passed'),
+        failedRequirementIds: requirements.filter(id => statusFor([id]) === 'failed'),
+        unverifiedRequirementIds: requirements.filter(id => statusFor([id]) === 'unverified'),
+    };
+}

package/dist/cli.js

@@ -5,7 +5,7 @@ import { realpathSync } from 'node:fs';
 import { checkProject, checkExitCode, protectAcceptance } from './check/command.js';
 import { registerProject, listProjects, unregisterProject } from './dashboard/registry.js';
 import { startDashboard } from './dashboard/server.js';
-import { createProjectGoal, readProjectGoal, runProjectGoal, pauseProjectGoal, goalHandoff, budgetProjectGoal, bindProjectGoal } from './goals/command.js';
+import { createProjectGoal, readProjectGoal, runProjectGoal, pauseProjectGoal, goalHandoff, budgetProjectGoal, bindProjectGoal, assessProjectGoal } from './goals/command.js';
 import { validateCanon } from './canon/validate.js';
 import { runRetrofit } from './retrofit/command.js';
 import { setLoopEnabled, loopStatus, runLoopCommand } from './loop/run-command.js';
@@ -26,6 +26,8 @@ import { printAudit, runAudit } from './audit/command.js';
 import { runSetup } from './setup/command.js';
 import { runCodeIntelligenceServer } from './code-intelligence/mcp-server.js';
 import { pendingChanges, queueChange } from './change/inbox.js';
+import { localUsageReport } from './observability/local-report.js';
+import { runToolPreflight } from './code-intelligence/preflight.js';
 import { answerPendingDecision, answeredDecisionResumeIsValid, clearDecisionResume, decisionProcessingExists, decisionResumeMatchesCurrent, finalizeCommittedDecisionResume, formatPendingDecision, readDecisionResume, readPendingDecision, writeDecisionResume, } from './loop/decision.js';
 export { runRetrofit } from './retrofit/command.js';
 export function runValidate(canonDir) {
@@ -149,7 +151,83 @@ function parseExploreLimitFlag(args, explore) {
 }
 export function main(argv) {
     const [cmd, ...rest] = argv;
+    // Help must exit before any command can write configuration or start a process.
+    if (argv.includes('--help') || argv.includes('-h'))
+        return main([]);
+    const mutationFlags = {
+        setup: ['--yes', '--host=', '--agent=', '--runner=', '--code-graph=', '--code-intelligence=', '--decision-policy=', '--loop', '--no-loop', '--routing', '--no-routing', '--routing-strategy=', '--model-provider=', '--runner-model=', '--runner-reasoning=', '--model=', '--reasoning=', '--clean-worktrees', '--configure-models', '--routing-preset'],
+        retrofit: ['--loop', '--agent=', '--code-graph=', '--code-intelligence=', '--clean-worktrees', '--runner-model=', '--runner-reasoning=', '--model=', '--reasoning='],
+        context: [],
+        projects: [],
+        worktrees: ['--all', '--force'],
+        dashboard: ['--port=', '--no-register'],
+        goal: ['--objective=', '--attempts=', '--minutes=', '--wall-minutes=', '--tokens=', '--criteria=', '--clear-token-budget', '--runner=', '--model=', '--effort=', '--bare', '--native-goal', '--no-native-goal'],
+        check: ['--json', '--protect', '--refresh', '--requirement='],
+        change: ['--idea='],
+        loop: ['--compact', '--remove-worktrees', '--discard-stale-recovery', '--discard', '--explore', '--explore-interval=', '--explore-limit=', '--quality', '--no-quality', '--quality-rounds=', '--quality-minutes=', '--quality-policy=', '--quality-unbounded', '--candidates=', '--choice=', '--rationale=', '--no-resume', '--max=', '--runner=', '--reviewer=', '--review', '--allow-self-review', '--routing', '--no-routing', '--isolate', '--no-isolate', '--unsafe', '--timeout=', '--decision-policy=', '--parallel=', '--json', '--on-ambiguity=', '--resume-worktree'],
+        new: ['--idea=', '--agent=', '--runner=', '--loop'],
+        prd: ['--idea=', '--runner=', '--story=', '--apply', '--reassess', '--force', '--timeout='],
+        review: ['--reviewer=', '--base=', '--focus=', '--allow-self-review', '--json', '--timeout='],
+        audit: ['--json'],
+        'flow-smoke': ['--url=', '--label='],
+        'design-scan': ['--report', '--max='],
+        usage: ['--json', '--from=', '--to=', '--run='],
+        'tools-preflight': ['--json'],
+    };
+    const accepted = mutationFlags[cmd];
+    if (accepted) {
+        const unknown = rest.find(value => value.startsWith('-') && !accepted.some(flag => flag.endsWith('=') ? value.startsWith(flag) && value.length > flag.length : value === flag));
+        if (unknown) {
+            console.error(`Unknown or incomplete ${cmd} flag: ${unknown}`);
+            return 1;
+        }
+        for (const toggle of ['loop', 'routing', 'isolate', 'native-goal', 'quality']) {
+            if (rest.includes(`--${toggle}`) && rest.includes(`--no-${toggle}`)) {
+                console.error(`Cannot use --${toggle} with --no-${toggle}.`);
+                return 1;
+            }
+        }
+    }
     switch (cmd) {
+        case 'tools-preflight': {
+            return runToolPreflight(rest.find(arg => !arg.startsWith('-')) ?? '.').then(report => {
+                if (rest.includes('--json'))
+                    console.log(JSON.stringify(report));
+                else {
+                    console.log(`RTK: ${report.rtk.status}; native rewrite=${report.rtk.nativeRewrite}; nested code mode=${report.rtk.nestedCodeMode}`);
+                    console.log(`Code intelligence: ${report.codeIntelligence.status}; mode=${report.codeIntelligence.mode}; workspace=${report.codeIntelligence.workspaceId}`);
+                    console.log(`  ${report.rtk.fallback}\n  ${report.codeIntelligence.fallback}; index freshness=${report.codeIntelligence.indexFreshness}`);
+                }
+                return 0;
+            }).catch(error => { console.error(`Tool preflight unavailable: ${error.message}`); return 2; });
+        }
+        case 'usage': {
+            const value = (name) => rest.find(arg => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+            const to = value('to') === undefined ? Date.now() : Date.parse(value('to'));
+            const from = value('from') === undefined ? to - 30 * 86400000 : Date.parse(value('from'));
+            if (!Number.isFinite(from) || !Number.isFinite(to) || from >= to || to - from > 366 * 86400000) {
+                console.error('Invalid usage time range: choose --from/--to dates spanning at most 366 days.');
+                return 2;
+            }
+            try {
+                const report = localUsageReport(rest.find(arg => !arg.startsWith('-')) ?? '.', { from, to, runId: value('run') });
+                if (rest.includes('--json'))
+                    console.log(JSON.stringify(report));
+                else {
+                    console.log(`Usage ${report.from} to ${report.to}: input=${report.total.inputTokens ?? 'unknown'} cache=${report.total.cachedInputTokens ?? 'unknown'} output=${report.total.outputTokens ?? 'unknown'} cost=${report.total.totalCostUsd ?? 'unknown'} (${report.total.coverage}; cost ${report.total.costCoverage})`);
+                    console.log(`Guardian=${report.hostCoverage.guardian} approval=${report.hostCoverage.approval}; phase sum=${report.time.phaseDurationSumMs ?? 'unknown'}ms union=${report.time.phaseDurationUnionMs ?? 'unknown'}ms`);
+                    for (const limit of report.limitations)
+                        console.log(`  ${limit}`);
+                    for (const error of report.errors)
+                        console.error(`Usage history: ${error}`);
+                }
+                return report.errors.length ? 2 : 0;
+            }
+            catch (error) {
+                console.error(`Usage report unavailable: ${error.message}`);
+                return 2;
+            }
+        }
         case 'code-intelligence-server':
             return runCodeIntelligenceServer(rest).then(() => 0).catch(error => { console.error(`Code intelligence server: ${error.message}`); return 2; });
         case 'setup': {
@@ -339,6 +417,15 @@ export function main(argv) {
                     console.log('Pause requested at next safe boundary');
                     return 0;
                 }
+                if (sub === 'assess') {
+                    const provider = value('runner');
+                    if (provider && !SUPPORTED_AGENTS.includes(provider))
+                        throw new Error('Unknown runner');
+                    return assessProjectGoal(targetDir, { provider: provider, selection: { model: value('model'), reasoningEffort: value('effort'), bare: rest.includes('--bare') ? true : undefined } }).then(result => {
+                        console.log(JSON.stringify(result));
+                        return result.assessed ? 0 : 1;
+                    }).catch(error => { console.error(`Goal assessment: ${error.message}`); return 2; });
+                }
                 if (sub === 'run' || sub === 'resume') {
                     const provider = value('runner');
                     if (provider && !SUPPORTED_AGENTS.includes(provider))
@@ -348,7 +435,7 @@ export function main(argv) {
                         return goal.status === 'complete' ? 0 : 1;
                     }).catch(error => { console.error(`Goal: ${error.message}`); return 2; });
                 }
-                throw new Error('Use goal set|bind|status|run|resume|pause|handoff|budget');
+                throw new Error('Use goal set|bind|assess|status|run|resume|pause|handoff|budget');
             }
             catch (error) {
                 console.error(`Goal: ${error.message}`);
@@ -832,7 +919,8 @@ export function main(argv) {
         case 'upgrade':
             return runUpgrade();
         default:
-            console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
+            console.log('Local diagnostics: yoke tools-preflight [dir] [--json] | usage [dir] [--from=ISO] [--to=ISO] [--run=id] [--json]');
+            console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|bind|assess|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
             console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--clean-worktrees] [--runner-model=<model>] [--runner-reasoning=<effort>] [--model=<agent>:<model>] [--reasoning=<agent>:<effort>] [--loop] | worktrees <list|prune> [dir] [--all] [--force] | change <add|status> [dir] | code-intelligence-server --workspace=<dir> --mode=<mode> | prd <draft|check|assess|decompose> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] | design-scan [dir] | flow-smoke [dir] | upgrade>`);
             return cmd ? 1 : 0;
     }

package/dist/code-intelligence/adapters/mcp.js

@@ -54,5 +54,6 @@ export class McpBackendAdapter {
         const tool = this.aliases[request.tool] ?? request.tool;
         return valueFromResult(await this.client.call(tool, request.arguments, timeoutMs));
     }
+    probe(timeoutMs) { return this.client.listTools(timeoutMs); }
     close() { return this.client.close(); }
 }

package/dist/code-intelligence/budgets.js

@@ -0,0 +1,138 @@
+import { shorten } from './evidence.js';
+const TRUNCATED = 'BUDGET_EXCEEDED: result truncated; coverage is partial.';
+/** The provider/tokenizer is unknown to this facade. Count one budget unit per
+ * UTF-8 byte conservatively, including the response's own metrics. This is not
+ * provider-measured token usage. JSON-RPC transport framing is outside this
+ * structuredContent response and is not included. */
+export function measureResponse(response) {
+    response.metrics.token_count_kind = 'estimated';
+    response.metrics.token_count_method = 'utf8_bytes_conservative';
+    for (let i = 0; i < 10; i++) {
+        const bytes = Buffer.byteLength(JSON.stringify(response), 'utf8');
+        if (response.metrics.returned_bytes === bytes && response.metrics.result_tokens === bytes)
+            return response;
+        response.metrics.returned_bytes = bytes;
+        response.metrics.result_tokens = bytes;
+    }
+    return response;
+}
+export function responseByteLimit(limits) {
+    return Math.max(0, Math.floor(Math.min(limits.tokenBudget, limits.maxBytes)));
+}
+/** This fixed-size failure is the only exception when a caller's budget cannot
+ * even represent the required error envelope. It never echoes backend content. */
+export function budgetError(response) {
+    return measureResponse({
+        schema_version: response.schema_version, request_id: shorten(response.request_id, 64), workspace_id: shorten(response.workspace_id, 128), snapshot_id: shorten(response.snapshot_id, 128),
+        status: 'error', data: null,
+        coverage: { backends_requested: [], backends_used: [], backends_missing: [], structural: 'unavailable', semantic: 'unavailable', documents: 'unavailable' },
+        provenance: [], warnings: [], metrics: { latency_ms: response.metrics.latency_ms, result_tokens: 0, token_count_kind: 'estimated', returned_bytes: 0 }, artifact_uri: null,
+        error: { code: 'BUDGET_EXCEEDED', message: 'Budget cannot represent the mandatory response envelope.' },
+    });
+}
+function markPartial(response) {
+    if (response.status === 'success')
+        response.status = 'partial';
+    for (const key of ['structural', 'semantic', 'documents'])
+        if (response.coverage[key] !== 'unavailable')
+            response.coverage[key] = 'partial';
+}
+function usedEvidence(value, ids = new Set()) {
+    if (Array.isArray(value))
+        for (const entry of value)
+            usedEvidence(entry, ids);
+    else if (value && typeof value === 'object')
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === 'evidence_ids' && Array.isArray(entry)) {
+                for (const id of entry)
+                    if (typeof id === 'string')
+                        ids.add(id);
+            }
+            else
+                usedEvidence(entry, ids);
+        }
+    return ids;
+}
+function pruneProvenance(response) {
+    const ids = usedEvidence(response.data);
+    response.provenance = response.provenance.filter(item => item.evidence_id && ids.has(item.evidence_id));
+}
+function shortenLargestText(value) {
+    const fields = [];
+    function visit(node) {
+        if (Array.isArray(node))
+            for (const item of node)
+                visit(item);
+        else if (node && typeof node === 'object')
+            for (const [key, entry] of Object.entries(node)) {
+                if (['excerpt', 'signature', 'message', 'label'].includes(key) && typeof entry === 'string' && entry.length > 64)
+                    fields.push({ object: node, key, value: entry });
+                else if (entry && typeof entry === 'object')
+                    visit(entry);
+            }
+    }
+    visit(value);
+    const field = fields.sort((a, b) => Buffer.byteLength(b.value) - Buffer.byteLength(a.value))[0];
+    if (!field)
+        return false;
+    field.object[field.key] = shorten(field.value, Math.max(63, Math.floor(field.value.length / 2))) + '…';
+    return true;
+}
+function removeResultEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const data = value;
+    // All facade result collections remain arrays; identifiers and operation
+    // receipts stay intact. Never replace typed data with a prose excerpt.
+    const keys = ['items', 'symbols', 'references', 'diagnostics', 'nodes', 'edges', 'semantic_findings', 'structural_candidates', 'documents', 'suggested_test_paths', 'unresolved', 'changed_paths'];
+    const candidates = keys.filter(key => Array.isArray(data[key]) && data[key].length > 0);
+    candidates.sort((a, b) => Buffer.byteLength(JSON.stringify(data[b].at(-1))) - Buffer.byteLength(JSON.stringify(data[a].at(-1))));
+    const key = candidates[0];
+    if (!key)
+        return false;
+    data[key].pop();
+    if (key === 'nodes') {
+        const ids = new Set(data.nodes.map((node) => node.id));
+        data.edges = data.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to));
+        data.frontier_remaining = (data.frontier_remaining ?? 0) + 1;
+        data.traversal_complete = false;
+    }
+    else if (key === 'edges') {
+        data.frontier_remaining = (data.frontier_remaining ?? 0) + 1;
+        data.traversal_complete = false;
+    }
+    return true;
+}
+/** Bound the complete structured response, not just result.data. Retained data
+ * continues to satisfy its shape, and retained evidence links stay resolvable. */
+export function fitResponse(response, limits) {
+    const limit = responseByteLimit(limits);
+    if (measureResponse(response).metrics.returned_bytes <= limit)
+        return response;
+    markPartial(response);
+    response.warnings = [TRUNCATED, ...response.warnings.filter(item => item !== TRUNCATED).map(item => shorten(item, 256))];
+    pruneProvenance(response);
+    while (measureResponse(response).metrics.returned_bytes > limit) {
+        if (shortenLargestText(response.data))
+            continue;
+        if (removeResultEntry(response.data)) {
+            pruneProvenance(response);
+            continue;
+        }
+        if (response.warnings.length > 1) {
+            response.warnings = [TRUNCATED, 'Additional warnings omitted.'];
+            if (measureResponse(response).metrics.returned_bytes <= limit)
+                break;
+            response.warnings = [TRUNCATED];
+            continue;
+        }
+        // A long diagnostic is allowed to shrink, but error codes and rejection
+        // status survive; an exhausted error body becomes the bounded budget error.
+        if (response.error && response.error.message.length > 64) {
+            response.error.message = shorten(response.error.message, 63) + '…';
+            continue;
+        }
+        return budgetError(response);
+    }
+    return response;
+}

package/dist/code-intelligence/contracts.js

@@ -5,6 +5,7 @@ export const StatusSchema = z.enum(['success', 'partial', 'blocked', 'error']);
 export const ResolutionSchema = z.enum(['resolved', 'unresolved', 'ambiguous', 'not_applicable']);
 export const FreshnessSchema = z.enum(['current', 'stale', 'unknown']);
 export const ProvenanceSchema = z.object({
+    evidence_id: z.string().min(1).optional(),
     backend: BackendNameSchema,
     version: z.string().min(1),
     source_path: z.string().nullable(),
@@ -26,6 +27,7 @@ export const MetricsSchema = z.object({
     latency_ms: z.number().nonnegative(),
     result_tokens: z.number().int().nonnegative(),
     token_count_kind: z.enum(['exact', 'estimated']),
+    token_count_method: z.literal('utf8_bytes_conservative').optional(),
     returned_bytes: z.number().int().nonnegative(),
 });
 export const ErrorSchema = z.object({