@hecer/yoke 1.14.0 → 1.15.1

package/dist/code-intelligence/edit-plans.js

@@ -0,0 +1,53 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function storeDir(root) { return join(root, '.yoke', 'code-intelligence', 'plans'); }
+function planHashInput(plan) {
+    return { workspace_id: plan.workspace_id, snapshot_id: plan.snapshot_id, root: plan.root, sandbox_root: plan.sandbox_root, operations: plan.operations, validation_profile: plan.validation_profile, changedPaths: plan.changed_paths, validation: plan.validation, expiresAt: plan.expires_at, diffHash: plan.diff_hash, sandboxHash: plan.sandbox_hash };
+}
+export function createEditPlan(root, snapshot, sandboxRoot, operations, validation, validationProfile, changedPaths, diff, ttlMs = 30 * 60_000) {
+    const planId = `plan-${randomUUID()}`;
+    const diffUri = join(storeDir(root), `${planId}.diff`);
+    const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+    const diffHash = hash(diff);
+    const sandboxHash = hash(changedPaths.map(path => [path, existsSync(join(sandboxRoot, path)) ? readFileSync(join(sandboxRoot, path)).toString('base64') : null]));
+    const base = { workspace_id: snapshot.workspace_id, snapshot_id: snapshot.snapshot_id, root, sandbox_root: sandboxRoot, operations, validation_profile: validationProfile, changedPaths, validation, expiresAt, diffHash, sandboxHash };
+    const planHash = hash(base);
+    const plan = {
+        plan_id: planId, plan_hash: planHash, diff_uri: diffUri, changed_paths: changedPaths, validation, approval_required: true, expires_at: expiresAt,
+        workspace_id: snapshot.workspace_id, snapshot_id: snapshot.snapshot_id, root, sandbox_root: sandboxRoot, operations, validation_profile: validationProfile, created_at: new Date().toISOString(), diff_hash: diffHash, sandbox_hash: sandboxHash,
+    };
+    mkdirSync(storeDir(root), { recursive: true });
+    writeFileSync(diffUri, diff, { mode: 0o600 });
+    writeFileSync(join(storeDir(root), `${planId}.json`), JSON.stringify(plan, null, 2) + '\n', { mode: 0o600 });
+    return plan;
+}
+export function loadEditPlan(root, planId) {
+    const file = join(storeDir(root), `${planId}.json`);
+    if (!existsSync(file))
+        throw new Error(`unknown edit plan: ${planId}`);
+    const plan = JSON.parse(readFileSync(file, 'utf8'));
+    if (plan.plan_hash !== hash(planHashInput(plan)))
+        throw new Error('edit plan integrity check failed');
+    return plan;
+}
+/** This is deliberately separate from the MCP apply tool. The loop/control layer
+ * calls it only after human/policy approval has been recorded. */
+export function approveEditPlan(root, planId) {
+    const plan = loadEditPlan(root, planId);
+    mkdirSync(storeDir(root), { recursive: true });
+    writeFileSync(join(storeDir(root), `${planId}.approval.json`), JSON.stringify({ plan_id: planId, plan_hash: plan.plan_hash, approved_at: new Date().toISOString(), authority: 'yoke-control' }) + '\n', { mode: 0o600 });
+}
+export function readPlanApproval(root, plan) {
+    const file = join(storeDir(root), `${plan.plan_id}.approval.json`);
+    if (!existsSync(file))
+        return false;
+    try {
+        const approval = JSON.parse(readFileSync(file, 'utf8'));
+        return approval.plan_hash === plan.plan_hash && approval.authority === 'yoke-control';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/code-intelligence/evidence.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { assertSafePath } from './snapshots.js';
+function hash(value) { return createHash('sha256').update(value).digest('hex'); }
+function textOf(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    try {
+        return JSON.stringify(raw) ?? '';
+    }
+    catch {
+        return String(raw);
+    }
+}
+function locate(text, root) {
+    const match = /(?:^|[\s("'`])((?:[A-Za-z0-9_.@-]+[\\/])*[A-Za-z0-9_.@-]+\.[A-Za-z0-9]+):(\d+)/u.exec(text);
+    if (!match)
+        return { path: null, line: null };
+    try {
+        return { path: assertSafePath(root, match[1]), line: Number(match[2]) };
+    }
+    catch {
+        return { path: null, line: null };
+    }
+}
+export function makeProvenance(options, text, resolution = 'resolved') {
+    const location = locate(text, options.root);
+    const file = location.path ? options.snapshot.files.find(item => item.path === location.path) : undefined;
+    return {
+        backend: options.adapter.name, version: options.adapter.version, source_path: location.path, content_hash: file?.hash ?? null,
+        byte_range: null, origin: options.origin ?? (options.adapter.semantic ? 'lsp' : 'parser'), resolution, freshness: 'current',
+    };
+}
+export function evidenceId(provenance, excerpt) {
+    return `evidence-${hash(JSON.stringify({ provenance, excerpt })).slice(0, 24)}`;
+}
+export function normalizeItems(raw, options, kind = 'code', limit = 100) {
+    const full = textOf(raw);
+    const chunks = Array.isArray(raw) ? raw : (raw && typeof raw === 'object' && Array.isArray(raw.results) ? raw.results : [raw]);
+    const provenance = [];
+    const items = [];
+    const maxChars = options.maxChars ?? 12000;
+    for (const candidate of chunks.slice(0, limit)) {
+        const excerpt = textOf(candidate).slice(0, maxChars);
+        if (!excerpt)
+            continue;
+        const p = makeProvenance(options, excerpt, excerpt.toLowerCase().includes('ambiguous') ? 'ambiguous' : 'resolved');
+        const id = evidenceId(p, excerpt);
+        provenance.push(p);
+        items.push({ item_id: `item-${hash(excerpt).slice(0, 24)}`, kind, path: p.source_path, excerpt, evidence_ids: [id], rank: items.length });
+    }
+    if (items.length === 0 && full) {
+        const excerpt = full.slice(0, maxChars);
+        const p = makeProvenance(options, excerpt, 'unresolved');
+        const id = evidenceId(p, excerpt);
+        provenance.push(p);
+        items.push({ item_id: `item-${hash(excerpt).slice(0, 24)}`, kind, path: p.source_path, excerpt, evidence_ids: [id], rank: 0 });
+    }
+    return { items, provenance };
+}
+export function normalizeSymbols(raw, options) {
+    const normalized = normalizeItems(raw, options, 'symbol');
+    const candidates = Array.isArray(raw) ? raw : (raw && typeof raw === 'object' && Array.isArray(raw.results) ? raw.results : []);
+    const symbols = normalized.items.map((item, index) => {
+        const candidate = candidates[index] && typeof candidates[index] === 'object' ? candidates[index] : {};
+        const namePath = String(candidate.name_path ?? candidate.namePath ?? candidate.name ?? item.excerpt.split(/\s|\(|\{/u)[0] ?? 'unknown');
+        const path = typeof candidate.relative_path === 'string' ? candidate.relative_path : item.path;
+        const stableId = `serena:${encodeURIComponent(JSON.stringify({ name_path: namePath, relative_path: path ?? '' }))}`;
+        return { symbol_id: stableId, name: String(candidate.name ?? namePath.split('/').at(-1) ?? namePath), path, kind: String(candidate.kind ?? 'unknown'), signature: item.excerpt.slice(0, 500), evidence_ids: item.evidence_ids };
+    });
+    return { symbols, references: [], diagnostics: [], provenance: normalized.provenance };
+}
+export function normalizeEdges(raw, options, relation) {
+    const normalized = normalizeItems(raw, options, 'code');
+    const nodes = normalized.items.map(item => ({ id: item.item_id, label: item.excerpt.slice(0, 160), path: item.path, evidence_ids: item.evidence_ids }));
+    const edges = nodes.slice(1).map((node, index) => ({ from: nodes[index].id, to: node.id, relation, evidence_ids: node.evidence_ids }));
+    return { nodes, edges, provenance: normalized.provenance };
+}

package/dist/code-intelligence/index.js

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './coordinator.js';
+export * from './edit-plans.js';
+export * from './snapshots.js';
+export * from './transactions.js';

package/dist/code-intelligence/internal-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process';
+/** Small, bounded stdio MCP client. It supports Graft's newline JSON-RPC and the
+ * Content-Length framing used by the Python MCP SDK (Graphify and Serena). */
+export class McpStdioClient {
+    command;
+    args;
+    cwd;
+    framing;
+    maxBytes;
+    child;
+    buffer = Buffer.alloc(0);
+    pending = new Map();
+    nextId = 1;
+    stderrBytes = 0;
+    constructor(command, args, cwd, framing = 'content-length', maxBytes = 2_000_000) {
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.framing = framing;
+        this.maxBytes = maxBytes;
+    }
+    async call(tool, arguments_, timeoutMs) {
+        await this.start(timeoutMs);
+        return this.request('tools/call', { name: tool, arguments: arguments_ }, timeoutMs);
+    }
+    async close() {
+        if (!this.child)
+            return;
+        const child = this.child;
+        this.child = undefined;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('MCP process closed'));
+        }
+        this.pending.clear();
+        child.kill('SIGTERM');
+        await new Promise(resolve => {
+            const timer = setTimeout(() => { if (!child.killed)
+                child.kill('SIGKILL'); resolve(); }, 500);
+            child.once('close', () => { clearTimeout(timer); resolve(); });
+        });
+    }
+    async start(timeoutMs) {
+        if (this.child)
+            return;
+        const child = spawn(this.command, this.args, { cwd: this.cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, NO_COLOR: '1' } });
+        this.child = child;
+        child.stdout.on('data', chunk => this.consume(Buffer.from(chunk)));
+        child.stderr.on('data', chunk => { this.stderrBytes += Buffer.byteLength(chunk); if (this.stderrBytes > this.maxBytes)
+            void this.close(); });
+        child.on('error', error => this.fail(new Error(`MCP backend failed to start: ${error.message}`)));
+        child.on('close', (code, signal) => { if (this.child === child)
+            this.child = undefined; this.fail(new Error(`MCP backend exited (${code ?? 'null'}${signal ? `, ${signal}` : ''})`)); });
+        await this.request('initialize', { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'yoke-code-intelligence', version: '0.1.0' } }, timeoutMs);
+        await this.notify('notifications/initialized', {});
+    }
+    notify(method, params) {
+        const payload = JSON.stringify({ jsonrpc: '2.0', method, params });
+        this.write(payload);
+        return Promise.resolve();
+    }
+    request(method, params, timeoutMs) {
+        if (!this.child)
+            return Promise.reject(new Error('MCP process is not running'));
+        const id = this.nextId++;
+        this.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`MCP request timed out: ${method}`)); void this.close(); }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+    }
+    write(payload) {
+        if (!this.child?.stdin.writable)
+            throw new Error('MCP stdin is closed');
+        if (this.framing === 'line')
+            this.child.stdin.write(`${payload}\n`);
+        else
+            this.child.stdin.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+    }
+    consume(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        if (this.buffer.byteLength > this.maxBytes) {
+            void this.close();
+            return;
+        }
+        while (this.buffer.byteLength > 0) {
+            if (this.framing === 'line') {
+                const newline = this.buffer.indexOf(10);
+                if (newline < 0)
+                    return;
+                const line = this.buffer.subarray(0, newline).toString('utf8').trim();
+                this.buffer = this.buffer.subarray(newline + 1);
+                if (line)
+                    this.accept(line);
+                continue;
+            }
+            const headerEnd = this.buffer.indexOf('\r\n\r\n');
+            if (headerEnd < 0)
+                return;
+            const header = this.buffer.subarray(0, headerEnd).toString('ascii');
+            const match = /Content-Length:\s*(\d+)/i.exec(header);
+            if (!match) {
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const length = Number(match[1]);
+            const start = headerEnd + 4;
+            if (this.buffer.byteLength < start + length)
+                return;
+            const body = this.buffer.subarray(start, start + length).toString('utf8');
+            this.buffer = this.buffer.subarray(start + length);
+            this.accept(body);
+        }
+    }
+    accept(raw) {
+        try {
+            const message = JSON.parse(raw);
+            if (typeof message.id !== 'number')
+                return;
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error)
+                pending.reject(new Error(message.error.message ?? 'MCP request failed'));
+            else
+                pending.resolve(message.result);
+        }
+        catch { /* backend log/noise on stdout is ignored; protocol errors surface by timeout */ }
+    }
+    fail(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}

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

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { CodeIntelligenceCoordinator } from './coordinator.js';
+import { TOOL_DEFINITIONS } from './contracts.js';
+import { loadConfig } from '../retrofit/config.js';
+const INPUT_SCHEMAS = {
+    code_context: { type: 'object', required: ['workspace_id', 'query'], properties: { workspace_id: { type: 'string' }, query: { type: 'string' }, snapshot_id: { type: 'string' }, mode: { type: 'string', enum: ['orient', 'locate', 'explain'] }, paths: { type: 'array', items: { type: 'string' } }, include_docs: { type: 'boolean' }, token_budget: { type: 'integer' }, timeout_ms: { type: 'integer' } } },
+    code_symbol: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, query: { type: 'string' }, path: { type: 'string' }, include: { type: 'array' } } },
+    code_trace: { type: 'object', required: ['workspace_id', 'snapshot_id', 'symbol_id', 'direction', 'relations'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, direction: { type: 'string', enum: ['in', 'out'] }, relations: { type: 'array' }, max_depth: { type: 'integer' }, max_nodes: { type: 'integer' } } },
+    code_impact: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, targets: { type: 'array' }, plan_id: { type: 'string' }, include_docs: { type: 'boolean' }, require_semantic: { type: 'boolean' } } },
+    code_edit_preview: { type: 'object', required: ['workspace_id', 'snapshot_id', 'operations', 'validation_profile'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, operations: { type: 'array' }, validation_profile: { type: 'string', enum: ['default', 'extended'] } } },
+    code_edit_apply: { type: 'object', required: ['workspace_id', 'plan_id', 'expected_snapshot_id', 'idempotency_key'], properties: { workspace_id: { type: 'string' }, plan_id: { type: 'string' }, expected_snapshot_id: { type: 'string' }, idempotency_key: { type: 'string' } } },
+};
+function arg(name, args) { return args.find(value => value.startsWith(`--${name}=`))?.slice(name.length + 3); }
+function summary(response) { return `status=${response.status} snapshot=${response.snapshot_id} warnings=${response.warnings.length} (full result in structuredContent)`; }
+export async function runCodeIntelligenceServer(argv = process.argv.slice(2)) {
+    const workspace = arg('workspace', argv) ?? process.cwd();
+    const configured = loadConfig(workspace)?.codeIntelligence;
+    const mode = arg('mode', argv) ?? configured?.mode ?? 'active';
+    const coordinator = new CodeIntelligenceCoordinator(workspace, {
+        mode,
+        policy: { excludePatterns: configured?.policy?.excludePatterns, maxFileBytes: configured?.policy?.maxFileBytes },
+        limits: { maxBytes: configured?.limits?.maxBytes, maxBackends: configured?.limits?.maxBackends },
+        graft: configured?.graft, graphify: configured?.graphify, serena: configured?.serena,
+    });
+    let framing = 'line';
+    let buffer = Buffer.alloc(0);
+    const send = (message) => {
+        const payload = JSON.stringify(message);
+        if (framing === 'line')
+            process.stdout.write(`${payload}\n`);
+        else
+            process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+    };
+    const handle = async (message) => {
+        if (message.method === 'notifications/initialized' || message.method?.startsWith('notifications/'))
+            return;
+        if (message.method === 'initialize') {
+            send({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2025-11-25', capabilities: { tools: {} }, serverInfo: { name: 'yoke-code-intelligence', version: '0.1.0' } } });
+            return;
+        }
+        if (message.method === 'tools/list') {
+            send({ jsonrpc: '2.0', id: message.id, result: { tools: TOOL_DEFINITIONS.map(tool => ({ ...tool, inputSchema: INPUT_SCHEMAS[tool.name] })) } });
+            return;
+        }
+        if (message.method === 'tools/call') {
+            const name = message.params?.name;
+            const response = await coordinator.dispatch(name, message.params?.arguments ?? {});
+            send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: summary(response) }], structuredContent: response, isError: response.status === 'error' || response.status === 'blocked' } });
+            return;
+        }
+        if (message.id !== undefined)
+            send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `method not found: ${message.method}` } });
+    };
+    process.stdin.on('data', chunk => {
+        buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+        while (buffer.length) {
+            let raw;
+            if (/^Content-Length:/i.test(buffer.toString('ascii', 0, Math.min(buffer.length, 32)))) {
+                framing = 'content-length';
+                const end = buffer.indexOf('\r\n\r\n');
+                if (end < 0)
+                    return;
+                const header = buffer.subarray(0, end).toString('ascii');
+                const match = /Content-Length:\s*(\d+)/i.exec(header);
+                if (!match) {
+                    buffer = buffer.subarray(end + 4);
+                    continue;
+                }
+                const length = Number(match[1]);
+                if (buffer.length < end + 4 + length)
+                    return;
+                raw = buffer.subarray(end + 4, end + 4 + length).toString('utf8');
+                buffer = buffer.subarray(end + 4 + length);
+            }
+            else {
+                const end = buffer.indexOf(10);
+                if (end < 0)
+                    return;
+                raw = buffer.subarray(0, end).toString('utf8').trim();
+                buffer = buffer.subarray(end + 1);
+            }
+            if (!raw)
+                continue;
+            try {
+                void handle(JSON.parse(raw));
+            }
+            catch { /* malformed protocol input is ignored */ }
+        }
+    });
+    await new Promise(resolve => { const stop = () => { process.off('SIGTERM', stop); process.off('SIGINT', stop); void coordinator.close().finally(resolve); }; process.once('SIGTERM', stop); process.once('SIGINT', stop); process.stdin.once('end', stop); });
+}
+if (process.argv[1]?.endsWith('code-intelligence-server.js'))
+    void runCodeIntelligenceServer();

