@hecer/yoke 1.9.0 → 1.10.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.9.0",
+  "version": "1.10.0",
   "description": "Cross-agent coding harness: one curated skill canon (TDD, brainstorming, plans, reviews, shipping, design verification) 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.9.0",
+  "version": "1.10.0",
   "description": "Cross-agent coding discipline, mechanical gates, and release workflows",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## Unreleased
+## 1.10.0 — 2026-09-06
+
+### Added
+- Adopt the Yoke wordmark in the GitHub and npm README.
+- Prepare task assessments in one bounded planning call with `yoke prd assess`; draft and inbox planning bind assessments to requirements, upstream dependencies and the approved brief.
+- Separate `planning.agent`/`model`/`reasoningEffort` from execution settings. New setups require prepared assessments and block missing worker profiles; existing configurations retain on-demand planning and parent fallback.
+- Add selective reassessment, planning input limits and `routing.maxTier` to bound automatic model selection and escalation.
+- Add attention-first project search and status filters, with separate goal/loop states and explicit stale activity warnings.
+- Restore dashboard views and UTC period controls through URL links, browser history and refresh; cancel obsolete requests and bound project comparison concurrency.
+- Compare recorded tokens, accepted tasks and reported costs against the preceding equal-duration period without inventing missing measurements or percentages from zero baselines.
+
+### Fixed
+- Fix Windows safe-mode Codex execution by screening Store PowerShell/aliases and probing a native shell under the same sandbox before model work; keep permissions intact.
+- Launch Windows provider executables/npm entry points with literal argv; bound preflight and provider lifetime, recognize streamed infrastructure failures, retain failed-worktree/process evidence, and guard against unconfirmed termination before another worker starts.
+- Separate provider liveness, supervisor heartbeat, output and successful-tool progress in status/dashboard; label backlog percentages and preserve explicit bare startup through capability routing. See [Windows runner validation](docs/WINDOWS-RUNNER-VALIDATION.md).
+- Keep local loop locks and dashboard status out of implementation commits and clean-worktree checks.
+- Stage implementation files safely when runtime history directories are already ignored, including literal filenames and tracked deletions, for serial commits and parallel candidate snapshots.
+
+### Migration and validation limits
+- Existing routing configurations retain on-demand assessment and parent fallback. Use `yoke prd assess` to prepare task packages; configure `planning.agent`, `planning.model`, `planning.reasoningEffort` and `routing.maxTier` to separate planning from bounded execution. New setups require prepared assessments and block missing profiles.
+- Update installed packages and restart the dashboard/runner to use the new code. Existing running processes are not upgraded or instrumented retroactively. Windows preflight preserves sandbox permissions and changes only the provider environment.
+- Dashboard comparisons report recorded measurements, not reconstructed history or calibrated savings. Tokens per minute are consumption rates, not generation speed. Live routed Windows validation covered Codex on the documented machine; cross-provider performance and universal Windows compatibility are not established. See the linked dashboard, batch-planning and runner validation records.
 
 ## 1.9.0 — 2026-09-06
 

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-# 🐂 Yoke
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.10.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.9.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1134<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.10.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1173<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1134%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1173%20defined-blue.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -27,7 +27,7 @@
 
 > **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
 
-**New in 1.9.0:** [routing by task requirements](docs/CAPABILITY-ROUTING.md). Keep planning on the start model, select execution models and effort from saved task assessments, and use bounded repair and escalation with independent checks. The dashboard explains model selection; existing routing settings remain authoritative.
+**New in 1.10.0:** [dashboard search, filters and period comparisons](docs/DASHBOARD-EVOLUTION.md), [batch task assessments with separate planning models](docs/CAPABILITY-ROUTING.md), and [Windows sandbox preflight and process supervision](docs/WINDOWS-RUNNER-VALIDATION.md). Existing routing settings remain authoritative. See the [changelog](CHANGELOG.md) for migration and validation limits.
 
 ### One dashboard, multiple projects
 
@@ -40,6 +40,8 @@ yoke dashboard --no-register
 
 Open the printed `http://127.0.0.1:...` URL. Each registered project has its own goals, tasks and evidence. The dashboard shows available worker state, per-task duration estimates, planned start offsets, input/output tokens, costs and unknown measurements. You can request a goal pause at a safe boundary.
 
