@hecer/yoke 1.13.0 → 1.15.0

package/dist/dashboard/server.js

@@ -1,6 +1,6 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-import { lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'yaml';
 import { z } from 'zod';
@@ -8,8 +8,14 @@ import { listProjects } from './registry.js';
 import { dashboardPage } from './page.js';
 import { readEvents } from '../observability/events.js';
 import { estimateSchedule } from '../estimation/schedule.js';
-import { pauseProjectGoal } from '../goals/command.js';
-import { parsePeriod, projectAnalytics } from './analytics.js';
+import { pauseProjectGoal, runProjectGoal } from '../goals/command.js';
+import { runLoopCommand } from '../loop/run-command.js';
+import { isPidAlive, readLock } from '../loop/lock.js';
+import { appendEvent } from '../observability/events.js';
+import { queueChange } from '../change/inbox.js';
+import { statePath } from '../workspace/state.js';
+import { parsePeriod, parseRanking, projectAnalytics, projectHistory, workspaceAnalytics } from './analytics.js';
+import { DASHBOARD_LIMITS, DashboardChangePayloadSchema, DashboardControlPayloadSchema, DashboardNotePayloadSchema, DashboardResumePayloadSchema, parseDashboardLimit, } from './contracts.js';
 const text = z.string().max(16000);
 const number = z.number().finite().nonnegative();
 const Goal = z.object({ objective: text, status: z.enum(['active', 'running', 'paused', 'blocked', 'complete']), reason: text.optional(), pendingAttempt: z.object({ provider: text, model: text.optional(), startedAt: text }).optional(), attempts: z.array(z.object({ durationMs: number.optional(), provider: text.optional(), success: z.boolean().optional(), summary: text.optional(), inputTokens: number.optional(), outputTokens: number.optional() })).max(200).default([]) });
@@ -17,8 +23,11 @@ const Status = z.object({ state: text, phase: text.optional(), reason: text.opti
 const Stories = z.array(z.object({ id: text, title: text, passes: z.boolean(), priority: number.optional(), area: text.optional(), writes: z.array(text).optional(), needs: z.array(text).optional() })).max(2000);
 const Check = z.object({ id: text, status: z.enum(['passed', 'failed', 'unverified']), generatedAt: text, summary: text, criteria: z.array(z.object({ id: text, text, status: z.enum(['passed', 'failed', 'unverified']), summary: text })).max(500) });
 const Durations = z.array(z.object({ storyId: text, ms: number.positive() })).max(5000);
-const MAX_FILE = 1_048_576;
+const MAX_FILE = DASHBOARD_LIMITS.fileBytes;
+const activeResumes = new Set();
 function safeFile(root, relative) {
+    if (!relative || relative.startsWith('/') || relative.includes('\\') || relative.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new Error('Unsafe project path');
     let file = root;
     try {
         for (const part of relative.split('/')) {
@@ -39,6 +48,62 @@ function safeFile(root, relative) {
         throw error;
     }
 }
+function requestBody(req, empty = { action: 'pause' }) {
+    const length = req.headers['content-length'];
+    if (typeof length === 'string' && Number.isFinite(Number(length)) && Number(length) > DASHBOARD_LIMITS.requestBytes) {
+        req.resume();
+        return Promise.reject(new Error('Dashboard request body too large'));
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let rejected = false;
+        req.on('data', chunk => {
+            size += Buffer.byteLength(chunk);
+            if (size > DASHBOARD_LIMITS.requestBytes) {
+                rejected = true;
+                req.resume();
+                reject(new Error('Dashboard request body too large'));
+                return;
+            }
+            chunks.push(Buffer.from(chunk));
+        });
+        req.on('end', () => {
+            if (rejected)
+                return;
+            const body = Buffer.concat(chunks).toString('utf8').trim();
+            if (!body) {
+                resolve(empty);
+                return;
+            }
+            try {
+                resolve(JSON.parse(body));
+            }
+            catch {
+                reject(new Error('Invalid dashboard request body'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function writePauseSignal(root) {
+    const directory = statePath(root);
+    const path = statePath(root, 'loop.pause');
+    mkdirSync(directory, { recursive: true });
+    try {
+        writeFileSync(path, 'pause\n', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
+function projectIsRunning(root) {
+    if (activeResumes.has(root))
+        return true;
+    const lock = readLock(root);
+    return Boolean(lock && isPidAlive(lock.pid));
+}
 function snapshot(project, detail) {
     const errors = project.error ? [project.error] : [];
     const read = (file, schema, yaml = false) => {
@@ -75,13 +140,13 @@ function snapshot(project, detail) {
                 errors.push(error.message);
         }
     }
-    return { ...project, goal, status, errors, ...(detail ? { stories, check, events: project.error ? [] : readEvents(project.root, 100), estimate: estimateSchedule(stories, Math.max(1, status?.parallel?.maxConcurrency ?? 1), history) } : {}) };
+    return { ...project, goal, status, errors, ...(detail ? { stories, check, events: project.error ? [] : readEvents(project.root, DASHBOARD_LIMITS.events), estimate: estimateSchedule(stories, Math.max(1, status?.parallel?.maxConcurrency ?? 1), history) } : {}) };
 }
 export async function startDashboard(options = {}) {
     const token = randomBytes(32).toString('hex');
     const nonce = randomBytes(24).toString('base64');
     let origin = '';
-    const server = createServer((req, res) => {
+    const server = createServer(async (req, res) => {
         res.setHeader('Cache-Control', 'no-store');
         res.setHeader('X-Content-Type-Options', 'nosniff');
         res.setHeader('Referrer-Policy', 'no-referrer');
@@ -91,14 +156,19 @@ export async function startDashboard(options = {}) {
             send(403, { error: 'Untrusted request origin' });
             return;
         }
-        let path;
+        let requested;
         try {
-            path = new URL(req.url ?? '/', origin).pathname;
+            requested = new URL(req.url ?? '/', origin);
         }
         catch {
             send(400, { error: 'Invalid URL' });
             return;
         }
+        if (requested.origin !== origin) {
+            send(403, { error: 'Untrusted request origin' });
+            return;
+        }
+        const path = requested.pathname;
         if (req.method === 'POST') {
             const supplied = req.headers['x-yoke-token'];
             if (req.headers.origin !== origin || typeof supplied !== 'string' || Buffer.byteLength(supplied) !== token.length || !timingSafeEqual(Buffer.from(supplied), Buffer.from(token))) {
@@ -121,7 +191,20 @@ export async function startDashboard(options = {}) {
                 send(200, listProjects().map(project => snapshot(project, false)));
                 return;
             }
-            const match = /^\/api\/projects\/([a-f0-9]{32})(\/pause|\/analytics)?$/u.exec(path);
+            if (req.method === 'GET' && path === '/api/workspace/analytics') {
+                let period, sort;
+                try {
+                    period = parsePeriod(requested.searchParams);
+                    sort = parseRanking(requested.searchParams);
+                }
+                catch (error) {
+                    send(400, { error: error.message });
+                    return;
+                }
+                send(200, workspaceAnalytics(listProjects(), period, sort));
+                return;
+            }
+            const match = /^\/api\/projects\/([a-f0-9]{32})(\/pause|\/resume|\/notes|\/changes|\/analytics|\/history|\/events)?$/u.exec(path);
             if (match) {
                 const project = listProjects().find(project => project.id === match[1]);
                 if (!project) {
@@ -135,7 +218,7 @@ export async function startDashboard(options = {}) {
                     }
                     let period;
                     try {
-                        period = parsePeriod(new URL(req.url, origin).searchParams);
+                        period = parsePeriod(requested.searchParams);
                     }
                     catch (error) {
                         send(400, { error: error.message });
@@ -144,18 +227,110 @@ export async function startDashboard(options = {}) {
                     send(200, projectAnalytics(project.root, period));
                     return;
                 }
+                if (req.method === 'GET' && (match[2] === '/history' || match[2] === '/events')) {
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    let period, limit;
+                    try {
+                        period = parsePeriod(requested.searchParams);
+                        limit = parseDashboardLimit(requested.searchParams.get('limit'));
+                    }
+                    catch (error) {
+                        send(400, { error: error.message });
+                        return;
+                    }
+                    send(200, projectHistory(project.root, period, limit));
+                    return;
+                }
                 if (req.method === 'GET' && !match[2]) {
                     send(200, snapshot(project, true));
                     return;
                 }
                 if (req.method === 'POST' && match[2] === '/pause') {
-                    if (project.error || !snapshot(project, false).goal) {
-                        send(409, { error: 'No readable project goal' });
+                    try {
+                        DashboardControlPayloadSchema.parse(await requestBody(req, { action: 'pause' }));
+                    }
+                    catch (error) {
+                        send(error.message === 'Dashboard request body too large' ? 413 : 400, { error: error.message === 'Dashboard request body too large' ? error.message : 'Invalid dashboard control payload' });
+                        return;
+                    }
+                    const current = snapshot(project, false);
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    if (current.goal)
+                        pauseProjectGoal(project.root);
+                    writePauseSignal(project.root);
+                    const response = { status: 'pause-requested' };
+                    send(200, response);
+                    return;
+                }
+                if (req.method === 'POST' && match[2] === '/resume') {
+                    try {
+                        DashboardResumePayloadSchema.parse(await requestBody(req, { action: 'resume' }));
+                    }
+                    catch (error) {
+                        send(error.message === 'Dashboard request body too large' ? 413 : 400, { error: error.message === 'Dashboard request body too large' ? error.message : 'Invalid dashboard resume payload' });
+                        return;
+                    }
+                    const current = snapshot(project, false);
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    if (projectIsRunning(project.root)) {
+                        send(409, { status: 'already-running', error: 'Project is already running' });
+                        return;
+                    }
+                    const goal = current.goal !== null && current.goal.status !== 'complete';
+                    activeResumes.add(project.root);
+                    void Promise.resolve().then(async () => {
+                        if (goal)
+                            await runProjectGoal(project.root);
+                        else
+                            await runLoopCommand(project.root, {});
+                    }).catch(() => undefined).finally(() => { activeResumes.delete(project.root); });
+                    const response = { status: 'resume-requested' };
+                    send(202, response);
+                    return;
+                }
+                if (req.method === 'POST' && match[2] === '/notes') {
+                    let payload;
+                    try {
+                        payload = DashboardNotePayloadSchema.parse(await requestBody(req, {}));
+                    }
+                    catch (error) {
+                        send(error.message === 'Dashboard request body too large' ? 413 : 400, { error: error.message === 'Dashboard request body too large' ? error.message : 'Invalid dashboard note payload' });
+                        return;
+                    }
+                    if (project.error) {
+                        send(409, { error: project.error });
+                        return;
+                    }
+                    appendEvent(project.root, { runId: 'dashboard', timestamp: new Date().toISOString(), type: 'operator-note', data: { note: payload.note } });
+                    const response = { status: 'note-added' };
+                    send(200, response);
+                    return;
+                }
+                if (req.method === 'POST' && match[2] === '/changes') {
+                    let payload;
+                    try {
+                        payload = DashboardChangePayloadSchema.parse(await requestBody(req, {}));
+                    }
+                    catch (error) {
+                        send(error.message === 'Dashboard request body too large' ? 413 : 400, { error: error.message === 'Dashboard request body too large' ? error.message : 'Invalid dashboard change payload' });
+                        return;
+                    }
+                    if (project.error) {
+                        send(409, { error: project.error });
                         return;
                     }
-                    safeFile(project.root, '.yoke/goal.pause');
-                    pauseProjectGoal(project.root);
-                    send(200, { status: 'pause-requested' });
+                    const change = queueChange(project.root, payload.request);
+                    const response = { status: 'pending', requestId: change.id };
+                    send(200, response);
                     return;
                 }
             }

package/dist/observability/events.js

@@ -55,7 +55,7 @@ export function readEvents(root, limit = 200) {
                 if (!stat.isFile() || stat.isSymbolicLink() || stat.size > EVENT_MAX_BYTES)
                     return [];
                 const value = JSON.parse(readFileSync(file, 'utf8'));
-                if (value?.schemaVersion !== 1 || typeof value.id !== 'string' || typeof value.runId !== 'string' || typeof value.timestamp !== 'string' || !Number.isFinite(Date.parse(value.timestamp)) || !['status', 'tokens', 'phase-ended', 'attempt-ended', 'accepted'].includes(value.type))
+                if (value?.schemaVersion !== 1 || typeof value.id !== 'string' || typeof value.runId !== 'string' || typeof value.timestamp !== 'string' || !Number.isFinite(Date.parse(value.timestamp)) || !['status', 'tokens', 'phase-ended', 'attempt-ended', 'accepted', 'operator-note'].includes(value.type))
                     return [];
                 if (value.durationMs !== undefined && (!Number.isFinite(value.durationMs) || value.durationMs < 0))
                     return [];

package/dist/observability/history.js

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

package/dist/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 } } : {}),

package/dist/retrofit/config.js

@@ -6,7 +6,16 @@ import { AgentSchema, PermissionProfileSchema } from '../agents/contracts.js';
 import { ProjectQualityDefaultsSchema } from '../quality/types.js';
 import { DEFAULT_OUTPUT_POLICY } from '../output/types.js';
 import { ToolActionSchema } from '../execution/actions.js';
+import { CodeIntelligenceModeSchema } from '../code-intelligence/contracts.js';
+export { CodeIntelligenceModeSchema };
 const CodeGraphSchema = z.enum(['graphify', 'serena']);
+const CodeIntelligenceProcessSchema = z.object({ command: z.string().min(1), args: z.array(z.string()).max(32).optional() });
+const CodeIntelligenceSchema = z.object({
+    mode: CodeIntelligenceModeSchema.default('off'), workspaceId: z.string().min(1).optional(),
+    graft: CodeIntelligenceProcessSchema.optional(), graphify: CodeIntelligenceProcessSchema.optional(), serena: CodeIntelligenceProcessSchema.optional(),
+    policy: z.object({ allowNetwork: z.boolean().default(false), excludePatterns: z.array(z.string().min(1)).max(100).default([]), maxFileBytes: z.number().int().positive().max(20_000_000).optional() }).optional(),
+    limits: z.object({ tokenBudget: z.number().int().min(128).max(16000).default(2400), timeoutMs: z.number().int().min(100).max(600000).default(10000), maxBytes: z.number().int().positive().max(10_000_000).default(2_000_000), maxBackends: z.number().int().min(1).max(3).default(3) }).optional(),
+});
 const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() });
 const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
 const OutputPolicySchema = z.object({
@@ -118,6 +127,7 @@ export const YokeConfigSchema = z.object({
         max: z.number().int().positive().default(4),
     }).optional(),
     codeGraph: CodeGraphSchema.optional(),
+    codeIntelligence: CodeIntelligenceSchema.optional(),
     smoke: SmokeSchema.optional(),
     quality: ProjectQualityDefaultsSchema.optional(),
     output: OutputPolicySchema.optional(),

package/dist/retrofit/gitignore.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 export const YOKE_IGNORE_LINES = [
     '.yoke/worktrees/',
     '.yoke/backup/',
+    '.yoke/code-intelligence/',
     '.yoke/loop-status.json',
     '.yoke/loop.log',
     '.yoke/loop.lock',

package/dist/retrofit/plan.js

@@ -10,7 +10,7 @@ export function planClaudeRetrofit(canonDir, targetDir) {
     return planClaude(canonDir, targetDir);
 }
 export const PLANNERS = {
-    claude: (c, t, cg) => planClaude(c, t, undefined, cg),
+    claude: (c, t, cg, ci) => planClaude(c, t, undefined, cg, undefined, ci),
     codex: planCodex,
     gemini: planGemini,
     qwen: planQwen,
@@ -18,7 +18,7 @@ export const PLANNERS = {
     kilo: planKilo,
     pi: planPi,
 };
-export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify') {
+export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify', codeIntelligence = 'off') {
     const seen = new Set();
     const merged = [];
     for (const action of baseContextActions(canonDir)) {
@@ -26,7 +26,7 @@ export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify'
         merged.push(action);
     }
     for (const agent of agents) {
-        for (const action of PLANNERS[agent](canonDir, targetDir, codeGraph)) {
+        for (const action of PLANNERS[agent](canonDir, targetDir, codeGraph, codeIntelligence)) {
             if (seen.has(action.target))
                 continue;
             seen.add(action.target);

package/dist/retrofit/planners/claude.js

@@ -22,7 +22,7 @@ This project uses the Yoke harness. Baseline instructions:
 ${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}
 ${PRESERVE_SCAFFOLD}
 `;
-export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir)) {
+export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir), codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     for (const skill of manifest.skills) {
@@ -45,8 +45,8 @@ export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGra
     actions.push({
         kind: 'write',
         target: '.mcp.json',
-        content: JSON.stringify({ mcpServers: mcpServers(codeGraph) }, null, 2) + '\n',
-        reason: 'MCP servers (code-graph + playwright)',
+        content: JSON.stringify({ mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir) }, null, 2) + '\n',
+        reason: codeIntelligence === 'off' ? 'MCP servers (code-graph + playwright)' : 'Yoke code-intelligence facade + playwright',
     });
     if (rtkHookable) {
         actions.push({

package/dist/retrofit/planners/codex.js

@@ -3,8 +3,8 @@ import { join } from 'node:path';
 import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 import { skillPackageActions } from '../skill-actions.js';
-function tomlMcp(codeGraph) {
-    const servers = mcpServers(codeGraph);
+function tomlMcp(codeGraph, codeIntelligence, targetDir) {
+    const servers = mcpServers(codeGraph, codeIntelligence, targetDir);
     // Codex reads MCP servers from ~/.codex/config.toml. This project-level file is a
     // ready-to-merge snippet; users append these blocks to their global config.
     return Object.entries(servers)
@@ -14,7 +14,7 @@ function tomlMcp(codeGraph) {
     })
         .join('\n');
 }
-export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planCodex(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'codex'));
@@ -32,8 +32,8 @@ export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
     }, {
         kind: 'write',
         target: '.codex/config.toml',
-        content: `# Yoke project configuration. Codex loads this in trusted repositories.\n\n[features]\nhooks = true\n\n${tomlMcp(codeGraph)}`,
-        reason: 'MCP servers (code-graph + playwright)',
+        content: `# Yoke project configuration. Codex loads this in trusted repositories.\n\n[features]\nhooks = true\n\n${tomlMcp(codeGraph, codeIntelligence, targetDir)}`,
+        reason: codeIntelligence === 'off' ? 'MCP servers (code-graph + playwright)' : 'Yoke code-intelligence facade + playwright',
     }, {
         kind: 'write',
         target: '.codex/hooks.json',

package/dist/retrofit/planners/gemini.js

@@ -8,7 +8,7 @@ import { skillPackageActions } from '../skill-actions.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
-export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planGemini(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     // GEMINI.md: baseline + instruction for commands outside the rewrite hook.
@@ -56,7 +56,7 @@ export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
         target: '.gemini/settings.json',
         merge: true,
         content: JSON.stringify({
-            mcpServers: mcpServers(codeGraph),
+            mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir),
             context: { fileName: ['AGENTS.md', 'GEMINI.md'] },
             hooks: { BeforeTool: [{ matcher: '^run_shell_command$', hooks: [{ name: 'yoke-rtk', type: 'command', command: 'node .gemini/hooks/gemini-rtk-hook.mjs' }] }] },
         }, null, 2) + '\n',

package/dist/retrofit/planners/kilo.js

@@ -15,7 +15,7 @@ permission:
 
 Review the observed diff and test evidence. Do not modify files. Return only actionable findings grounded in evidence.
 `;
-export function planKilo(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planKilo(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'kilo'));
@@ -31,7 +31,7 @@ export function planKilo(canonDir, _targetDir, codeGraph = 'graphify') {
         content: JSON.stringify({
             $schema: 'https://app.kilo.ai/config.json',
             instructions: ['AGENTS.md', '.yoke/context/*.md'],
-            mcp: openCodeMcpServers(codeGraph),
+            mcp: openCodeMcpServers(codeGraph, codeIntelligence, targetDir),
         }, null, 2) + '\n',
         reason: 'Kilo instructions + MCP servers',
     }, {

package/dist/retrofit/planners/opencode.js

@@ -15,7 +15,7 @@ tools:
 
 Review the observed diff and test evidence. Do not modify files. Return only actionable findings grounded in evidence.
 `;
-export function planOpenCode(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planOpenCode(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'opencode'));
@@ -31,7 +31,7 @@ export function planOpenCode(canonDir, _targetDir, codeGraph = 'graphify') {
         content: JSON.stringify({
             $schema: 'https://opencode.ai/config.json',
             instructions: ['AGENTS.md', '.yoke/context/*.md'],
-            mcp: openCodeMcpServers(codeGraph),
+            mcp: openCodeMcpServers(codeGraph, codeIntelligence, targetDir),
         }, null, 2) + '\n',
         reason: 'OpenCode instructions + MCP servers',
     }, {

package/dist/retrofit/planners/pi.js

@@ -4,7 +4,7 @@ import { loadManifest } from '../../canon/manifest.js';
 import { rtkInstruction } from '../tools.js';
 import { PRESERVE_SCAFFOLD } from '../preserve.js';
 import { skillPackageActions } from '../skill-actions.js';
-export function planPi(canonDir, _targetDir, _codeGraph = 'graphify') {
+export function planPi(canonDir, _targetDir, _codeGraph = 'graphify', _codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'pi'));

package/dist/retrofit/planners/qwen.js

@@ -8,7 +8,7 @@ import { skillPackageActions } from '../skill-actions.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
-export function planQwen(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planQwen(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     // QWEN.md: baseline + instruction for commands outside the rewrite hook.
@@ -56,7 +56,7 @@ export function planQwen(canonDir, _targetDir, codeGraph = 'graphify') {
         target: '.qwen/settings.json',
         merge: true,
         content: JSON.stringify({
-            mcpServers: mcpServers(codeGraph),
+            mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir),
             context: { fileName: ['AGENTS.md', 'QWEN.md'] },
             hooks: { PreToolUse: [{ matcher: '^run_shell_command$', hooks: [{ name: 'yoke-rtk', type: 'command', command: 'node .qwen/hooks/qwen-rtk-hook.mjs' }] }] },
         }, null, 2) + '\n',

package/dist/retrofit/tools.js

@@ -8,15 +8,17 @@ const CODE_GRAPH_SERVERS = {
         args: ['start-mcp-server', '--open-web-dashboard', 'false'],
     },
 };
-export function mcpServers(codeGraph = 'graphify') {
-    return {
-        [codeGraph]: CODE_GRAPH_SERVERS[codeGraph],
-        playwright: { command: 'npx', args: ['@playwright/mcp@latest'] },
-    };
+export function mcpServers(codeGraph = 'graphify', codeIntelligence = 'off', targetDir = '.') {
+    if (codeIntelligence !== 'off')
+        return {
+            'code-intelligence': { command: 'yoke', args: ['code-intelligence-server', `--workspace=${targetDir}`, `--mode=${codeIntelligence}`] },
+            playwright: { command: 'npx', args: ['@playwright/mcp@latest'] },
+        };
+    return { [codeGraph]: CODE_GRAPH_SERVERS[codeGraph], playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } };
 }
 /** OpenCode-family CLIs use an object with a local command array, not Claude's mcpServers shape. */
-export function openCodeMcpServers(codeGraph = 'graphify') {
-    return Object.fromEntries(Object.entries(mcpServers(codeGraph)).map(([name, server]) => [name, {
+export function openCodeMcpServers(codeGraph = 'graphify', codeIntelligence = 'off', targetDir = '.') {
+    return Object.fromEntries(Object.entries(mcpServers(codeGraph, codeIntelligence, targetDir)).map(([name, server]) => [name, {
             type: 'local',
             command: [server.command, ...server.args],
             enabled: true,

package/dist/setup/command.js

@@ -75,6 +75,7 @@ export async function runSetup(targetDir, opts = {}) {
                 ? detected.agents
                 : modelProviders.length ? ['qwen'] : [host ?? 'claude'];
     const defaultGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
+    const defaultCodeIntelligence = opts.codeIntelligence ?? existing?.codeIntelligence?.mode ?? 'off';
     const defaultLoop = opts.loop ?? existing?.loop.enabled ?? true;
     const defaultRunner = opts.runner ?? existing?.runner?.agent ?? (host && defaultAgents.includes(host) ? host : defaultAgents[0] ?? host ?? 'claude');
     const defaultPolicy = opts.decisionPolicy ?? existing?.loop.decisionPolicy ?? (existing?.loop.onAmbiguity === 'abort' ? 'critical' : 'auto');
@@ -90,6 +91,7 @@ export async function runSetup(targetDir, opts = {}) {
     try {
         let agents = defaultAgents;
         let codeGraph = defaultGraph;
+        let codeIntelligence = defaultCodeIntelligence;
         let loop = defaultLoop;
         let runner = defaultRunner;
         let decisionPolicy = defaultPolicy;
@@ -112,7 +114,7 @@ export async function runSetup(targetDir, opts = {}) {
             agents = [...agents, 'qwen'];
         if (!agents.includes(runner))
             agents = [...agents, runner];
-        const code = runRetrofit(targetDir, { loop, agents, codeGraph, host });
+        const code = runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence, host });
         if (code !== 0)
             return code;
         applyActions(presetActions, targetDir, { backupDir: join(targetDir, '.yoke', 'backups', `model-presets-${Date.now()}`) });

package/docs/CODE-INTELLIGENCE.md

@@ -0,0 +1,36 @@
+# Yoke Code Intelligence
+
+Yoke integrates Graphify, Graft and Serena as a federation. Their repositories are not merged into Yoke and their individual MCP tools are not published to agents. Yoke publishes one snapshot-bound facade with six tools:
+
+`code_context`, `code_symbol`, `code_trace`, `code_impact`, `code_edit_preview`, and `code_edit_apply`.
+
+## Enable it
+
+```sh
+yoke setup . --yes --code-intelligence=active
+# or, for an existing project:
+yoke retrofit . --code-intelligence=active
+```
+
+The default is `off`, which preserves the previous `codeGraph` behavior. `shadow` enables a read-only canary and keeps all edits blocked. `active` enables read operations and snapshot-bound edit previews. The generated host configuration exposes only Yoke's facade, so an agent cannot accidentally combine duplicate backend tools.
+
+## Backend roles and tested pins
+
+| Backend | Role | Launch command | Pin checked during integration |
+|---|---|---|---|
+| [Graft](https://github.com/trailhq/Graft) | structural code search, repo map, call graph | `graft mcp` | `05760b07abc0e427f5af8ad378889ee402c5afc6` / 0.17.0 |
+| [Graphify](https://github.com/Graphify-Labs/graphify) | architecture/document knowledge graph | `python -m graphify.serve` | `67f99bd0059dd1bac9e44382907ef9f10098b39f` / 0.9.56 |
+| [Serena](https://github.com/oraios/serena) | LSP symbols, references, implementations and semantic edits | `serena start-mcp-server --project-from-cwd --context codex` | `701e7c843f46c6a649203a488cece1bf19f1df90` / 1.7.1-dev |
+
+Install and pin these tools in the project or developer environment before enabling the facade. Yoke never installs `latest` during a task. Missing tools produce an explicit `partial` response with backend warnings and provenance; they are never interpreted as “no references”.
+
+## Safety contract
+
+- Every request is tied to a workspace and a content-addressed snapshot of committed and uncommitted, non-sensitive files.
+- Paths are workspace-relative; traversal, symlinks, `.env`/key material and policy-excluded paths are rejected.
+- Read calls are bounded by timeout and output budgets. Results carry backend, version, source path, content hash, resolution and freshness.
+- Edits run in a disposable Yoke sandbox. Preview writes a durable plan and diff but requires an approval record created by the Yoke control layer.
+- Apply rechecks the snapshot, plan expiry, plan hash, an exclusive transaction lock and idempotency. It produces a managed worktree and does not commit or merge; the existing Yoke loop and gates remain authoritative for integration.
+- Network access is not needed by the facade. Backend installation and any backend-specific network behavior remain an explicit environment concern.
+
+For a host that has no native MCP support (currently Pi), use the normal Yoke loop and bounded CLI/skill adapter. Yoke does not invent a second MCP transport for that host.