package/dist/code-intelligence/snapshots.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+export const SnapshotFileSchema = z.object({ path: z.string().min(1), hash: z.string().length(64), size: z.number().int().nonnegative() });
+export const SnapshotSchema = z.object({
+    snapshot_id: z.string().length(64), workspace_id: z.string().min(1), root: z.string().min(1), head: z.string().nullable(),
+    files: z.array(SnapshotFileSchema), policy_hash: z.string().length(64), created_at: z.string(),
+});
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*').replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+}
+function excluded(path, policy) {
+    const standard = [/^\.git(?:\/|$)/, /^\.yoke\/code-intelligence(?:\/|$)/, /(^|\/)\.env(?:\.|$)/, /\.(?:pem|key|p12|pfx)$/i];
+    if (standard.some(re => re.test(path)))
+        return true;
+    return (policy.excludePatterns ?? []).some(pattern => globToRegExp(pattern).test(path));
+}
+function safeFile(root, rel, policy) {
+    const normalized = rel.replaceAll('\\', '/');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').some(part => part === '..') || excluded(normalized, policy))
+        return null;
+    const absolute = resolve(root, normalized);
+    if (!inside(root, absolute) || !existsSync(absolute))
+        return null;
+    const stat = lstatSync(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink() || (policy.maxFileBytes && stat.size > policy.maxFileBytes))
+        return null;
+    return { path: normalized, bytes: readFileSync(absolute) };
+}
+function fallbackFiles(root, dir = root, output = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === '.yoke' || entry.name === 'node_modules')
+            continue;
+        const absolute = join(dir, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink())
+            fallbackFiles(root, absolute, output);
+        else if (entry.isFile())
+            output.push(relative(root, absolute).replaceAll('\\', '/'));
+    }
+    return output;
+}
+function trackedAndUntracked(root) {
+    try {
+        const result = execFileSync('git', ['-C', root, 'ls-files', '-co', '--exclude-standard', '-z'], { encoding: 'buffer', stdio: ['ignore', 'pipe', 'ignore'] });
+        return result.toString('utf8').split('\0').filter(Boolean);
+    }
+    catch {
+        return fallbackFiles(root);
+    }
+}
+function head(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function workspaceId(workspaceRoot) {
+    return `workspace-${sha256(realpathSync(resolve(workspaceRoot))).slice(0, 24)}`;
+}
+export function assertSafePath(workspaceRoot, candidate, policy = {}) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const absolute = resolve(root, candidate);
+    const rel = relative(root, absolute).replaceAll('\\', '/');
+    if (!inside(root, absolute) || rel === '' || excluded(rel, policy))
+        throw new Error(`path is outside the permitted workspace: ${candidate}`);
+    try {
+        if (lstatSync(absolute).isSymbolicLink())
+            throw new Error(`symbolic links are not allowed: ${candidate}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return rel;
+}
+export function createSnapshot(workspaceRoot, policy = {}, workspace = workspaceId(workspaceRoot)) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const files = trackedAndUntracked(root).map(path => safeFile(root, path, policy)).filter((value) => value !== null)
+        .sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: sha256(file.bytes), size: file.bytes.byteLength }));
+    const policyHash = sha256(JSON.stringify({ excludePatterns: policy.excludePatterns ?? [], maxFileBytes: policy.maxFileBytes ?? null }));
+    const identity = JSON.stringify({ workspace, root, head: head(root), files, policyHash });
+    const snapshot = SnapshotSchema.parse({ snapshot_id: sha256(identity), workspace_id: workspace, root, head: head(root), files, policy_hash: policyHash, created_at: new Date().toISOString() });
+    const dir = join(root, '.yoke', 'code-intelligence', 'snapshots');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${snapshot.snapshot_id}.json`), JSON.stringify(snapshot, null, 2) + '\n', { mode: 0o600 });
+    return snapshot;
+}
+export function loadSnapshot(workspaceRoot, snapshotId) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const file = join(root, '.yoke', 'code-intelligence', 'snapshots', `${snapshotId}.json`);
+    if (!existsSync(file))
+        throw new Error(`unknown snapshot: ${snapshotId}`);
+    const snapshot = SnapshotSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+    if (snapshot.root !== root)
+        throw new Error('snapshot belongs to another workspace');
+    return snapshot;
+}
+export function currentSnapshotMatches(workspaceRoot, snapshot, policy = {}) {
+    const current = createSnapshot(workspaceRoot, policy, snapshot.workspace_id);
+    return current.snapshot_id === snapshot.snapshot_id;
+}
+export function assertSnapshotCurrent(workspaceRoot, snapshot, policy = {}) {
+    if (!currentSnapshotMatches(workspaceRoot, snapshot, policy))
+        throw new Error('snapshot is stale; create a new snapshot before continuing');
+}