+The dashboard includes attention-first project search and filters, restorable view links, and usage comparisons against the preceding period. See [dashboard behavior and measurement limits](docs/DASHBOARD-EVOLUTION.md).
+
 Projects are registered explicitly; this version does not automatically discover every process or aggregate other computers. Start/resume and budget changes use the CLI. Missing history appears as unknown; time ranges are empirical estimates, not exact deadlines.
 
 ### Verified goals and efficient execution
@@ -895,7 +897,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1134 tests)
+npm test          # vitest (1173 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/canon/loop/prd.schema.md

@@ -34,6 +34,12 @@ belongs in a trusted `completion.command` journey suite.
 `sourceChange` is an optional Yoke-owned request ID. The change inbox uses it to append new
 stories idempotently; authors normally omit it.
 
+`assessment` holds the planner's task class, difficulty, uncertainty, risk, scope, testability,
+reason and approach. `assessmentFor` is a Yoke-generated SHA-256 binding to the task requirements,
+upstream contracts and approved brief. Do not copy a binding onto changed requirements.
+With `routing.assessmentPolicy: prepared`, use `yoke prd assess` after editing contracts;
+dispatch blocks missing or stale assessments. See [capability routing](../../docs/CAPABILITY-ROUTING.md).
+
 Stories without `needs`, `area`, or `agent` retain serial behavior. A story is ready only when
 every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously
 active areas, and uses `agent` as an affinity hint.

