@hecer/yoke 1.17.0 → 1.19.0

package/canon/loop/loop-spec.md

@@ -4,7 +4,8 @@ The autonomous loop is optional and toggle-able:
 
 - `yoke loop on` / `yoke loop off` — enable or disable it in `.yoke/config.yaml`.
 - `yoke loop status` — show enabled state and backlog progress.
-- `yoke loop run [--max=N] [--parallel=N] [--isolate] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — run until the current backlog is green or a gate blocks.
+- `yoke loop run [--max=N] [--parallel=N] [--isolate] [--explore] [--explore-interval=N] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — run until the backlog is green or a gate blocks; `--explore` opts into persistent discovery and recovery after each backlog drains.
+- `yoke loop pause` — request a safe-boundary pause from a running loop or exploration supervisor.
 - `yoke change add --idea="..."` — queue a product change at any time, including while the loop is running.
 - `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop.
 
@@ -13,6 +14,10 @@ story is fast-forwarded to the main tree. Pass `--review` or `--reviewer=<provid
 a separate, schema-validated review. Pass `--parallel=N` to dispatch ready, non-colliding stories
 concurrently. Pass `--json` for NDJSON status on stdout.
 
+With `--explore`, `--explore-limit=12h|3d|2w` optionally stops one invocation after the selected
+duration. The default is unbounded. Expiry stops new work and pauses after active stories complete
+their normal gates and integration; exit code `3` can be resumed with another `yoke loop run`.
+
 Stories may declare a reference, candidate artifact, rubric, and blocking/advisory quality policy.
 `--quality` runs a read-only blind critic plus bounded repair before review; every repair reruns the
 mechanical gates. `--candidates=N` requires quality declarations and dispatches multiple isolated
@@ -48,12 +53,24 @@ For each story:
 7. Only after all gates pass, mark the story `passes: true`, log the decision, and commit
    atomically. A failed commit restores the PRD state.
 8. When all current stories pass, run optional `completion.command` against the integrated
-   system. Only a green result reports `complete`; otherwise the loop blocks. This readiness
-   result is ephemeral, not a release and not a freeze on future changes.
+   system. Only a green result reports `complete`; otherwise the loop blocks. In `--explore` mode
+   a green result starts a read-only exploration pass instead of ending the supervisor. A red
+   completion gate is supplied as evidence to the explorer so it can propose work to resolve the
+   blocker; the gate is never skipped.
+9. Exploration proposals require repository-file evidence, confidence of at least 0.8, low/medium
+   risk, disjoint declared write scopes, and two to five structured acceptance criteria with
+   criterion-targeted approved test commands. Yoke validates and commits accepted PRD changes
+   before isolated implementation. Passed exploration stories are compacted from the active PRD;
+   their full prior contracts remain in Git history and a bounded recent fingerprint ledger
+   prevents near-term duplication.
 
 A supervisor can pause the loop by creating `.yoke/loop.pause`. The running story finishes;
 the dispatcher latches the signal, stops launching new workers, lets active workers reach safe
 terminal proof/cleanup, and exits with code `3` before another story is integrated.
+`--explore` also checks this signal while waiting between scans and during retry backoff. Without
+an explicit `--max` cap, draining the current PRD does not stop exploration; the supervisor waits,
+retries recoverable failures with backoff, and reports the next action. It cannot survive forced
+process or machine termination.
 
 State lives outside model context: PRD, git, and the ignored `.yoke/changes/` inbox. All are
 re-read at story boundaries, so a request queued mid-run becomes additional stories without a

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.17.0
+version: 1.19.0
 agents: [claude, codex, gemini, qwen, opencode, kilo, pi, hermes]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology, invocation: auto }

package/dist/agents/process.js

@@ -6,6 +6,7 @@ import { createBoundedOutput, createTelemetryAccumulator } from './process-strea
 import { processIncarnation } from './process-incarnation.js';
 import { prepareWindowsInvocation, resolveWindowsCommand } from './windows-launch.js';
 import { createSupervision, supervisionLimits, assertPreviousProvidersStopped } from './supervision.js';