package/dist/code-intelligence/transactions.js

@@ -0,0 +1,60 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assertSnapshotCurrent } from './snapshots.js';
+import { readPlanApproval } from './edit-plans.js';
+function transactionDir(root) { return join(root, '.yoke', 'code-intelligence', 'transactions'); }
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+export function applyEditPlan(root, plan, snapshot, idempotencyKey) {
+    if (plan.expires_at <= new Date().toISOString())
+        throw new Error('edit plan has expired');
+    if (!readPlanApproval(root, plan))
+        throw new Error('edit plan requires Yoke control approval');
+    assertSnapshotCurrent(root, snapshot);
+    if (!existsSync(plan.diff_uri) || hash(readFileSync(plan.diff_uri, 'utf8')) !== plan.diff_hash)
+        throw new Error('edit plan diff has changed');
+    const sandboxHash = hash(plan.changed_paths.map(path => [path, existsSync(join(plan.sandbox_root, path)) ? readFileSync(join(plan.sandbox_root, path)).toString('base64') : null]));
+    if (sandboxHash !== plan.sandbox_hash)
+        throw new Error('edit plan sandbox has changed');
+    const dir = transactionDir(root);
+    mkdirSync(dir, { recursive: true });
+    const idem = join(dir, `${idempotencyKey}.json`);
+    if (existsSync(idem)) {
+        const prior = JSON.parse(readFileSync(idem, 'utf8'));
+        if (prior.plan_id !== plan.plan_id)
+            throw new Error('idempotency key is bound to another plan');
+        return prior;
+    }
+    const lock = join(dir, '.write.lock');
+    let handle;
+    try {
+        handle = openSync(lock, 'wx');
+    }
+    catch {
+        throw new Error('another code-intelligence transaction is active');
+    }
+    try {
+        const transactionId = `tx-${randomUUID()}`;
+        const worktree = join(root, '.yoke', 'code-intelligence', 'worktrees', transactionId);
+        mkdirSync(worktree, { recursive: true });
+        for (const path of plan.changed_paths) {
+            const source = join(plan.sandbox_root, path);
+            const target = join(worktree, path);
+            if (!existsSync(source))
+                continue;
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+        }
+        const result = { transaction_id: transactionId, plan_id: plan.plan_id, changed_paths: plan.changed_paths, worktree, new_snapshot_id: snapshot.snapshot_id, validation: plan.validation, committed: false, merged: false };
+        writeFileSync(idem, JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });
+        return result;
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/estimation/schedule.js

@@ -10,32 +10,46 @@ export function estimateSchedule(stories, maxConcurrency, history) {
     if (!estimate)
         return { available: false, reason: 'No measured duration history' };
     const ranks = criticalPathRanks(stories);
-    const pending = stories.filter(story => !story.passes).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0) || (ranks.get(b.id) ?? 0) - (ranks.get(a.id) ?? 0) || a.id.localeCompare(b.id));
-    const complete = new Set(stories.filter(story => story.passes).map(story => story.id));
-    const active = [];
-    const tasks = [];
-    let time = 0;
-    while (pending.length || active.length) {
-        for (let index = 0; index < pending.length && active.length < maxConcurrency;) {
-            const story = pending[index];
-            if ((story.needs ?? []).every(id => complete.has(id)) && (!story.area || !active.some(item => item.story.area === story.area)) && !active.some(item => writeScopesOverlap(story.writes, item.story.writes))) {
-                const duration = estimateDurations(history.filter(item => item.storyId === story.id).map(item => item.ms)) ?? estimate;
-                const end = time + duration.typicalMs;
-                active.push({ story, end });
-                tasks.push({ storyId: story.id, startMs: time, endMs: end });
-                pending.splice(index, 1);
+    const durations = new Map(stories.filter(story => !story.passes).map(story => [story.id,
+        estimateDurations(history.filter(item => item.storyId === story.id).map(item => item.ms)) ?? estimate,
+    ]));
+    const simulate = (field) => {
+        const pending = stories.filter(story => !story.passes).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0) || (ranks.get(b.id) ?? 0) - (ranks.get(a.id) ?? 0) || a.id.localeCompare(b.id));
+        const complete = new Set(stories.filter(story => story.passes).map(story => story.id));
+        const active = [];
+        const tasks = [];
+        let time = 0;
+        while (pending.length || active.length) {
+            for (let index = 0; index < pending.length && active.length < maxConcurrency;) {
+                const story = pending[index];
+                if ((story.needs ?? []).every(id => complete.has(id)) && (!story.area || !active.some(item => item.story.area === story.area)) && !active.some(item => writeScopesOverlap(story.writes, item.story.writes))) {
+                    const end = time + durations.get(story.id)[field];
+                    active.push({ story, end });
+                    tasks.push({ storyId: story.id, startMs: time, endMs: end });
+                    pending.splice(index, 1);
+                }
+                else
+                    index++;
             }
-            else
-                index++;
+            if (!active.length)
+                return undefined;
+            time = Math.min(...active.map(item => item.end));
+            for (let index = active.length - 1; index >= 0; index--)
+                if (active[index].end === time) {
+                    complete.add(active[index].story.id);
+                    active.splice(index, 1);
+                }
         }
-        if (!active.length)
-            return { available: false, reason: 'Cyclic or missing dependencies' };
-        time = Math.min(...active.map(item => item.end));
-        for (let index = active.length - 1; index >= 0; index--)
-            if (active[index].end === time) {
-                complete.add(active[index].story.id);
-                active.splice(index, 1);
-            }
-    }
-    return { available: true, etaMs: time, lowerMs: time * estimate.lowerMs / estimate.typicalMs, upperMs: time * estimate.upperMs / estimate.typicalMs, sampleCount: estimate.sampleCount, confidence: estimate.confidence, tasks };
+        return { time, tasks };
+    };
+    const typical = simulate('typicalMs'), lower = simulate('lowerMs'), upper = simulate('upperMs');
+    if (!typical || !lower || !upper)
+        return { available: false, reason: 'Cyclic or missing dependencies' };
+    // Different durations can change a greedy schedule's ordering. Keep the
+    // empirical scenario envelope ordered; this is not a calibrated interval.
+    return { available: true, etaMs: typical.time,
+        lowerMs: Math.min(lower.time, typical.time, upper.time), upperMs: Math.max(lower.time, typical.time, upper.time),
+        sampleCount: estimate.sampleCount,
+        confidence: [...durations.values()].some(duration => duration.confidence === 'low') ? 'low' : estimate.confidence,
+        tasks: typical.tasks };
 }

