@hecer/yoke 1.22.0 → 1.23.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Cross-agent coding harness for Claude, Codex, Gemini, Qwen, OpenCode, Kilo, Pi and Hermes: one curated skill canon plus mechanical safety gates and an autonomous loop via the yoke CLI.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Cross-agent coding discipline, mechanical gates, and release workflows for eight supported harnesses",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.23.0 — 2026-10-04
+
+### Added
+- Add read-only `yoke tools-preflight` and bounded local `yoke usage` reports. Separate configured tools from available capabilities, recorded usage from unknown coverage, and overlapping worker time from summed process durations.
+- Retain immutable hashed runtime proofs before isolated candidate cleanup, with source, configuration and environment bindings. Preserve candidates when transfer or validation fails.
+- Add optional `smoke.sourceIdentity: { path, sha256 }` configuration; production browser smoke now requires it and verifies served bytes before launch and after journeys.
+
+### Fixed
+- Make setup/retrofit help read-only and reject unknown or contradictory mutating flags before dispatch while preserving recovery options.
+- Ignore supervision runtime files, diagnose already tracked copies, render actual parallel workers and integration states, and stop reporting success merely when an integrator becomes idle.
+- Preserve redacted browser launch causes instead of reporting every failure as a missing package. Keep OAuth, authorization and configured form secrets out of diagnostics.
+- Migrate Yoke-owned Codex RTK hooks to the native protocol without deleting foreign hooks; honor configured Code Intelligence workspace identifiers and await MCP shutdown before temporary directory cleanup.
+- Validate actual candidate writes and sibling collisions before and after integration gates. Reject shared writable worktree runtime caches and completion commands that change source or final assets.
+- Preserve partial/missing usage markers through routing and include recorded serial implementation durations without counting parent/child usage twice.
+
+### Migration and validation limits
+- Existing browser smoke projects must pin an app-specific served source path and its lowercase SHA-256. Update the pin intentionally after source changes; a static byte pin establishes response identity, not an independent deployment attestation.
+- Shared package download stores remain allowed. Worktrees need their own `node_modules` root and writable `.vite-temp`, `.vite` and `.cache` directories. The guard covers these conventional roots, not arbitrary application-defined cache paths or concurrent changes after inspection.
+- No dependency installer or retry policy was added: Yoke does not own one. Full-product model speed/cost and genuine npm/provider cold/warm cache comparisons remain unmeasured. The paired help experiment is a local regression check only.
+- See the [analysis](docs/benchmarks/2026-10-04-efficiency/ANALYSE.md) and [validation record](docs/RELEASE-VALIDATION-1.23.0.md). Version metadata is prepared locally; publication requires independent review and release gates, followed by verified CI/npm evidence.
+
 ## 1.22.0 — 2026-10-03
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Node.js 20+](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 
-<!-- yoke:version:start -->1.22.0<!-- yoke:version:end --> · <!-- yoke:tests:start -->1610<!-- yoke:tests:end --> test cases · <!-- yoke:skills:start -->34<!-- yoke:skills:end --> skills
+<!-- yoke:version:start -->1.23.0<!-- yoke:version:end --> · <!-- yoke:tests:start -->1697<!-- yoke:tests:end --> test cases · <!-- yoke:skills:start -->34<!-- yoke:skills:end --> skills
 
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi | Hermes<!-- yoke:agents:end -->
 
@@ -21,6 +21,8 @@ Yoke turns a goal into acceptance-tested stories, coordinates one or more coding
 
 ## How it works
 
+Version 1.23 adds local `yoke usage [dir] --json` and `yoke tools-preflight [dir] --json` diagnostics. Browser smoke now requires `smoke.sourceIdentity` with an app-specific same-origin path and the lowercase SHA-256 of its served bytes. Pin a stable source response and refresh it deliberately after source changes; see [browser delivery configuration](docs/DELIVERY-JOURNEYS.md). Local version preparation and validation limits are recorded in [1.23 validation](docs/RELEASE-VALIDATION-1.23.0.md).
+
 ```mermaid
 flowchart LR
   A[Goal and acceptance criteria] --> B[PRD stories and dependencies]

package/TODOS.md

@@ -1,5 +1,11 @@
 # Yoke follow-up work
 
+## Deferred from the user-authorized 1.23.0 release
+
+- E7: establish dependency-installer ownership before enforcing lockfile-keyed install reuse and offline/network failure classification; measure genuine cold/warm setup conditions.
+- E8: emit explicit failure categories at production boundaries where the cause is known; preserve unknown observer/guardian/approval coverage.
+- E9: collect paired full-product benchmarks and rerun the populated NEXUS layout regression with a platform-correct dependency tree. The copied macOS dependencies could not start Vite on Windows. No general speed/cost improvement is established yet.
+
 - Add provider-native output schemas when all three CLIs expose compatible stable APIs.
 - Expand benchmark fixtures and collect multiple authenticated samples per provider/model.
 - Add signed provenance and attestations to npm and GitHub releases.

package/canon/manifest.yaml

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

package/canon/skills/visual-verification/SKILL.md

@@ -24,6 +24,9 @@ Configure the key user flows once in `.yoke/config.yaml`:
 ```yaml
 smoke:
   baseUrl: http://localhost:3000
+  sourceIdentity:
+    path: /assets/app-specific-static-source.js
+    sha256: "<replace with SHA-256 of the served bytes>"
   flows:
     - name: home
       path: /
@@ -33,7 +36,26 @@ smoke:
       landmark: "form"
 ```
 
-With that in place, the `yoke flow-smoke .` step from the section-1 pipeline is live.
+The example contains a required hash placeholder. Before running production smoke, replace
+the resource path with a stable, app-specific source resource and the hash with its actual
+64-character lowercase SHA-256. The schema allows the field to be absent for existing
+configuration readers; production `flow-smoke` requires it.
+
+Start the intended server and confirm its checkout/build and port. Fetch the resource from
+the effective `baseUrl` origin, using the exact body bytes returned by the server. Hash those
+bytes, not a local source file that a dev server may transform. The resource must return a
+successful HTTP response without redirects, finish within five seconds and contain at most
+1 MiB. Keep it stable for the whole smoke run. When `--url` changes the origin, verify that
+origin serves the intended build before deriving the pin.
+
+Refresh the expected hash explicitly after an intentional source/build change and after
+confirming the server serves that change. A mismatch must fail the gate; do not automatically
+overwrite the expected hash with whatever a port happens to serve. A shared health response
+or unchanged marker cannot identify changed app code. This static pin proves only that the
+selected resource matches before and after the run; retain the checkout fingerprint and
+acceptance evidence for broader source binding.
+
+With a real pin in place, the `yoke flow-smoke .` step from the section-1 pipeline is live.
 `yoke flow-smoke` loads each route against the running dev server, waits for the landmark,
 fails on any console error, and **always** saves a screenshot to `.yoke/proof/<story>/`
 (the loop labels the folder with the current story id via `YOKE_STORY`; standalone runs use
@@ -50,5 +72,6 @@ already handles the failure case.
 
 ## Rule
 
-Green pipeline = types + units + no design-slop over budget + every flow renders without
+Green pipeline = types + units + no design-slop over budget + served-source identity matches
+before and after the run + every flow renders without
 console errors, with a screenshot to prove it. Only then is the story actually done.

package/canon/tools/codex-rtk-hook.mjs

@@ -2,24 +2,14 @@ import { spawnSync } from 'node:child_process'
 import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
-function rtkCheck(command) {
-  const result = spawnSync('rtk', ['hook', 'check', command], { encoding: 'utf8', timeout: 3000 })
-  return result.status === 0 ? result.stdout.trim() : ''
+function nativeHook(input) {
+  const result = spawnSync('rtk', ['hook', 'codex'], { input: JSON.stringify(input), encoding: 'utf8', timeout: 3000 })
+  return result.status === 0 && result.stdout.trim() ? JSON.parse(result.stdout) : null
 }
 
-export function rewriteHookInput(input, check = rtkCheck) {
-  if (input?.tool_name !== 'Bash' && input?.toolName !== 'Bash') return null
-  const toolInput = input.tool_input ?? input.toolInput
-  const command = toolInput?.command
-  if (typeof command !== 'string' || command.trim() === '') return null
-  const rewritten = check(command)
-  if (!rewritten || rewritten === command) return null
-  return {
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      updatedInput: { ...toolInput, command: rewritten },
-    },
-  }
+export function rewriteHookInput(input, processHook = nativeHook) {
+  // Native RTK owns Codex schema, permission-mode handling and fail-open rules.
+  try { return processHook(input) ?? null } catch { return null }
 }
 
 async function main() {

package/dist/cli.js

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

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

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

package/dist/code-intelligence/coordinator.js

@@ -53,7 +53,7 @@ export class CodeIntelligenceCoordinator {
     adapters;
     constructor(root, options = {}) {
         this.root = root;
-        this.workspace_id = workspaceId(root);
+        this.workspace_id = options.workspaceId ?? workspaceId(root);
         this.options = options;
         this.adapters = {
             graft: options.adapters?.graft ?? createGraftAdapter(root, options.graft),
@@ -141,6 +141,8 @@ export class CodeIntelligenceCoordinator {
         if (candidate.workspace_id && candidate.workspace_id !== this.workspace_id)
             throw new Error('workspace is not permitted');
         const snapshot = candidate.snapshot_id ? loadSnapshot(this.root, candidate.snapshot_id) : createSnapshot(this.root, this.options.policy, this.workspace_id);
+        if (snapshot.workspace_id !== this.workspace_id)
+            throw new Error('snapshot workspace identifier differs from the configured workspace; create a new snapshot');
         if (candidate.snapshot_id)
             assertSnapshotCurrent(this.root, snapshot, this.options.policy);
         return snapshot;

package/dist/code-intelligence/index.js

@@ -3,3 +3,4 @@ export * from './coordinator.js';
 export * from './edit-plans.js';
 export * from './snapshots.js';
 export * from './transactions.js';
+export * from './preflight.js';

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

@@ -12,6 +12,7 @@ export class McpStdioClient {
     pending = new Map();
     nextId = 1;
     stderrBytes = 0;
+    closing;
     constructor(command, args, cwd, framing = 'content-length', maxBytes = 2_000_000) {
         this.command = command;
         this.args = args;
@@ -29,9 +30,17 @@ export class McpStdioClient {
         }
         return this.request('tools/call', { name: tool, arguments: arguments_ }, remaining);
     }
+    async listTools(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        await this.start(timeoutMs);
+        const result = await this.request('tools/list', {}, deadline - Date.now());
+        if (!Array.isArray(result.tools))
+            throw new Error('MCP backend did not advertise tools');
+        return result.tools.map(tool => tool.name).filter((name) => typeof name === 'string');
+    }
     async close() {
         if (!this.child)
-            return;
+            return this.closing;
         const child = this.child;
         this.child = undefined;
         for (const pending of this.pending.values()) {
@@ -39,12 +48,14 @@ export class McpStdioClient {
             pending.reject(new Error('MCP process closed'));
         }
         this.pending.clear();
-        child.kill('SIGTERM');
-        await new Promise(resolve => {
+        this.closing = new Promise(resolve => {
             const timer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
-                child.kill('SIGKILL'); resolve(); }, 500);
+                child.kill('SIGKILL'); }, 500);
             child.once('close', () => { clearTimeout(timer); resolve(); });
         });
+        child.kill('SIGTERM');
+        await this.closing;
+        this.closing = undefined;
     }
     async start(timeoutMs) {
         if (this.child)

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

@@ -2,6 +2,7 @@
 import { CodeIntelligenceCoordinator } from './coordinator.js';
 import { TOOL_DEFINITIONS } from './contracts.js';
 import { loadConfig } from '../retrofit/config.js';
+import { workspaceId } from './snapshots.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' }, token_budget: { type: 'integer', minimum: 128, maximum: 16000 }, timeout_ms: { type: 'integer', minimum: 100, maximum: 60000 } } },
@@ -16,8 +17,10 @@ export async function runCodeIntelligenceServer(argv = process.argv.slice(2), io
     const workspace = arg('workspace', argv) ?? process.cwd();
     const configured = loadConfig(workspace)?.codeIntelligence;
     const mode = arg('mode', argv) ?? configured?.mode ?? 'active';
+    const workspaceIdentifier = configured?.workspaceId ?? workspaceId(workspace);
     const coordinator = new CodeIntelligenceCoordinator(workspace, {
         mode,
+        workspaceId: workspaceIdentifier,
         policy: { excludePatterns: configured?.policy?.excludePatterns, maxFileBytes: configured?.policy?.maxFileBytes },
         limits: configured?.limits,
         graft: configured?.graft, graphify: configured?.graphify, serena: configured?.serena,
@@ -39,7 +42,7 @@ export async function runCodeIntelligenceServer(argv = process.argv.slice(2), io
             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] })) } });
+            send({ jsonrpc: '2.0', id: message.id, result: { tools: TOOL_DEFINITIONS.map(tool => ({ ...tool, inputSchema: { ...INPUT_SCHEMAS[tool.name], properties: { ...INPUT_SCHEMAS[tool.name].properties, workspace_id: { type: 'string', const: workspaceIdentifier, description: 'Accepted identifier for this configured workspace.' } } } })) } });
             return;
         }
         if (message.method === 'tools/call') {

package/dist/code-intelligence/preflight.js

@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadConfig } from '../retrofit/config.js';
+import { workspaceId } from './snapshots.js';
+import { createGraftAdapter, createGraphifyAdapter, createSerenaAdapter } from './adapters/index.js';
+/** Probe protocol capabilities in an empty disposable cwd, never create a target snapshot.
+ * Configured commands are arbitrary code and cannot be promised read-only: leave them unprobed. */
+export async function runToolPreflight(root, options = {}) {
+    const configured = loadConfig(root)?.codeIntelligence;
+    const timeout = Math.min(10000, Math.max(100, options.timeoutMs ?? 2000));
+    const version = spawnSync('rtk', ['--version'], { encoding: 'utf8', timeout });
+    const native = spawnSync('rtk', ['hook', 'codex'], {
+        encoding: 'utf8', timeout,
+        input: JSON.stringify({ hook_event_name: 'PreToolUse', permission_mode: 'default', tool_name: 'Bash', tool_input: { command: 'git status' } }),
+    });
+    let nativeRewrite = false;
+    try {
+        const result = JSON.parse(native.stdout);
+        nativeRewrite = native.status === 0 && result.hookSpecificOutput?.permissionDecision === 'allow' && result.hookSpecificOutput?.updatedInput?.command === 'rtk git status';
+    }
+    catch { /* native support unavailable */ }
+    let hookRegistration = 'missing';
+    const hooksPath = join(root, '.codex/hooks.json');
+    if (existsSync(hooksPath)) {
+        try {
+            const hooks = JSON.parse(readFileSync(hooksPath, 'utf8')).hooks?.PreToolUse;
+            if (Array.isArray(hooks) && hooks.some(block => ['Bash', '^Bash$'].includes(block.matcher) && Array.isArray(block.hooks) && block.hooks.some((hook) => hook.type === 'command' && hook.command === 'rtk hook codex')))
+                hookRegistration = 'configured';
+        }
+        catch {
+            hookRegistration = 'invalid';
+        }
+    }
+    const mode = configured?.mode ?? 'off';
+    const probeRoot = mkdtempSync(join(tmpdir(), 'yoke-tool-probe-'));
+    const backends = {};
+    const definitions = [
+        ['graft', configured?.graft, createGraftAdapter, ['graft_find_code', 'graft_trace_calls']],
+        ['graphify', configured?.graphify, createGraphifyAdapter, ['query_graph', 'get_node']],
+        ['serena-lsp', configured?.serena, createSerenaAdapter, ['find_symbol', 'find_referencing_symbols']],
+    ];
+    try {
+        for (const [name, custom, factory, required] of definitions) {
+            if (mode === 'off' || custom) {
+                backends[name] = { status: 'unprobed', tools: [], missingTools: [...required], reason: mode === 'off' ? 'Configured mode is off.' : 'Custom command/arguments were not executed; read-only behavior cannot be verified.' };
+                continue;
+            }
+            const adapter = factory(probeRoot);
+            try {
+                const tools = await adapter.probe(timeout);
+                const missingTools = required.filter(tool => !tools.includes(tool));
+                backends[name] = { status: missingTools.length ? 'unavailable' : 'available', tools, missingTools };
+            }
+            catch {
+                backends[name] = { status: 'unavailable', tools: [], missingTools: [...required], reason: 'Backend protocol initialization or tools/list failed; target indexing was not attempted.' };
+            }
+            finally {
+                await adapter.close();
+            }
+        }
+    }
+    finally {
+        rmSync(probeRoot, { recursive: true, force: true });
+    }
+    return {
+        rtk: { status: nativeRewrite ? 'available' : 'degraded', version: version.status === 0 ? version.stdout.trim() : null, nativeRewrite, hookRegistration, hostActivation: 'unverified', nestedCodeMode: 'unverified', fallback: nativeRewrite ? 'Explicit RTK prefixes remain required for unverified nested code-mode calls; project-hook activation depends on host support and trust.' : 'Use explicit RTK prefixes; update RTK outside this preflight if native Codex support is needed. Use rtk init --codex --dry-run to inspect supported setup flags.' },
+        codeIntelligence: { mode, workspaceId: configured?.workspaceId ?? workspaceId(root), status: mode === 'off' ? 'off' : Object.values(backends).every(backend => backend.status === 'available') ? 'available' : 'degraded', backends, probeScope: 'isolated protocol capabilities only', indexFreshness: 'unverified', fallback: 'Use rg and direct source reads; verify backend candidates against source. Target index freshness and exhaustive coverage are unverified.' },
+    };
+}

package/dist/loop/cache-isolation.js

@@ -0,0 +1,36 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+const CACHE_PATHS = ['node_modules', '.vite-temp', '.vite', '.cache', 'node_modules/.vite-temp', 'node_modules/.vite', 'node_modules/.cache'];
+/** Check writable roots only: ordinary package links and download stores remain supported. */
+export function cacheIsolationProblem(worktree) {
+    let root;
+    try {
+        root = realpathSync.native(worktree);
+    }
+    catch {
+        return 'Cannot verify isolated worktree cache boundary. Restore the candidate directory before running gates.';
+    }
+    for (const path of CACHE_PATHS) {
+        const candidate = join(root, path);
+        try {
+            lstatSync(candidate);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            return `Cannot inspect isolated cache ${path}. Repair permissions before running gates.`;
+        }
+        let actual;
+        try {
+            actual = realpathSync.native(candidate);
+        }
+        catch {
+            return `Cannot resolve isolated cache ${path}. Repair its dangling link or permissions before running gates.`;
+        }
+        const rel = relative(root, actual);
+        if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\')) {
+            return `Isolated cache ${path} resolves outside the candidate. Use worktree-local node_modules and writable runtime caches; shared package download stores and package-level links are allowed. Repair this link before retrying; do not relax the sandbox.`;
+        }
+    }
+    return undefined;
+}

package/dist/loop/loop.js

@@ -1,3 +1,5 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
+import { retainRuntimeProof } from './proof-retention.js';
 import { knownInfrastructureFailure } from "../routing/capability.js";
 import { existsSync, unlinkSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { acceptanceProtectionProblem } from '../check/command.js';
@@ -182,6 +184,8 @@ function runCompletionGate(opts, stories) {
         const verdict = opts.completion(opts.targetDir);
         if (!verdict.passed)
             reason = `integrated system did not verify: ${verdict.summary}`;
+        else if (!opts.git.isClean(opts.targetDir))
+            reason = 'completion command left source or final assets dirty; preserve changes and move rerun proofs to ignored runtime paths before resuming';
     }
     catch (error) {
         reason = `integrated completion gate failed: ${error.message}`;
@@ -203,6 +207,9 @@ function runCompletionGate(opts, stories) {
     return { status: 'blocked', iterations: 0, reason, failure: observed.failure, finalProgress: progress(stories) };
 }
 function runCriterionGates(opts, executionDir, story) {
+    const cacheProblem = opts.isolate && executionDir !== opts.targetDir ? cacheIsolationProblem(executionDir) : undefined;
+    if (cacheProblem)
+        return { passed: false, summary: cacheProblem };
     const protectionProblem = acceptanceProtectionProblem(executionDir, opts.targetDir);
     if (protectionProblem)
         return { passed: false, summary: protectionProblem };
@@ -214,10 +221,10 @@ function runCriterionGates(opts, executionDir, story) {
     }
     if (!opts.verifyCriterion)
         return { passed: false, summary: `story ${story.id} has criteria but no criterion verifier` };
-    const evidence = criteria.map(criterion => ({
-        criterion,
-        result: opts.verifyCriterion(executionDir, story, criterion),
-    }));
+    const evidence = criteria.map(criterion => {
+        const problem = opts.isolate && executionDir !== opts.targetDir ? cacheIsolationProblem(executionDir) : undefined;
+        return { criterion, result: problem ? { passed: false, summary: problem } : opts.verifyCriterion(executionDir, story, criterion) };
+    });
     try {
         writeCriterionEvidence(opts.targetDir, story, evidence);
     }
@@ -230,6 +237,15 @@ function runCriterionGates(opts, executionDir, story) {
         : { passed: true, summary: `${evidence.length} acceptance criteria verified` };
 }
 export function runLoop(opts) {
+    if (opts.isolate)
+        for (const name of ['verify', 'design', 'perf', 'audit']) {
+            const gate = opts[name];
+            if (gate)
+                opts = { ...opts, [name]: (dir) => {
+                        const problem = dir !== opts.targetDir ? cacheIsolationProblem(dir) : undefined;
+                        return problem ? { passed: false, summary: problem } : gate(dir);
+                    } };
+        }
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
     for (;;) {
@@ -445,6 +461,7 @@ export function runLoop(opts) {
                 });
                 const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
                 savePrd(wtPrd, updated);
+                retainRuntimeProof(wt, story.id, opts.targetDir);
                 opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
                 opts.git.integrate(opts.targetDir, wt);
                 result.routing?.recordOutcome(true);
@@ -623,6 +640,9 @@ function runImplementation(opts, dir, story, reporter) {
     let feedback = opts.feedback;
     for (let attempt = 0;; attempt++) {
         const result = opts.runner({ targetDir: dir, story, feedback });
+        const cacheProblem = opts.isolate && dir !== opts.targetDir ? cacheIsolationProblem(dir) : undefined;
+        if (cacheProblem)
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: cacheProblem } };
         if (!result.routing?.canRetry || result.routing.blocked || attempt >= 7)
             return { result };
         if (["decision-request.yaml", "ambiguity.md", "loop.pause"].some(name => existsSync(join(dir, ".yoke", name))) || existsSync(pauseFilePath(opts.targetDir)))

package/dist/loop/parallel-adapters.js

@@ -3,11 +3,14 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { isProviderTreeAlive, reapProviderProcesses } from './cleanup.js';
-import { realGitOps, stageImplementation } from './git.js';
+import { realGitOps, stageImplementation, RUNTIME_EXCLUDES } from './git.js';
 import { isPidAlive } from './lock.js';
 import { storyPathSegment } from './prd.js';
 import { killProcessTreeForCleanup } from './watchdog.js';
 import { parallelAcceptanceDigest, recoverParallelWorktree, retainParallelWorktree } from './recovery.js';
+import { cacheIsolationProblem } from './cache-isolation.js';
+import { retainRuntimeProof } from './proof-retention.js';
+import { writeScopesOverlap } from './scheduler.js';
 import { statePath } from '../workspace/state.js';
 export function makeParallelAdapters(targetDir, identity, injectedGit) {
     return injectedGit
@@ -78,7 +81,13 @@ function productionAdapters(targetDir, identity) {
         git: {
             isClean: dir => realGitOps.isClean(dir),
             rebase: input => rebaseCandidate(targetDir, input),
-            commit: input => realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity),
+            commit: input => {
+                const unexpected = unexpectedWrites(input, changedPaths(input.worktree.path, gitText(input.worktree.path, ['rev-parse', 'HEAD'])));
+                if (unexpected.length)
+                    throw new Error(`Candidate writes outside declared scopes after integrated gates: ${unexpected.join(', ')}`);
+                retainRuntimeProof(input.worktree.path, input.story.id, targetDir);
+                realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity);
+            },
             integrate: (input, expectedHead) => integrateCandidate(targetDir, input, expectedHead),
         },
         candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens, acceptanceDigests.get(primary.story.id)),
@@ -177,7 +186,18 @@ function writeCandidateStatus(targetDir, input, worktree, state, reason) {
     writeFileSync(file, JSON.stringify({ storyId: input.storyId, candidateId: input.candidateId, worktree, state, ...(reason ? { reason } : {}) }));
 }
 function rebaseCandidate(targetDir, input) {
+    const cacheProblem = cacheIsolationProblem(input.worktree.path);
+    if (cacheProblem)
+        return { kind: 'reopen', reason: cacheProblem };
     const currentHead = gitText(targetDir, ['rev-parse', 'HEAD']);
+    const actual = changedPaths(input.worktree.path, input.worktree.baseCommit);
+    const unexpected = unexpectedWrites(input, actual);
+    const siblings = currentHead === input.worktree.baseCommit ? [] : changedPaths(targetDir, input.worktree.baseCommit);
+    const collisions = actual.filter(path => writeScopesOverlap([path], siblings));
+    if (unexpected.length)
+        return { kind: 'reopen', reason: `Candidate writes outside declared scopes: ${unexpected.join(', ')}${collisions.length ? `; integrated sibling collisions: ${collisions.join(', ')}` : ''}` };
+    if (collisions.length)
+        return { kind: 'reopen', reason: `Candidate writes collide with integrated sibling changes: ${collisions.join(', ')}` };
     const candidateHead = gitText(input.worktree.path, ['rev-parse', 'HEAD']);
     try {
         execFileSync('git', ['merge-base', '--is-ancestor', input.worktree.baseCommit, 'HEAD'], { cwd: input.worktree.path, stdio: 'pipe' });
@@ -247,3 +267,16 @@ function gitText(dir, args) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function changedPaths(directory, base) {
+    const read = (args) => execFileSync('git', args, { cwd: directory, stdio: 'pipe' }).toString().split('\0').filter(Boolean);
+    return [...new Set([...read(['diff', '--no-renames', '--name-only', '-z', base, '--', '.', ...RUNTIME_EXCLUDES]), ...read(['ls-files', '--others', '--exclude-standard', '-z', '--', '.', ...RUNTIME_EXCLUDES])])].filter(path => !/^(?:\.yoke\/(?:proof|context)\/|\.yoke\/prd\.(?:yaml|json)$)/u.test(path));
+}
+function unexpectedWrites(input, paths) {
+    if (input.story.writes === undefined)
+        return [];
+    const normalize = (value) => {
+        const path = value.replace(/\\/gu, '/').replace(/\/$/u, '');
+        return process.platform === 'win32' ? path.toLowerCase() : path;
+    };
+    return paths.filter(path => !input.story.writes.some(scope => normalize(path) === normalize(scope) || normalize(path).startsWith(`${normalize(scope)}/`)));
+}