+import { prepareSolPiTemporaryConfig } from './sol-pi-runtime.js';
 function cancellationReason(signal) {
     return typeof signal.reason === 'string' && signal.reason.length > 0
         ? signal.reason
@@ -26,25 +27,48 @@ export function startProviderProcess(agent, invocation, options = {}) {
     let progress = () => { };
     const limits = supervisionLimits(invocation.cwd);
     const supervision = createSupervision(invocation.cwd, reason => failure(reason), () => progress(), options.attempt);
+    let restoreSolPiConfig = () => { };
     let prepared;
     try {
+        if (agent === 'pi')
+            restoreSolPiConfig = prepareSolPiTemporaryConfig(invocation.cwd);
         assertPreviousProvidersStopped(invocation.cwd);
         prepared = process.platform === 'win32' ? prepareWindowsInvocation(invocation) : { command: invocation.command, args: invocation.args, env: process.env };
     }
     catch (error) {
-        const message = error.message;
+        let message = error.message;
+        try {
+            restoreSolPiConfig();
+        }
+        catch (cleanupError) {
+            message = cleanupError.message;
+        }
         supervision.stop(message);
         return { pid: undefined, invocation, recordPath: '', cancel: () => false, completion: Promise.resolve({ kind: 'spawn-failed', error: message, invocation, pid: undefined, stdout: '', stderr: '', stdoutTruncated: false, stderrTruncated: false, telemetry: { usageAvailable: false } }) };
     }
     const spawnOptions = { ...prepared, cwd: invocation.cwd, shell: false, detached: process.platform !== 'win32' };
-    const child = spawn(spawnOptions.command, [...spawnOptions.args], {
-        cwd: spawnOptions.cwd,
-        shell: spawnOptions.shell,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        detached: spawnOptions.detached,
-        env: prepared.env,
-        windowsHide: true,
-    });
+    let child;
+    try {
+        child = spawn(spawnOptions.command, [...spawnOptions.args], {
+            cwd: spawnOptions.cwd,
+            shell: spawnOptions.shell,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            detached: spawnOptions.detached,
+            env: prepared.env,
+            windowsHide: true,
+        });
+    }
+    catch (error) {
+        let message = error.message;
+        try {
+            restoreSolPiConfig();
+        }
+        catch (cleanupError) {
+            message = cleanupError.message;
+        }
+        supervision.stop(message);
+        return { pid: undefined, invocation, recordPath: '', cancel: () => false, completion: Promise.resolve({ kind: 'spawn-failed', error: message, invocation, pid: undefined, stdout: '', stderr: '', stdoutTruncated: false, stderrTruncated: false, telemetry: { usageAvailable: false } }) };
+    }
     const targetDir = resolve(invocation.cwd);
     const pid = child.pid;
     const startedAt = pid === undefined ? `unverified:${new Date().toISOString()}` : processIncarnation(pid) ?? `unverified:${new Date().toISOString()}`;
@@ -130,11 +154,18 @@ export function startProviderProcess(agent, invocation, options = {}) {
             return;
         settled = true;
         clearTimers();
-        supervision.stop(termination?.reason ?? (result.kind === 'succeeded' ? 'provider-exited' : 'provider-failed'), !termination || terminationConfirmed);
+        let completedResult = result;
+        try {
+            restoreSolPiConfig();
+        }
+        catch (error) {
+            completedResult = { ...evidence(), kind: 'spawn-failed', error: error.message };
+        }
+        supervision.stop(termination?.reason ?? (completedResult.kind === 'succeeded' ? 'provider-exited' : 'provider-failed'), !termination || terminationConfirmed);
         options.signal?.removeEventListener('abort', onAbort);
         if (!termination || terminationConfirmed)
             removeRecord();
-        resolveCompletion(result);
+        resolveCompletion(completedResult);
     };
     const evidence = () => ({
         invocation,

package/dist/agents/providers.js

@@ -1,5 +1,7 @@
 import { ModelSelectionSchema } from './contracts.js';
 import { fileURLToPath } from 'node:url';
+import { loadSolPiProjectConfig } from './sol-pi-runtime.js';
+const SOL_PI_EXTENSION = 'git:github.com/NVlabs/SoL-Pi@d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0';
 export { providerSpawnOptions, startProviderProcess, } from './process.js';
 const argsFor = (agent, permissions) => {
     if (agent === 'claude') {
@@ -76,6 +78,13 @@ export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe'
     if (parsedSelection.variant && !['opencode', 'kilo', 'pi', 'hermes'].includes(agent))
         throw new Error(`${agent} does not support a model variant selection`);
     const args = argsFor(agent, permissions);
+    if (agent === 'pi' && loadSolPiProjectConfig(cwd)?.solpi?.enabled) {
+        const [major, minor] = process.version.slice(1).split('.').map(Number);
+        if (major < 22 || (major === 22 && minor < 19)) {
+            throw new Error(`SoL-Pi requires Node.js 22.19 or newer; current version is ${process.version}`);
+        }
+        args.push('--extension', SOL_PI_EXTENSION);
+    }
     if (output.schemaFile !== undefined || output.jsonSchema !== undefined) {
         if (agent === 'codex' && output.schemaFile && output.jsonSchema === undefined) {
             if (/[\0\r\n]/u.test(output.schemaFile) || (process.platform === 'win32' && !/^[A-Za-z0-9_./:\\-]+$/u.test(output.schemaFile)))
@@ -119,7 +128,7 @@ export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe'
         else if (agent === 'pi')
             args.push('--thinking', parsedSelection.reasoningEffort);
         else if (agent === 'hermes')
-            args.push('--reasoning-effort', parsedSelection.reasoningEffort);
+            args.push('--reasoning', parsedSelection.reasoningEffort);
     }
     if (parsedSelection.variant) {
         if ((agent === 'opencode' || agent === 'kilo') && !parsedSelection.reasoningEffort)
@@ -134,7 +143,7 @@ export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe'
             if (parsedSelection.reasoningEffort && parsedSelection.reasoningEffort !== parsedSelection.variant)
                 throw new Error('Hermes reasoningEffort and variant selections must match');
             if (!parsedSelection.reasoningEffort)
-                args.push('--reasoning-effort', parsedSelection.variant);
+                args.push('--reasoning', parsedSelection.variant);
         }
     }
     if (agent === 'codex' && parsedSelection.nativeMultiAgent === false)

package/dist/agents/sol-pi-runtime.js

@@ -0,0 +1,76 @@
+import { lstatSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { loadConfig, toSolPiNativeConfig } from '../retrofit/config.js';
+export function loadSolPiProjectConfig(directory) {
+    let current = resolve(directory);
+    while (true) {
+        const config = loadConfig(current);
+        if (config)
+            return config;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function lstatIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function assertNoConfigSymlinks(paths) {
+    for (const path of paths) {
+        if (lstatIfPresent(path)?.isSymbolicLink())
+            throw new Error('SoL-Pi refuses symbolic-link config paths: ' + path);
+    }
+}
+function removeCreatedDirectories(directories) {
+    for (const directory of [...directories].reverse()) {
+        try {
+            rmdirSync(directory);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTEMPTY')
+                throw error;
+        }
+    }
+}
+export function prepareSolPiTemporaryConfig(workspace) {
+    const config = loadSolPiProjectConfig(workspace);
+    if (!config?.solpi?.enabled)
+        return () => { };
+    const piDirectory = resolve(workspace, '.pi');
+    const solPiConfigPath = join(piDirectory, 'sol-pi.json');
+    const configPaths = [piDirectory, solPiConfigPath];
+    assertNoConfigSymlinks(configPaths);
+    const existingConfig = lstatIfPresent(solPiConfigPath) ? readFileSync(solPiConfigPath) : undefined;
+    const createdDirectories = [];
+    const restore = () => {
+        assertNoConfigSymlinks(configPaths);
+        if (existingConfig === undefined)
+            rmSync(solPiConfigPath, { force: true });
+        else
+            writeFileSync(solPiConfigPath, existingConfig);
+        removeCreatedDirectories(createdDirectories);
+    };
+    try {
+        for (const directory of [piDirectory]) {
+            if (!lstatIfPresent(directory)) {
+                mkdirSync(directory);
+                createdDirectories.push(directory);
+            }
+        }
+        writeFileSync(solPiConfigPath, JSON.stringify(toSolPiNativeConfig(config)), { flag: existingConfig === undefined ? 'wx' : 'w' });
+    }
+    catch (error) {
+        restore();
+        throw error;
+    }
+    return restore;
+}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { createProjectGoal, readProjectGoal, runProjectGoal, pauseProjectGoal, g
 import { validateCanon } from './canon/validate.js';
 import { runRetrofit } from './retrofit/command.js';
 import { setLoopEnabled, loopStatus, runLoopCommand } from './loop/run-command.js';
+import { requestLoopPause } from './loop/loop.js';
 import { runContextInit, runContextStatus } from './context/command.js';
 import { runReview } from './review/command.js';
 import { scanDir } from './scan/design.js';
@@ -103,6 +104,33 @@ export function parseQualityFlags(args) {
         },
     };
 }
+export function parseExploreLimit(value) {
+    const match = /^(\d+)\s*(h|hours?|d|days?|w|weeks?)$/i.exec(value.trim());
+    if (!match)
+        return { ok: false, error: `Invalid --explore-limit value: ${value} (expected a positive duration such as 12h, 3d, or 2w)` };
+    const amount = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const unitMs = unit.startsWith('h') ? 60 * 60_000 : unit.startsWith('d') ? 24 * 60 * 60_000 : 7 * 24 * 60 * 60_000;
+    const milliseconds = amount * unitMs;
+    if (!Number.isSafeInteger(amount) || amount <= 0 || !Number.isSafeInteger(milliseconds) || Date.now() + milliseconds > 8_640_000_000_000_000) {
+        return { ok: false, error: `Invalid --explore-limit value: ${value} (duration must be positive and within the supported date range)` };
+    }
+    return { ok: true, milliseconds };
+}
+function parseExploreLimitFlag(args, explore) {
+    const values = args.filter(arg => arg.startsWith('--explore-limit='));
+    if (args.includes('--explore-limit'))
+        return { ok: false, error: '--explore-limit requires a duration, for example --explore-limit=12h' };
+    if (values.length > 1)
+        return { ok: false, error: 'Use --explore-limit only once per invocation' };
+    const raw = values[0];
+    if (!raw)
+        return { ok: true };
+    if (!explore)
+        return { ok: false, error: '--explore-limit requires --explore' };
+    const parsed = parseExploreLimit(raw.slice('--explore-limit='.length));
+    return parsed.ok ? { ok: true, milliseconds: parsed.milliseconds } : parsed;
+}
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -358,6 +386,11 @@ export function main(argv) {
                 console.log(loopStatus(targetDir));
                 return 0;
             }
+            if (sub === 'pause') {
+                requestLoopPause(targetDir);
+                console.log('Pause requested at the next safe story or exploration boundary.');
+                return 0;
+            }
             if (sub === 'cleanup')
                 return runLoopCleanup(targetDir, {
                     removeWorktrees: rest.includes('--remove-worktrees'),
@@ -414,7 +447,23 @@ export function main(argv) {
                     console.error(qualityFlags.error);
                     return 1;
                 }
-                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options });
+                const explore = rest.includes('--explore');
+                const exploreLimit = parseExploreLimitFlag(rest, explore);
+                if (!exploreLimit.ok) {
+                    console.error(exploreLimit.error);
+                    return 1;
+                }
+                const exploreArg = rest.find(a => a.startsWith('--explore-interval='));
+                if (exploreArg && !explore) {
+                    console.error('--explore-interval requires --explore');
+                    return 1;
+                }
+                const exploreIntervalMinutes = exploreArg ? Number(exploreArg.slice('--explore-interval='.length)) : undefined;
+                if (exploreIntervalMinutes !== undefined && (!Number.isInteger(exploreIntervalMinutes) || exploreIntervalMinutes < 1 || exploreIntervalMinutes > 1_440)) {
+                    console.error(`Invalid --explore-interval value: ${exploreArg} (expected 1..1440 minutes)`);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options, ...(explore ? { explore: true } : {}), ...(exploreIntervalMinutes !== undefined ? { exploreIntervalMinutes } : {}), ...(exploreLimit.milliseconds !== undefined ? { exploreLimitMs: exploreLimit.milliseconds } : {}) });
             }
             if (sub === 'answer') {
                 const choice = rest.find(a => a.startsWith('--choice='))?.slice('--choice='.length);
@@ -543,9 +592,29 @@ export function main(argv) {
                     console.error(qualityFlags.error);
                     return 1;
                 }
-                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, ...qualityFlags.options });
+                const explore = rest.includes('--explore');
+                const exploreLimit = parseExploreLimitFlag(rest, explore);
+                if (!exploreLimit.ok) {
+                    console.error(exploreLimit.error);
+                    return 1;
+                }
+                const exploreArg = rest.find(a => a.startsWith('--explore-interval='));
+                if (exploreArg && !explore) {
+                    console.error('--explore-interval requires --explore');
+                    return 1;
+                }
+                const exploreIntervalMinutes = exploreArg ? Number(exploreArg.slice('--explore-interval='.length)) : undefined;
+                if (exploreIntervalMinutes !== undefined && (!Number.isInteger(exploreIntervalMinutes) || exploreIntervalMinutes < 1 || exploreIntervalMinutes > 1_440)) {
+                    console.error(`Invalid --explore-interval value: ${exploreArg} (expected 1..1440 minutes)`);
+                    return 1;
+                }
+                if (explore && rest.includes('--resume-worktree')) {
+                    console.error('--explore starts its own safe resume cycle; remove --resume-worktree and re-run it after resolving the retained story.');
+                    return 1;
+                }
+                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|decision|answer|resume [--discard] [--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] [--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|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': {

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

@@ -2,7 +2,7 @@ import { McpBackendAdapter } from './mcp.js';
 export const GRAPHIFY_VERSION = '0.9.56';
 export function createGraphifyAdapter(cwd, override) {
     return new McpBackendAdapter({
-        name: 'graphify', version: GRAPHIFY_VERSION, cwd, command: override?.command ?? 'python', args: override?.args ?? ['-m', 'graphify.serve'], framing: 'content-length', semantic: false, documents: true,
+        name: 'graphify', version: GRAPHIFY_VERSION, cwd, command: override?.command ?? 'python', args: override?.args ?? ['-m', 'graphify.serve'], framing: 'line', semantic: false, documents: true,
         aliases: { context: 'query_graph', symbol: 'get_node', neighbors: 'get_neighbors', trace: 'shortest_path', impact: 'get_pr_impact' },
     });
 }

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

@@ -2,16 +2,37 @@ import { McpStdioClient } from '../mcp-client.js';
 function valueFromResult(value) {
     if (!value || typeof value !== 'object')
         return value;
-    if (value.structuredContent !== undefined)
-        return value.structuredContent;
+    if (value.isError === true)
+        throw new Error('MCP backend tool returned an error');
+    if (value.structuredContent !== undefined) {
+        const structured = value.structuredContent;
+        if (structured && typeof structured === 'object' && Object.keys(structured).length === 1 && typeof structured.result === 'string') {
+            try {
+                return JSON.parse(structured.result);
+            }
+            catch {
+                return structured.result;
+            }
+        }
+        return structured;
+    }
     const text = Array.isArray(value.content) ? value.content.find((item) => item?.type === 'text')?.text : undefined;
     if (typeof text !== 'string')
         return value;
     try {
-        return JSON.parse(text);
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === 'object' && Object.keys(parsed).length === 1 && typeof parsed.result === 'string') {
+            try {
+                return JSON.parse(parsed.result);
+            }
+            catch {
+                return parsed.result;
+            }
+        }
+        return parsed;
     }
     catch {
-        return { text };
+        return text;
     }
 }
 export class McpBackendAdapter {

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

@@ -2,7 +2,7 @@ import { McpBackendAdapter } from './mcp.js';
 export const SERENA_VERSION = '1.7.1-dev';
 export function createSerenaAdapter(cwd, override) {
     return new McpBackendAdapter({
-        name: 'serena-lsp', version: SERENA_VERSION, cwd, command: override?.command ?? 'serena', args: override?.args ?? ['start-mcp-server', '--project-from-cwd', '--context', 'codex'], framing: 'content-length', semantic: true, documents: false,
+        name: 'serena-lsp', version: SERENA_VERSION, cwd, command: override?.command ?? 'serena', args: override?.args ?? ['start-mcp-server', '--project-from-cwd', '--context', 'codex'], framing: 'line', semantic: true, documents: false,
         aliases: {
             symbol: 'find_symbol', references: 'find_referencing_symbols', implementations: 'find_implementations', overview: 'get_symbols_overview', diagnostics: 'get_diagnostics_for_file',
             rename: 'rename_symbol', replace_symbol_body: 'replace_symbol_body', insert_before_symbol: 'insert_before_symbol', insert_after_symbol: 'insert_after_symbol', safe_delete: 'safe_delete_symbol',

package/dist/code-intelligence/coordinator.js

@@ -185,9 +185,10 @@ export class CodeIntelligenceCoordinator {
         const name = input.symbol_id ?? input.query;
         const reference = symbolArgs(name, input.path ?? '');
         const graft = await this.call('graft', 'context', { query: name, limit: 10, ...(input.path ? { in: input.path } : {}) }, input.timeout_ms, state);
+        // Graft returns search prose, not structured symbol definitions. Preserve
+        // its provenance without inventing a symbol from the response heading.
         if (graft !== null) {
             const normalized = normalizeItems(graft, this.evidenceOptions(snapshot, 'graft'), 'symbol', 20);
-            symbols.push(...normalized.items.map(item => ({ symbol_id: `graft:${item.item_id}`, name: item.excerpt.split(/\s|\(|\{/u)[0] ?? name, path: item.path, kind: 'unknown', signature: item.excerpt.slice(0, 500), evidence_ids: item.evidence_ids })));
             provenance.push(...normalized.provenance);
         }
         const symbol = await this.call('serena-lsp', 'symbol', { name_path_pattern: reference.name_path, depth: 0, relative_path: reference.relative_path, include_body: false, max_matches: 20 }, input.timeout_ms, state);

package/dist/code-intelligence/evidence.js

@@ -12,7 +12,7 @@ function textOf(raw) {
     }
 }
 function locate(text, root) {
-    const match = /(?:^|[\s("'`])((?:[A-Za-z0-9_.@-]+[\\/])*[A-Za-z0-9_.@-]+\.[A-Za-z0-9]+):(\d+)/u.exec(text);
+    const match = /(?:^|[\s("'`])((?:[A-Za-z0-9_.@-]+[\\/])*[A-Za-z0-9_.@-]+\.[A-Za-z0-9]+):L?(\d+)/u.exec(text);
     if (!match)
         return { path: null, line: null };
     try {
@@ -44,6 +44,17 @@ export function normalizeItems(raw, options, kind = 'code', limit = 100) {
         if (!excerpt)
             continue;
         const p = makeProvenance(options, excerpt, excerpt.toLowerCase().includes('ambiguous') ? 'ambiguous' : 'resolved');
+        if (candidate && typeof candidate === 'object' && typeof candidate.relative_path === 'string') {
+            try {
+                p.source_path = assertSafePath(options.root, candidate.relative_path);
+                p.content_hash = options.snapshot.files.find(file => file.path === p.source_path)?.hash ?? null;
+            }
+            catch {
+                p.source_path = null;
+                p.content_hash = null;
+                p.resolution = '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: items.length });

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

@@ -1,6 +1,6 @@
 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). */
+/** Small, bounded stdio MCP client. Supports newline JSON-RPC used by the
+ * backend SDKs and optional Content-Length framing for legacy peers. */
 export class McpStdioClient {
     command;
     args;

package/dist/dashboard/page.js

@@ -33,7 +33,7 @@ function validDate(value){if(!/^\\d{4}-\\d{2}-\\d{2}$/u.test(value))return false
 function parseNavigationHash(hash){
   const params=new URLSearchParams(String(hash||'').replace(/^#/u,''));const screen=params.get('screen')||'overview',project=params.get('project'),view=params.get('view')||'now',period=Number(params.get('period')||30),group=params.get('group')||'day',from=params.get('from')||'',to=params.get('to')||'',query=params.get('query')||'',status=params.get('status')||'all',sort=params.get('sort')||'attention';
   const datesValid=(!from&&!to)||(validDate(from)&&validDate(to)&&from<=to&&Date.parse(to+'T00:00:00Z')-Date.parse(from+'T00:00:00Z')<=365*86400000);
-  if(!['overview','workspace','project'].includes(screen)||!['now','usage','results','history'].includes(view)||![1,7,30,90,365].includes(period)||!['day','week','month'].includes(group)||!['all','active','attention'].includes(status)||!['attention','activity','tokens','cost','acceptance','name'].includes(sort)||query.length>200||!datesValid||(screen==='project'&&!/^[a-f0-9]{32}$/u.test(project||'')))return {...defaultNavigation};
+  if(!['overview','workspace','project'].includes(screen)||!['now','usage','results','history','settings'].includes(view)||![1,7,30,90,365].includes(period)||!['day','week','month'].includes(group)||!['all','active','attention'].includes(status)||!['attention','activity','tokens','cost','acceptance','name'].includes(sort)||query.length>200||!datesValid||(screen==='project'&&!/^[a-f0-9]{32}$/u.test(project||'')))return {...defaultNavigation};
   const state={screen,project:screen==='project'?project:null,view,period,group,from,to};if(params.has('query'))state.query=query;if(params.has('status'))state.status=status;if(params.has('sort'))state.sort=sort;return state;
 }
 function serializeNavigationHash(state){const params=new URLSearchParams({screen:state.screen||'overview',view:state.view||'now',period:String(state.period||30),group:state.group||'day'});if(state.project)params.set('project',state.project);if(state.from&&state.to){params.set('from',state.from);params.set('to',state.to)}if(state.query)params.set('query',state.query);if(state.status&&state.status!=='all')params.set('status',state.status);if(state.sort&&state.sort!=='attention')params.set('sort',state.sort);return '#'+params.toString()}

package/dist/dashboard/panels.js

@@ -125,25 +125,47 @@ function renderUsageHistory(current,previous,project={}){
 }
 function renderResults(p,a){const t=a.total;content.append(append(el('div',undefined,'metrics'),metric('Accepted in period',t.accepted,'Recorded acceptance events'),metric('Repair phases',t.repairs,'Routing escalations: '+t.escalations),metric('Tokens / acceptance',rate(t.tokensPerAccepted),'Reported input + output, including failed work')));const attempts=panel('Measured outcomes');attempts.append(el('p','Ended attempts: '+t.attempts+' · explicitly successful attempts: '+t.successfulAttempts+' · average summed attempt time per acceptance: '+duration(t.timePerAcceptedMs)));attempts.append(el('p','Worker termination alone is not counted as successful acceptance. Rates only describe recorded activity in the selected period.','muted'));attempts.append(table(['Task','Attempts','Accepted','Repairs','Escalations','Tokens / acceptance'],a.tasks.map(v=>[v.storyId,v.attempts,v.accepted,v.repairs,v.escalations,rate(v.tokensPerAccepted)])));content.append(attempts);const checks=panel('Latest saved acceptance evidence');if(p.check){checks.append(el('p',p.check.summary));for(const c of p.check.criteria){const item=row(c.text,c.id,c.status);item.firstChild.append(append(el('details'),el('summary','View evidence'),el('p',c.summary)));checks.append(item)}checks.append(el('p','Checked '+p.check.generatedAt+' · historical evidence; independent of the selected statistics period.','muted'))}else checks.append(el('p','No saved independent check.','empty'));content.append(checks);const goals=panel('Saved goal attempts');for(const attempt of p.goal?.attempts||[])goals.append(row(attempt.provider||'Agent',(attempt.summary||'')+' · '+duration(attempt.durationMs)+' · input '+tokenText(attempt.inputTokens)+' / output '+tokenText(attempt.outputTokens),attempt.success?'finished':'failed'));content.append(goals)}
 function renderHistoryExplorer(project,history){const state=projectStatus(project),view=panel('History explorer');view.append(el('p','Recorded events and completed runs in the selected UTC window. The list is bounded to the latest 100 events.','muted'));const events=timelineEvents(history.events||[]);if(!events.length)view.append(el('p','No recorded history in this period.','empty'));else{const list=el('div',undefined,'timeline');for(const event of events)list.append(timelineItem(event));view.append(list)}const runs=panel('Run history');if(!(history.runs||[]).length)runs.append(el('p','No recorded runs in this period.','empty'));else runs.append(table(['Run','Started','Ended','Agent','Provider','Model','Tokens','Accepted','Outcome'],history.runs.map(run=>[dimensionLabel(run.runId),run.startedAt||'Not reported',run.endedAt||'Not reported',dimensionLabel(run.agent),dimensionLabel(run.provider),dimensionLabel(run.model),rankingText(run.total?.tokens?.total),rankingText(run.total?.outcomes?.accepted),rankingText(run.total?.outcomes?.successfulAttempts)])));content.append(renderCoverage(history,{stale:state.stale,unavailable:false}),runs,view)}
+function solPiRatioError(value){const text=String(value);const ratio=Number(text);return text.trim()===''||!Number.isFinite(ratio)||ratio<0?'Enter a finite cache write/read ratio of 0 or more.':null}
+async function saveSolPiSettings(projectId,settings,feedback){
+  const error=solPiRatioError(settings.cacheWriteReadRatio);if(error){feedback.className='settings-feedback notice';feedback.textContent=error;return}
+  feedback.className='settings-feedback muted';feedback.textContent='Saving settings…';
+  try{await api('/api/projects/'+projectId+'/settings',{method:'POST',headers:{'content-type':'application/json','x-yoke-token':sessionToken},body:JSON.stringify({...settings,cacheWriteReadRatio:Number(settings.cacheWriteReadRatio)})});feedback.className='settings-feedback muted';feedback.textContent='Settings saved.'}
+  catch(error){feedback.className='settings-feedback notice';feedback.textContent='Could not save settings: '+error.message}
+}
+function renderSolPiSettings(project,settings){
+  const view=panel('SoL-Pi settings');view.append(el('p','SoL-Pi is off by default. Change the master switch and any mechanism switches, then save.','muted'));
+  const controls={},toggles=[['enabled','Enable SoL-Pi (off by default)'],['actionFusion','Action fusion'],['observationPack','Observation packing'],['evidencePreservingReducer','Evidence-preserving reducer'],['onlineContextCompact','Online context compaction']];
+  for(const [key,label] of toggles){const input=el('input');input.type='checkbox';input.checked=settings[key]===true;input.setAttribute('role','switch');input.setAttribute('aria-label',label);controls[key]=input;view.append(append(el('label',undefined,'setting-toggle'),input,el('span',label)))}
+  const ratioLabel=el('label',undefined,'field'),ratio=el('input');ratio.type='number';ratio.min='0';ratio.step='any';ratio.value=String(settings.cacheWriteReadRatio);ratio.setAttribute('aria-label','Cache write/read ratio');ratioLabel.append(el('span','Cache write/read ratio','label'),ratio);view.append(ratioLabel);
+  view.append(el('p','The pinned SoL-Pi extension executes inside Pi. Review the pinned SoL-Pi extension before enabling it.','muted'));
+  view.append(el('p','SoL-Pi needs a compatible Pi runtime installed and configured; Yoke does not install or authenticate Pi. For headless runs, Pi requires explicit project trust before it loads project-local settings. Open Pi, run /trust, then restart. Yoke does not grant trust.','muted'));
+  view.append(el('p','The evidence-preserving reducer may make a model call using diagnostic logs; those logs can contain project data. Review the selected provider and model before enabling it.','muted'));
+  const feedback=el('p','Save your changes to apply them.','settings-feedback muted');feedback.setAttribute('role','status');feedback.setAttribute('aria-live','polite');view.append(feedback);
+  view.append(button('Save settings',()=>saveSolPiSettings(project.id,{enabled:controls.enabled.checked,actionFusion:controls.actionFusion.checked,observationPack:controls.observationPack.checked,evidencePreservingReducer:controls.evidencePreservingReducer.checked,onlineContextCompact:controls.onlineContextCompact.checked,cacheWriteReadRatio:ratio.value},feedback),true));
+  return view
+}
 async function showProject(id){
   const request=beginRequest();selected=id;nav();
   try{
     const bounds=periodWindows(Date.now(),periodDays,customFrom,customTo),detailRequest=api('/api/projects/'+id,{},request.signal);
-    let project,current=null,previous=null,history=null;
+    let project,current=null,previous=null,history=null,settings=null;
     if(projectView==='usage'){
       [project,current,previous]=await Promise.all([detailRequest,api('/api/projects/'+id+'/analytics?'+queryPeriod(bounds.current),{},request.signal),api('/api/projects/'+id+'/analytics?'+queryPeriod(bounds.previous),{},request.signal)]);
     }else if(projectView==='results'){
       [project,current]=await Promise.all([detailRequest,api('/api/projects/'+id+'/analytics?'+queryPeriod(bounds.current),{},request.signal)]);
     }else if(projectView==='history'){
       [project,history]=await Promise.all([detailRequest,api('/api/projects/'+id+'/history?'+queryPeriod(bounds.current)+'&limit=100',{},request.signal)]);
+    }else if(projectView==='settings'){
+      [project,settings]=await Promise.all([detailRequest,api('/api/projects/'+id+'/settings',{},request.signal)]);
     }else project=await detailRequest;
     if(!currentRequest(request.version)||navigationState.screen!=='project'||selected!==id)return;
     lastSuccessfulSync=new Date().toISOString();heading(project.name,project.goal?.objective||'Saved project work');content.append(el('p',project.root,'path'));for(const error of project.errors)content.append(el('p',error,'notice'));
-    const tabs=el('div',undefined,'actions');for(const [view,label] of [['now','Now'],['usage','Usage & time'],['results','Results'],['history','History']]){const control=button(label,()=>setNavigation({view}),projectView===view);control.setAttribute('aria-pressed',String(projectView===view));tabs.append(control)}
+    const tabs=el('div',undefined,'actions');for(const [view,label] of [['now','Now'],['usage','Usage & time'],['results','Results'],['history','History'],['settings','Settings']]){const control=button(label,()=>setNavigation({view}),projectView===view);control.setAttribute('aria-pressed',String(projectView===view));tabs.append(control)}
     content.append(tabs);
     if(projectView==='now'){
       const tasks=project.stories||[],state=projectStatus(project);content.append(append(el('div',undefined,'metrics'),metric('Accepted tasks',tasks.filter(task=>task.passes).length+' / '+tasks.length,'Saved acceptance state'),metric('Remaining time',project.estimate?.available?duration(project.estimate.lowerMs)+' – '+duration(project.estimate.upperMs):'Unknown',project.estimate?.available?project.estimate.sampleCount+' samples · empirical range':'No reliable duration history'),metric('Project status',state.primary,state.goal&&state.loop&&state.goal!==state.loop?'Goal '+state.goal+' · loop '+(state.stale?'unconfirmed':state.loop):'Latest reported state')));renderNow(project);
-    }else{periodControls(id);if(projectView==='usage')renderUsageHistory(current,previous,projectStatus(project));else if(projectView==='history')renderHistoryExplorer(project,history);else renderResults(project,current)}
+    }else if(projectView==='settings')content.append(renderSolPiSettings(project,settings));
+    else{periodControls(id);if(projectView==='usage')renderUsageHistory(current,previous,projectStatus(project));else if(projectView==='history')renderHistoryExplorer(project,history);else renderResults(project,current)}
   }catch(error){if(currentRequest(request.version)&&navigationState.screen==='project'&&selected===id&&!isAbort(error)){heading('Project unavailable','Offline or unavailable: '+error.message);content.append(renderCoverage({errors:[],coverage:'Historical analytics are unavailable for this project.'},{unavailable:true}))}}
 }
 if(typeof setInterval==='function')setInterval(()=>{if(selected&&projectView==='now'&&typeof document.hidden!=='undefined'&&!document.hidden&&!['INPUT','SELECT','TEXTAREA'].includes(document.activeElement?.tagName)&&!document.activeElement?.matches?.(':focus-visible'))showProject(selected)},5000);