package/dist/retrofit/command.js

@@ -17,7 +17,8 @@ export function runRetrofit(targetDir, opts) {
         : (detection.agents.length > 0 ? detection.agents : [opts.host ?? detectHostAgent() ?? 'claude']);
     const existing = loadConfig(targetDir);
     const codeGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
-    const actions = planRetrofit(canonDir, targetDir, agents, codeGraph);
+    const codeIntelligence = opts.codeIntelligence ?? existing?.codeIntelligence?.mode ?? 'off';
+    const actions = planRetrofit(canonDir, targetDir, agents, codeGraph, codeIntelligence);
     const backupDir = join(targetDir, '.yoke', 'backup', String(Date.now()));
     const applied = applyActions(actions, targetDir, { backupDir });
     // Ensure runtime artifacts (loop status/log, worktrees, backups) are gitignored
@@ -31,6 +32,7 @@ export function runRetrofit(targetDir, opts) {
         agents: mergedAgents,
         loop: { ...existing?.loop, enabled: opts.loop },
         codeGraph,
+        codeIntelligence: { ...(existing?.codeIntelligence ?? {}), mode: codeIntelligence },
         ...(existing?.design
             ? { design: existing.design }
             : detection.ui.detected ? { design: { mode: 'auto', max: 4 } } : {}),