@hecer/yoke 1.20.0 → 1.22.0

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';
@@ -17,7 +17,7 @@ import { runNew } from './new/command.js';
 import { runPrdDraft, runPrdCheck } from './prd/command.js';
 import { runPrdAssess } from './prd/assess.js';
 import { runPrdDecompose } from './prd/decompose.js';
-import { runLoopCleanup } from './loop/cleanup.js';
+import { runLoopCleanup, pruneWorktrees, pruneFleetWorktrees, listWorktrees, listFleetWorktrees } from './loop/cleanup.js';
 import { runFlowSmoke } from './smoke/command.js';
 import { maybeNotifyUpdate, currentYokeVersion } from './update/check.js';
 import { runUpgrade } from './update/upgrade.js';
@@ -62,6 +62,22 @@ export function runDesignScan(targetDir, opts) {
     console.log(`${label} — ✓`);
     return 0;
 }
+export function parseKeyValueFlags(args, flagName) {
+    const result = {};
+    for (const arg of args) {
+        if (arg.startsWith(`--${flagName}=`)) {
+            const raw = arg.slice(flagName.length + 3);
+            const eqIdx = raw.indexOf(':');
+            if (eqIdx > 0) {
+                const key = raw.slice(0, eqIdx).trim();
+                const val = raw.slice(eqIdx + 1).trim();
+                if (key && val)
+                    result[key] = val;
+            }
+        }
+    }
+    return result;
+}
 export function parseQualityFlags(args) {
     const quality = args.includes('--quality') ? true : args.includes('--no-quality') ? false : undefined;
     const qualityUnbounded = args.includes('--quality-unbounded') || undefined;
@@ -185,9 +201,16 @@ export function main(argv) {
                 console.error('Invalid --model-provider (expected deepseek,kimi)');
                 return 1;
             }
+            const runnerModel = rest.find(a => a.startsWith('--runner-model='))?.slice('--runner-model='.length);
+            const runnerReasoning = rest.find(a => a.startsWith('--runner-reasoning='))?.slice('--runner-reasoning='.length);
+            const agentModels = parseKeyValueFlags(rest, 'model');
+            const agentReasoning = parseKeyValueFlags(rest, 'reasoning');
+            const cleanWorktrees = rest.includes('--clean-worktrees');
             return runSetup(targetDir, {
                 modelProviders: modelProviders,
                 host: hostArg, agents, runner: runnerArg,
+                runnerModel, runnerReasoning, agentModels, agentReasoning, cleanWorktrees,
+                configureModels: rest.includes('--configure-models'),
                 codeGraph: graphArg,
                 codeIntelligence: intelligenceArg,
                 loop, routing, decisionPolicy: policyArg,
@@ -218,6 +241,47 @@ export function main(argv) {
                 return 2;
             }
         }
+        case 'worktrees': {
+            const sub = rest[0] ?? 'list';
+            const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            const all = rest.includes('--all');
+            const force = rest.includes('--force');
+            if (sub === 'list') {
+                if (all) {
+                    const fleet = listFleetWorktrees();
+                    for (const [name, list] of Object.entries(fleet)) {
+                        console.log(`[${name}] ${list.length} worktree(s):`);
+                        for (const wt of list)
+                            console.log(`  ${wt}`);
+                    }
+                    return 0;
+                }
+                const list = listWorktrees(targetDir);
+                console.log(`Worktrees in ${targetDir} (${list.length}):`);
+                for (const wt of list)
+                    console.log(`  ${wt}`);
+                return 0;
+            }
+            if (sub === 'prune') {
+                if (all) {
+                    const fleet = pruneFleetWorktrees({ force });
+                    let totalRemoved = 0;
+                    for (const [name, res] of Object.entries(fleet)) {
+                        if (res.removed.length > 0 || res.failed.length > 0) {
+                            console.log(`[${name}] Removed: ${res.removed.length}, Failed: ${res.failed.length}`);
+                            totalRemoved += res.removed.length;
+                        }
+                    }
+                    console.log(`Fleet prune complete: ${totalRemoved} worktree(s) removed.`);
+                    return 0;
+                }
+                const res = pruneWorktrees(targetDir, { force });
+                console.log(`Pruned ${res.removed.length} worktree(s) in ${targetDir}${res.failed.length > 0 ? ` (${res.failed.length} failed)` : ''}.`);
+                return res.failed.length === 0 ? 0 : 1;
+            }
+            console.log('usage: yoke worktrees <list|prune> [dir] [--all] [--force]');
+            return 1;
+        }
         case 'dashboard': {
             const port = rest.find(a => a.startsWith('--port='))?.slice('--port='.length);
             if (port !== undefined && (!Number.isInteger(Number(port)) || Number(port) < 0 || Number(port) > 65535)) {
@@ -275,6 +339,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))
@@ -284,7 +357,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}`);
@@ -319,6 +392,11 @@ export function main(argv) {
         case 'retrofit': {
             const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
             const loop = rest.includes('--loop');
+            const cleanWorktrees = rest.includes('--clean-worktrees');
+            const runnerModel = rest.find(a => a.startsWith('--runner-model='))?.slice('--runner-model='.length);
+            const runnerReasoning = rest.find(a => a.startsWith('--runner-reasoning='))?.slice('--runner-reasoning='.length);
+            const agentModels = parseKeyValueFlags(rest, 'model');
+            const agentReasoning = parseKeyValueFlags(rest, 'reasoning');
             const agentArg = rest.find(a => a.startsWith('--agent='))?.slice('--agent='.length);
             const all = [...SUPPORTED_AGENTS];
             const agents = !agentArg || agentArg === 'all'
@@ -338,7 +416,7 @@ export function main(argv) {
                 console.error(`Invalid --code-intelligence value: ${ciArg} (expected off|shadow|active)`);
                 return 1;
             }
-            return runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence: ciArg });
+            return runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence: ciArg, cleanWorktrees, runnerModel, runnerReasoning, agentModels, agentReasoning });
         }
         case 'change': {
             const sub = rest[0];
@@ -387,7 +465,7 @@ export function main(argv) {
                 return 0;
             }
             if (sub === 'status') {
-                console.log(loopStatus(targetDir));
+                console.log(loopStatus(targetDir, undefined, { compact: rest.includes('--compact') }));
                 return 0;
             }
             if (sub === 'pause') {
@@ -618,7 +696,7 @@ export function main(argv) {
                 }
                 return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, resumeWorktree: rest.includes('--resume-worktree'), parallel, parallelAuto: parallelArg === '--parallel=auto', reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions, ...(explore ? { explore: true } : {}), ...(exploreIntervalMinutes !== undefined ? { exploreIntervalMinutes } : {}), ...(exploreLimit.milliseconds !== undefined ? { exploreLimitMs: exploreLimit.milliseconds } : {}), ...qualityFlags.options });
             }
-            console.log(`usage: yoke loop <on|off|status|pause|decision|answer|resume [--discard] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--parallel=<auto|N>] [--runner=<${AGENT_LIST}>] [--reviewer=<${AGENT_LIST}>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate|--no-isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]`);
+            console.log(`usage: yoke loop <on|off|status [--compact]|pause|decision|answer|resume [--discard] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--parallel=<auto|N>] [--runner=<${AGENT_LIST}>] [--reviewer=<${AGENT_LIST}>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate|--no-isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]`);
             return 1;
         }
         case 'new': {
@@ -763,8 +841,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(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--loop] | 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>`);
+            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/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({