package/dist/agents/process-incarnation.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-const queryProcessIdentity = (command, args, options) => execFileSync(command, args, { stdio: 'pipe', ...options }).toString();
+const queryProcessIdentity = (command, args, options) => execFileSync(command, args, { stdio: 'pipe', timeout: 5000, windowsHide: true, ...options }).toString();
 export function processIncarnation(pid, platform = process.platform, query = queryProcessIdentity) {
     try {
         if (platform === 'win32') {

package/dist/agents/process.js

@@ -4,35 +4,64 @@ import { killProcessTreeForCleanup } from '../loop/watchdog.js';
 import { createProviderProcessRecord, filesystemProviderProcessRecordAdapter, } from './process-record.js';
 import { createBoundedOutput, createTelemetryAccumulator } from './process-streams.js';
 import { processIncarnation } from './process-incarnation.js';
+import { prepareWindowsInvocation, resolveWindowsCommand } from './windows-launch.js';
+import { createSupervision, supervisionLimits, assertPreviousProvidersStopped } from './supervision.js';
 function cancellationReason(signal) {
     return typeof signal.reason === 'string' && signal.reason.length > 0
         ? signal.reason
         : 'provider process cancellation requested';
 }
 export function providerSpawnOptions(invocation, platform = process.platform) {
-    const windowsCommandShim = !/[\\/]/u.test(invocation.command) || /\.(?:bat|cmd)$/iu.test(invocation.command);
+    const resolved = platform === 'win32' ? resolveWindowsCommand(invocation.command, invocation.args) : invocation;
     return {
-        command: invocation.command,
-        args: invocation.args,
+        command: resolved.command,
+        args: resolved.args,
         cwd: invocation.cwd,
-        shell: platform === 'win32' && windowsCommandShim,
+        shell: false,
         detached: platform !== 'win32',
     };
 }
 export function startProviderProcess(agent, invocation, options = {}) {
-    const spawnOptions = providerSpawnOptions(invocation);
+    let failure = () => { };
+    let progress = () => { };
+    const limits = supervisionLimits(invocation.cwd);
+    const supervision = createSupervision(invocation.cwd, reason => failure(reason), () => progress(), options.attempt);
+    let prepared;
+    try {
+        assertPreviousProvidersStopped(invocation.cwd);
+        prepared = process.platform === 'win32' ? prepareWindowsInvocation(invocation) : { command: invocation.command, args: invocation.args, env: process.env };
+    }
+    catch (error) {
+        const message = error.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,
     });
     const targetDir = resolve(invocation.cwd);
     const pid = child.pid;
     const startedAt = pid === undefined ? `unverified:${new Date().toISOString()}` : processIncarnation(pid) ?? `unverified:${new Date().toISOString()}`;
+    supervision.start(pid, 'shell' in prepared ? prepared.shell : undefined, startedAt.startsWith('unverified:') ? undefined : startedAt);
     const record = createProviderProcessRecord(targetDir, pid ?? 0, options.workerId, startedAt);
     const recordAdapter = options.recordAdapter ?? filesystemProviderProcessRecordAdapter;
-    const terminateProcessTree = options.terminateProcessTree ?? ((processPid) => killProcessTreeForCleanup(processPid));
+    const terminateProcessTree = options.terminateProcessTree ?? ((processPid) => {
+        try {
+            process.kill(processPid, 0);
+        }
+        catch {
+            return true;
+        }
+        if (startedAt.startsWith('unverified:') || processIncarnation(processPid) !== startedAt)
+            return false;
+        return killProcessTreeForCleanup(processPid);
+    });
     let recordPublished = false;
     const stdout = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
     const stderr = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
@@ -42,6 +71,9 @@ export function startProviderProcess(agent, invocation, options = {}) {
     let termination;
     let idleTimer;
     let forceTimer;
+    let totalTimer;
+    let progressTimer;
+    let completionTimer;
     let recordFailure;
     let terminationConfirmed = false;
     let settled = false;
@@ -58,6 +90,12 @@ export function startProviderProcess(agent, invocation, options = {}) {
             clearTimeout(idleTimer);
         if (forceTimer)
             clearTimeout(forceTimer);
+        if (totalTimer)
+            clearTimeout(totalTimer);
+        if (progressTimer)
+            clearTimeout(progressTimer);
+        if (completionTimer)
+            clearTimeout(completionTimer);
         idleTimer = undefined;
         forceTimer = undefined;
     };
@@ -66,6 +104,7 @@ export function startProviderProcess(agent, invocation, options = {}) {
             return;
         settled = true;
         clearTimers();
+        supervision.stop(termination?.reason ?? (result.kind === 'succeeded' ? 'provider-exited' : 'provider-failed'), !termination || terminationConfirmed);
         options.signal?.removeEventListener('abort', onAbort);
         if (!termination || terminationConfirmed)
             removeRecord();
@@ -81,6 +120,9 @@ export function startProviderProcess(agent, invocation, options = {}) {
         telemetry: telemetry.finish(),
     });
     const finalize = (exitCode) => {
+        if (settled)
+            return;
+        supervision.flush();
         // Windows can emit close before taskkill's process-tree state is observable.
         // Reconfirm here so successful termination does not leave a stale ownership record.
         if (termination && pid !== undefined && !terminationConfirmed) {
@@ -114,6 +156,21 @@ export function startProviderProcess(agent, invocation, options = {}) {
         forceTimer = setTimeout(() => {
             if (pid !== undefined && !settled)
                 terminationConfirmed = terminateProcessTree(pid, true);
+            // Allow close/pipe draining to confirm termination before the bounded fallback.
+            if (!settled)
+                completionTimer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    // A killer's return value is not an observed process exit.
+                    if (pid !== undefined) {
+                        try {
+                            process.kill(pid, 0);
+                            terminationConfirmed = false;
+                        }
+                        catch { /* exited */ }
+                    }
+                    finalize(null);
+                }, 5000);
         }, terminationGraceMs);
         return true;
     };
@@ -140,8 +197,16 @@ export function startProviderProcess(agent, invocation, options = {}) {
             stderr.append(text);
         }
         options.onOutput?.({ stream, text });
+        supervision.output(stream, text);
         armIdleTimer();
     };
+    failure = reason => { terminate({ kind: 'cancelled', reason }); };
+    progress = () => {
+        if (progressTimer)
+            clearTimeout(progressTimer);
+        if ((options.progressTimeoutMs ?? limits.progressMs) > 0)
+            progressTimer = setTimeout(() => terminate({ kind: 'timed-out', reason: 'provider-progress-timeout' }), options.progressTimeoutMs ?? limits.progressMs);
+    };
     child.stdout?.on('data', chunk => { onOutput('stdout', chunk); });
     child.stderr?.on('data', chunk => { onOutput('stderr', chunk); });
     child.stdin?.on('error', () => { });
@@ -178,5 +243,8 @@ export function startProviderProcess(agent, invocation, options = {}) {
     else
         options.signal?.addEventListener('abort', onAbort, { once: true });
     armIdleTimer();
+    if ((options.totalTimeoutMs ?? limits.totalMs) > 0)
+        totalTimer = setTimeout(() => terminate({ kind: 'timed-out', reason: 'provider-total-timeout' }), options.totalTimeoutMs ?? limits.totalMs);
+    progress();
     return handle;
 }

package/dist/agents/supervision.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync, renameSync, readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { processIncarnation } from './process-incarnation.js';
+import { loadConfig } from '../retrofit/config.js';
+export function supervisionLimits(cwd) {
+    const loop = loadConfig(cwd)?.loop;
+    return { totalMs: (loop?.maxCallMinutes ?? 30) * 60_000, progressMs: (loop?.progressTimeoutMinutes ?? 20) * 60_000 };
+}
+export function assertPreviousProvidersStopped(cwd) {
+    if (readSupervision(cwd, '').some(record => record.state === 'termination-unconfirmed' && record.liveness !== 'exited')) {
+        throw Error('A previous provider termination is unconfirmed; inspect owned process records before starting another worker');
+    }
+}
+/** Only provider error/tool-result envelopes are failure evidence; stderr MCP chatter is not. */
+export function inspectProviderEvent(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return {};
+    }
+    if (!event || typeof event !== 'object')
+        return {};
+    const item = event.item;
+    const failedCommand = event.type === 'item.completed' && item?.type === 'command_execution' && (item.status === 'failed' || (typeof item.exit_code === 'number' && item.exit_code !== 0));
+    const fatal = event.type === 'error' || event.type === 'turn.failed' || (event.type === 'result' && (event.is_error === true || event.status === 'error'));
+    if (failedCommand || fatal) {
+        const details = JSON.stringify(failedCommand ? item.aggregated_output : event.error ?? event.errors ?? event.result ?? event.message);
+        if (/CreateProcess(?:AsUserW|W)? failed|Failed to create unified exec process/iu.test(details ?? ''))
+            return { failure: 'worker-shell-spawn-failed' };
+        if (/AuthRequired|authentication failed|invalid api key|No access token|credentials (?:missing|not found)/iu.test(details ?? ''))
+            return { failure: 'provider-authentication-failed' };
+        if (fatal)
+            return { failure: 'provider-terminal-error' };
+    }
+    return { progress: (event.type === 'item.completed' && ((item?.type === 'command_execution' && item.exit_code === 0) || (item?.type === 'file_change' && item.status === 'completed')))
+            || (event.type === 'tool_result' && event.status === 'success')
+            || (event.type === 'user' && Array.isArray(event.message?.content) && event.message.content.some((part) => part.type === 'tool_result' && part.is_error === false)) };
+}
+export function inspectProviderDiagnostic(line) {
+    if (/\bERROR codex_core::tools::router: error=exec_command failed: CreateProcess\b/u.test(line) && /CreateProcess(?:AsUserW|W)? failed/u.test(line))
+        return 'worker-shell-spawn-failed';
+    // Unrelated rmcp/MCP authentication diagnostics are intentionally excluded.
+    if (/^(?:Error: |error: )(?:authentication failed|invalid api key|No access token)/iu.test(line))
+        return 'provider-authentication-failed';
+    return undefined;
+}
+export function createSupervision(cwd, onFailure, onProgress = () => { }, attempt = 1) {
+    const id = randomUUID(), dir = join(cwd, '.yoke', 'supervision'), path = join(dir, id + '.json');
+    const now = () => new Date().toISOString();
+    const state = { id, supervisorPid: process.pid, startedAt: now(), heartbeatAt: now(), state: 'preflight', retry: Math.max(0, attempt - 1) };
+    let pending = '', stderrPending = '', terminal = false, failure;
+    const save = () => {
+        state.heartbeatAt = now();
+        mkdirSync(dir, { recursive: true });
+        const temp = path + '.tmp';
+        writeFileSync(temp, JSON.stringify(state));
+        renameSync(temp, path);
+    };
+    save();
+    const timer = setInterval(() => { if (!terminal)
+        save(); }, 5000);
+    timer.unref();
+    return {
+        state,
+        flush() { if (pending)
+            this.output('stdout', '\n'); if (stderrPending)
+            this.output('stderr', '\n'); },
+        start(pid, shell, incarnation) { state.childPid = pid; state.childIncarnation = incarnation; state.shell = shell; state.state = 'running'; save(); },
+        output(stream, text) {
+            state.lastOutputAt = now();
+            const lines = ((stream === 'stdout' ? pending : stderrPending) + text).split(/\r?\n/u);
+            const tail = lines.pop() ?? '';
+            if (stream === 'stdout')
+                pending = tail.length > 262144 ? '' : tail;
+            else
+                stderrPending = tail.length > 262144 ? '' : tail;
+            for (const line of lines) {
+                if (line.length > 262144)
+                    continue;
+                const result = stream === 'stdout' ? inspectProviderEvent(line) : { failure: inspectProviderDiagnostic(line) };
+                if (result.progress) {
+                    state.lastProgressAt = now();
+                    onProgress();
+                }
+                if (result.failure && !failure) {
+                    failure = result.failure;
+                    state.reason = failure;
+                    state.state = 'stopping';
+                    save();
+                    onFailure(failure);
+                }
+            }
+        },
+        stop(reason, confirmed = true) { terminal = true; clearInterval(timer); state.reason = failure ?? reason; state.state = confirmed ? 'stopped' : 'termination-unconfirmed'; save(); },
+        get failure() { return failure; },
+    };
+}
+export function readSupervision(root, since) {
+    const roots = [root];
+    try {
+        for (const name of readdirSync(join(root, '.yoke', 'worktrees')).slice(0, 100)) {
+            const path = join(root, '.yoke', 'worktrees', name);
+            if (lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink())
+                roots.push(path);
+        }
+    }
+    catch { /* no isolated workers */ }
+    const records = [];
+    for (const cwd of roots) {
+        const dir = join(cwd, '.yoke', 'supervision');
+        try {
+            if (lstatSync(dir).isSymbolicLink())
+                continue;
+            for (const name of readdirSync(dir).filter(n => n.endsWith('.json')).slice(-200)) {
+                const path = join(dir, name), stat = lstatSync(path);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8192)
+                    continue;
+                try {
+                    const record = JSON.parse(readFileSync(path, 'utf8'));
+                    if (typeof record.startedAt === 'string' && record.startedAt >= since && typeof record.heartbeatAt === 'string')
+                        records.push(record);
+                }
+                catch { /* incomplete/untrusted state */ }
+            }
+        }
+        catch { /* no process evidence */ }
+    }
+    return records.sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, 20).map(record => ({ ...record, liveness: processLiveness(record) }));
+}
+const identities = new Map();
+function processLiveness(record) {
+    if (!Number.isInteger(record.childPid) || record.childPid <= 0)
+        return 'identity-unverified';
+    try {
+        process.kill(record.childPid, 0);
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'exited' : 'identity-unverified';
+    }
+    if (!record.childIncarnation)
+        return 'identity-unverified';
+    let identity = identities.get(record.childPid);
+    if (!identity || Date.now() - identity.at > 5000) {
+        identity = { at: Date.now(), value: processIncarnation(record.childPid) };
+        identities.set(record.childPid, identity);
+        if (identities.size > 100)
+            identities.delete(identities.keys().next().value);
+    }
+    return identity.value === record.childIncarnation ? 'alive' : 'identity-unverified';
+}

package/dist/agents/windows-launch.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+const file = (path) => { try {
+    return statSync(path).isFile();
+}
+catch {
+    return false;
+} };
+const pathValue = (env) => env[Object.keys(env).find(k => k.toLowerCase() === 'path') ?? 'PATH'] ?? '';
+/** Resolve npm launchers without cmd.exe argument concatenation. */
+export function resolveWindowsCommand(command, args, env = process.env) {
+    if (command === 'node' || command === process.execPath)
+        return { command: process.execPath, args: [...args] };
+    if (isAbsolute(command) && /\.(exe|com)$/iu.test(command))
+        return { command, args: [...args] };
+    const candidates = isAbsolute(command) || /[\\/]/u.test(command) ? [command]
+        : pathValue(env).split(';').filter(Boolean).flatMap(dir => extname(command) ? [join(dir, command)] : ['.exe', '.com', '.cmd', '.bat'].map(ext => join(dir, command + ext)));
+    const found = candidates.find(file);
+    if (!found)
+        throw Error(`Provider executable unavailable: ${command}`);
+    if (/\.(exe|com)$/iu.test(found))
+        return { command: found, args: [...args] };
+    const script = readFileSync(found, 'utf8');
+    const entry = script.match(/"%dp0%[\\/]([^"\r\n]+\.(?:m?js|cjs))"/iu)?.[1];
+    if (!entry)
+        throw Error('Unsupported Windows batch launcher; use a native executable or an npm-generated CLI launcher');
+    const target = resolve(dirname(found), ...entry.split(/[\\/]/u));
+    if (!file(target))
+        throw Error('Provider npm entry point is missing');
+    const localNode = join(dirname(found), 'node.exe');
+    return { command: file(localNode) ? localNode : process.execPath, args: [target, ...args] };
+}
+export function inaccessibleStoreShell(path) {
+    const bad = (p) => /[\\/]WindowsApps[\\/](?:Microsoft\.PowerShell[^\\/]*[\\/]|(?:pwsh|powershell)\.exe$)/iu.test(p);
+    if (bad(path))
+        return true;
+    try {
+        return bad(realpathSync(path));
+    }
+    catch {
+        return false;
+    }
+}
+export function windowsShellEnvironment(env = process.env) {
+    // Change only this provider's PATH. Never change machine/user configuration or permissions.
+    const paths = pathValue(env).split(';').filter(Boolean).filter(dir => !['pwsh.exe', 'powershell.exe'].some(name => inaccessibleStoreShell(join(dir, name))));
+    const nativePwsh = join(env.ProgramFiles ?? 'C:\\Program Files', 'PowerShell', '7', 'pwsh.exe');
+    const systemShell = join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    const shell = [...paths.map(p => join(p, 'pwsh.exe')), nativePwsh, ...paths.map(p => join(p, 'powershell.exe')), systemShell].find(p => file(p) && !inaccessibleStoreShell(p));
+    if (!shell)
+        throw Error('No native PowerShell available for sandbox preflight');
+    const next = { ...env };
+    for (const key of Object.keys(next))
+        if (key.toLowerCase() === 'path')
+            delete next[key];
+    next.PATH = [dirname(shell), ...paths].join(delimiter);
+    return { env: next, shell };
+}
+/** Model-free probe under the same Codex permission profile and isolated cwd. */
+export function prepareWindowsInvocation(inv, env = process.env) {
+    if (inv.command !== 'codex' || !inv.args.includes('exec') || inv.args.includes('--dangerously-bypass-approvals-and-sandbox'))
+        return { ...resolveWindowsCommand(inv.command, inv.args, env), env };
+    const prepared = windowsShellEnvironment(env);
+    const readOnly = inv.args.includes('read-only');
+    const config = ['--config', `shell_environment_policy.set.PATH=${JSON.stringify(prepared.env.PATH)}`];
+    const probe = resolveWindowsCommand('codex', ['sandbox', '-P', readOnly ? ':read-only' : ':workspace', '-C', inv.cwd, ...config, '--', prepared.shell, '-NoProfile', '-NonInteractive', '-Command', 'Write-Output YOKE_SHELL_OK'], prepared.env);
+    const compiled = fileURLToPath(new URL('../loop/watchdog.js', import.meta.url));
+    const watchdog = existsSync(compiled) ? [compiled] : ['--import', pathToFileURL(createRequire(import.meta.url).resolve('tsx')).href, fileURLToPath(new URL('../loop/watchdog.ts', import.meta.url))];
+    // The inner watchdog owns the native process tree. Killing only an npm wrapper
+    // on spawnSync timeout could otherwise leave the sandbox helper behind.
+    const result = spawnSync(process.execPath, [...watchdog, '--idle-ms=30000', '--total-ms=30000', '--', probe.command, ...probe.args], { cwd: inv.cwd, env: prepared.env, shell: false, windowsHide: true, encoding: 'utf8', timeout: 90_000, maxBuffer: 64 * 1024 });
+    if (result.status !== 0 || !result.stdout?.includes('YOKE_SHELL_OK')) {
+        const signature = /CreateProcessAsUserW failed:\s*-?\d+/u.exec(result.stderr ?? '')?.[0];
+        throw Error(`Codex sandbox preflight failed (${signature ?? result.error?.code ?? result.status ?? 'no completion'}); no model started. Check native PowerShell and Codex sandbox setup.`);
+    }
+    return { ...resolveWindowsCommand(inv.command, [...inv.args, ...config], prepared.env), ...prepared };
+}

package/dist/change/inbox.js

@@ -1,4 +1,8 @@
 import { assessmentInstructions } from "../routing/assessment.js";
+import { bindAssessments, preparedProblems } from '../prd/assess.js';
+import { loadConfig } from '../retrofit/config.js';
+import { resolvePlanner } from '../routing/planning.js';
+import { readPlanningFile } from '../routing/contracts.js';
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
@@ -88,13 +92,14 @@ export function pendingChanges(targetDir) {
         .map(name => ChangeRequestSchema.parse(JSON.parse(readFileSync(join(dir, name), 'utf8'))))
         .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
 }
-export function buildChangePrompt(request, proposalPath, stories) {
+export function buildChangePrompt(request, proposalPath, stories, brief = '') {
     return [
         'You are planning one newly requested product change for the Yoke autonomous loop.',
         `Change request ${request.id}: ${request.request}`,
         '',
         'Create an append-only proposal: add small new stories; never rewrite or delete existing stories.',
         assessmentInstructions,
+        ...(brief ? ['Approved planning brief:', brief] : []),
         `Existing story IDs: ${stories.map(story => story.id).join(', ') || '(none)'}`,
         'Every proposed story must have passes: false and 2-5 structured acceptance criteria.',
         'Every criterion must have a stable id, behavioral text, and one or more executable verify commands.',
@@ -128,6 +133,9 @@ function archiveRequest(targetDir, request) {
     rmSync(reviewFile(targetDir, request.id), { force: true });
 }
 export function runChangeApply(targetDir, opts) {
+    const config = loadConfig(targetDir);
+    const planner = resolvePlanner(config, opts.runner, opts.selection);
+    opts = { ...opts, runner: planner.agent, selection: planner.selection };
     let requests;
     try {
         requests = pendingChanges(targetDir);
@@ -170,15 +178,16 @@ export function runChangeApply(targetDir, opts) {
     if (!available(reviewer))
         return { ok: false, added: 0, summary: `reviewer CLI "${reviewer}" is unavailable`, changeId: request.id };
     const proposal = proposalFile(targetDir, request.id);
+    const brief = readPlanningFile(targetDir, '.yoke/plan.md', 80_000) ?? '';
     const plannerDir = changesDir(targetDir);
     mkdirSync(plannerDir, { recursive: true });
     rmSync(proposal, { force: true });
-    const base = agentInvocation(opts.runner, buildChangePrompt(request, proposal, existing), plannerDir, opts.permissions ?? 'safe', opts.selection);
+    const base = agentInvocation(opts.runner, buildChangePrompt(request, proposal, existing, brief), plannerDir, opts.permissions ?? 'safe', opts.selection);
     const invocation = buildWatchdogInvocation(base, opts.timeoutMs ?? 0);
     const result = (opts.run ?? runAgent)(invocation);
     if (!result.success)
         return { ok: false, added: 0, summary: `planner failed: ${result.summary}`, changeId: request.id };
-    if (readFileSync(prdPath, 'utf8') !== existingText) {
+    if (readFileSync(prdPath, 'utf8') !== existingText || (readPlanningFile(targetDir, '.yoke/plan.md', 80_000) ?? '') !== brief) {
         return {
             ok: false,
             added: 0,
@@ -221,12 +230,19 @@ export function runChangeApply(targetDir, opts) {
         }
         proposedIds.add(story.id);
     }
-    const appended = proposed.map(story => ({ ...story, sourceChange: request.id }));
+    let appended = proposed.map(story => ({ ...story, sourceChange: request.id }));
     const dependencyIssues = validateDependencies([...existing, ...appended]);
     if (dependencyIssues.length > 0) {
         return { ok: false, added: 0, summary: `invalid combined dependency graph: ${dependencyIssues.join('; ')}`, changeId: request.id };
     }
     const reviewPath = reviewFile(targetDir, request.id);
+    const bound = bindAssessments([...existing, ...appended], brief);
+    appended = bound.slice(existing.length).map(s => ({ ...s, sourceChange: request.id }));
+    if (config?.routing?.assessmentPolicy === 'prepared') {
+        const issues = preparedProblems(bound, brief).filter(issue => appended.some(s => issue.startsWith(s.id + ':')));
+        if (issues.length)
+            return { ok: false, added: 0, summary: issues.join('; '), changeId: request.id };
+    }
     rmSync(reviewPath, { force: true });
     const reviewBase = agentInvocation(reviewer, buildChangeReviewPrompt(request, reviewPath, appended), plannerDir, opts.permissions ?? 'safe', reviewer === opts.runner ? opts.selection : undefined);
     const reviewInvocation = buildWatchdogInvocation(reviewBase, opts.timeoutMs ?? 0);
@@ -234,7 +250,7 @@ export function runChangeApply(targetDir, opts) {
     if (!reviewResult.success) {
         return { ok: false, added: 0, summary: `coverage review failed: ${reviewResult.summary}`, changeId: request.id };
     }
-    if (readFileSync(prdPath, 'utf8') !== existingText) {
+    if (readFileSync(prdPath, 'utf8') !== existingText || (readPlanningFile(targetDir, '.yoke/plan.md', 80_000) ?? '') !== brief) {
         return {
             ok: false, added: 0,
             summary: 'PRD changed while the coverage reviewer was running; refusing to overwrite concurrent or out-of-contract edits',

package/dist/cli.js

@@ -13,6 +13,7 @@ import { runReview } from './review/command.js';
 import { scanDir } from './scan/design.js';
 import { runNew } from './new/command.js';
 import { runPrdDraft, runPrdCheck } from './prd/command.js';
+import { runPrdAssess } from './prd/assess.js';
 import { runLoopCleanup } from './loop/cleanup.js';
 import { runFlowSmoke } from './smoke/command.js';
 import { maybeNotifyUpdate, currentYokeVersion } from './update/check.js';
@@ -550,6 +551,14 @@ export function main(argv) {
         case 'prd': {
             const sub = rest[0];
             const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            if (sub === 'assess') {
+                const runner = rest.find(a => a.startsWith('--runner='))?.slice('--runner='.length);
+                if (runner && !['codex', 'claude', 'gemini'].includes(runner)) {
+                    console.error('Invalid planning runner');
+                    return 1;
+                }
+                return runPrdAssess(targetDir, { runner: runner, story: rest.find(a => a.startsWith('--story='))?.slice('--story='.length), reassess: rest.includes('--reassess') });
+            }
             if (sub === 'draft') {
                 const idea = rest.find(a => a.startsWith('--idea='))?.slice('--idea='.length);
                 if (!idea) {
@@ -577,7 +586,7 @@ export function main(argv) {
             }
             if (sub === 'check')
                 return runPrdCheck(targetDir);
-            console.log('usage: yoke prd <draft|check> [dir] [--idea="..."] [--runner=<claude|codex|gemini>] [--force] [--timeout=<minutes>]');
+            console.log('usage: yoke prd <draft|check|assess> [dir] [--idea="..."] [--runner=<claude|codex|gemini>] [--story=<id>] [--reassess] [--force] [--timeout=<minutes>]');
             return 1;
         }
         case 'context': {
@@ -642,7 +651,7 @@ export function main(argv) {
             return runUpgrade();
         default:
             console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
-            console.log('usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | change <add|status> [dir] | prd <draft|check> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>');
+            console.log('usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | change <add|status> [dir] | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>');
             return cmd ? 1 : 0;
     }
 }