@evomap/evolver-core 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/events/retention.js

@@ -1,24 +1,29 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { material } from '../schema/material.js';
+import { inspectMaterialArchive, planMaterialArchive, readMaterialHistory, } from '../material/materialArchive.js';
 import { rootEvent } from './eventSchema.js';
+import { ArchiveSegmentConflictError, inspectRootEventArchive, readRootEventHistory, RootEventHistoryGapError, ROOT_EVENT_ARCHIVE_DEFAULT_KEEP_EVENTS, validateRootEventHistory, } from './eventArchive.js';
 import { materialStorePath as defaultMaterialStorePath, rootEventsPath as defaultRootEventsPath } from './paths.js';
-import { NARRATIVE_MAX_LIMIT } from './reports.js';
 export const RETENTION_DEFAULT_MAX_ROOT_EVENTS = 100_000;
 export const RETENTION_DEFAULT_MAX_ROOT_BYTES = 64 * 1024 * 1024;
 export const RETENTION_DEFAULT_MAX_MATERIAL_RECORDS = 10_000;
 export const RETENTION_DEFAULT_MAX_MATERIAL_BYTES = 64 * 1024 * 1024;
 export const RETENTION_DEFAULT_WATCH_RATIO = 0.8;
-export const RETENTION_DEFAULT_ROOT_TAIL_EVENTS = Math.max(1_000, NARRATIVE_MAX_LIMIT);
+export const RETENTION_DEFAULT_ROOT_TAIL_EVENTS = ROOT_EVENT_ARCHIVE_DEFAULT_KEEP_EVENTS;
 export function defaultMaterialCursorPath(path = defaultMaterialStorePath()) {
     return join(dirname(path), 'cycle-consumer.json');
 }
+export function defaultMaterialCursorPaths(path = defaultMaterialStorePath()) {
+    return [defaultMaterialCursorPath(path), join(dirname(path), 'distill-consumer.json')];
+}
 export function buildRetentionReport(opts = {}) {
     const now = new Date((opts.now ?? Date.now)()).toISOString();
     const watchRatio = ratioOf(opts.watchRatio, RETENTION_DEFAULT_WATCH_RATIO);
     const rootPath = opts.rootEventsPath ?? defaultRootEventsPath();
     const materialPath = opts.materialStorePath ?? defaultMaterialStorePath();
-    const cursorPath = opts.materialCursorPath ?? defaultMaterialCursorPath(materialPath);
+    const cursorPaths = opts.materialCursorPaths
+        ?? (opts.materialCursorPath !== undefined ? [opts.materialCursorPath] : defaultMaterialCursorPaths(materialPath));
     const rootThresholds = {
         maxRecords: positiveInt(opts.maxRootEvents, RETENTION_DEFAULT_MAX_ROOT_EVENTS),
         maxBytes: positiveInt(opts.maxRootBytes, RETENTION_DEFAULT_MAX_ROOT_BYTES),
@@ -30,7 +35,7 @@ export function buildRetentionReport(opts = {}) {
         watchRatio,
     };
     const rootEvents = rootSnapshot(rootPath, rootThresholds, positiveInt(opts.protectRootTailEvents, RETENTION_DEFAULT_ROOT_TAIL_EVENTS));
-    const material = materialSnapshot(materialPath, cursorPath, materialThresholds);
+    const material = materialSnapshot(materialPath, cursorPaths, materialThresholds);
     const warnings = buildWarnings(rootEvents, material);
     const nextActions = buildNextActions(rootEvents, material);
     return {
@@ -45,6 +50,22 @@ export function buildRetentionReport(opts = {}) {
 }
 function rootSnapshot(path, thresholds, protectTailEvents) {
     const stats = readJsonl(path, (value) => rootEvent.parse(value));
+    const archive = inspectRootEventArchive(path);
+    const historyRecords = readRootEventHistory(path).length;
+    let historyConflicts = 0;
+    let historyGaps = 0;
+    let historyIntegrityErrors = 0;
+    try {
+        validateRootEventHistory(path);
+    }
+    catch (error) {
+        if (error instanceof ArchiveSegmentConflictError)
+            historyConflicts = 1;
+        else if (error instanceof RootEventHistoryGapError)
+            historyGaps = 1;
+        else
+            historyIntegrityErrors = 1;
+    }
     return {
         name: 'root_events',
         exists: stats.exists,
@@ -57,34 +78,67 @@ function rootSnapshot(path, thresholds, protectTailEvents) {
         lastSeq: stats.last?.seq ?? null,
         firstTs: stats.first?.ts ?? null,
         lastTs: stats.last?.ts ?? null,
+        archiveSegments: archive.segments,
+        archiveRecords: archive.records,
+        archiveBytes: archive.bytes,
+        archiveInvalidLines: archive.invalidLines,
+        historyRecords,
+        historyBytes: archive.bytes + stats.bytes,
+        historyConflicts,
+        historyGaps,
+        historyIntegrityErrors,
+        archiveRotationSupported: true,
+        archiveRotationSafe: stats.invalidLines === 0 && archive.invalidLines === 0 && historyConflicts === 0 && historyGaps === 0 && historyIntegrityErrors === 0,
         protectTailEvents: Math.min(stats.records, protectTailEvents),
         destructivePruneSafe: false,
-        reason: 'root_events is the replay and audit source; archive readers must exist before destructive prune is safe',
+        reason: 'archive rotation preserves replay history; destructive archive deletion remains disabled',
     };
 }
-function materialSnapshot(path, cursorPath, thresholds) {
+function materialSnapshot(path, cursorPaths, thresholds) {
     const stats = readJsonl(path, (value) => material.parse(value));
-    const cursor = readCycleCursor(cursorPath);
-    const cursorInRange = cursor.value >= 0 && cursor.value <= stats.records;
-    const effectiveCursor = cursorInRange ? cursor.value : clampCursor(cursor.value, stats.records);
+    const archive = inspectMaterialArchive(path);
+    const history = readMaterialHistory(path);
+    const historyRecords = history.length;
+    const cursors = readMaterialCursors(cursorPaths, historyRecords, archive.records);
+    const effectiveCursor = cursors.inRange ? cursors.cycle : clampCursor(cursors.cycle, historyRecords);
+    const effectiveMinimum = cursors.inRange ? cursors.min : clampCursor(cursors.min, historyRecords);
+    let archiveRotationSafe = stats.invalidLines === 0 && archive.invalidLines === 0 && cursors.valid && cursors.inRange;
+    if (archiveRotationSafe) {
+        try {
+            planMaterialArchive({ path, cursorPaths, keepRecords: 1 });
+        }
+        catch {
+            archiveRotationSafe = false;
+        }
+    }
     return {
         name: 'material',
-        exists: stats.exists,
+        exists: stats.exists || archive.exists,
         bytes: stats.bytes,
         records: stats.records,
         invalidLines: stats.invalidLines,
         state: retentionState(stats.records, stats.bytes, thresholds),
         thresholds,
-        firstCapturedAt: stats.first?.capturedAt ?? null,
-        lastCapturedAt: stats.last?.capturedAt ?? null,
-        cursorValid: cursor.valid,
-        cursorInRange,
-        cursor: cursor.value,
+        firstCapturedAt: history[0]?.capturedAt ?? null,
+        lastCapturedAt: history[history.length - 1]?.capturedAt ?? null,
+        archiveSegments: archive.segments,
+        archiveRecords: archive.records,
+        archiveBytes: archive.bytes,
+        archiveInvalidLines: archive.invalidLines,
+        historyRecords,
+        historyBytes: archive.bytes + stats.bytes,
+        cursorCount: cursors.count,
+        minCursor: effectiveMinimum,
+        cursorValid: cursors.valid,
+        cursorInRange: cursors.inRange,
+        cursor: cursors.cycle,
         effectiveCursor,
-        consumedPrefix: effectiveCursor,
-        pending: Math.max(0, stats.records - effectiveCursor),
+        consumedPrefix: effectiveMinimum,
+        pending: Math.max(0, historyRecords - effectiveCursor),
+        archiveRotationSupported: true,
+        archiveRotationSafe,
         destructivePruneSafe: false,
-        reason: 'material cursor is index-based; prune requires atomic archive plus cursor rewrite',
+        reason: 'archive rotation preserves absolute consumer cursors and full material history; destructive archive deletion remains disabled',
     };
 }
 function readJsonl(path, parse) {
@@ -111,19 +165,49 @@ function readJsonl(path, parse) {
     }
     return { exists: true, bytes, records, invalidLines, first, last };
 }
-function readCycleCursor(path) {
-    if (!existsSync(path))
-        return { exists: false, valid: true, value: 0 };
-    try {
-        const parsed = JSON.parse(readFileSync(path, 'utf8'));
-        if (typeof parsed.cycle === 'number' && Number.isFinite(parsed.cycle)) {
-            return { exists: true, valid: true, value: Math.floor(parsed.cycle) };
+function readMaterialCursors(paths, historyRecords, archiveRecords) {
+    let valid = true;
+    let inRange = true;
+    let cycle = 0;
+    let cycleFound = false;
+    const values = [];
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            valid = false;
+            continue;
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            valid = false;
+            continue;
+        }
+        for (const [group, value] of Object.entries(parsed)) {
+            if (!Number.isSafeInteger(value) || value < 0) {
+                valid = false;
+                continue;
+            }
+            const position = value;
+            values.push(position);
+            if (position > historyRecords)
+                inRange = false;
+            if (group === 'cycle' && !cycleFound) {
+                cycle = position;
+                cycleFound = true;
+            }
         }
-        return { exists: true, valid: false, value: 0 };
-    }
-    catch {
-        return { exists: true, valid: false, value: 0 };
     }
+    return {
+        valid,
+        inRange,
+        count: values.length,
+        cycle,
+        min: values.length === 0 ? archiveRecords : Math.min(...values),
+    };
 }
 function retentionState(records, bytes, thresholds) {
     if (records > thresholds.maxRecords || bytes > thresholds.maxBytes)
@@ -136,30 +220,42 @@ function buildWarnings(root, mat) {
     const out = [];
     if (root.invalidLines > 0)
         out.push(`root_events has ${root.invalidLines} invalid jsonl line(s); recover before rotating`);
+    if (root.archiveInvalidLines > 0)
+        out.push(`root_events archive has ${root.archiveInvalidLines} invalid jsonl line(s); repair archive integrity before rotating again`);
+    if (root.historyConflicts > 0)
+        out.push('root_events active/archive history has conflicting seq records; repair audit integrity before rotating');
+    if (root.historyGaps > 0)
+        out.push('root_events active/archive history has a seq gap; restore the missing audit segment before rotating');
+    if (root.historyIntegrityErrors > 0)
+        out.push('root_events history fails structural integrity checks; repair event ordering before rotating');
     if (mat.invalidLines > 0)
         out.push(`material store has ${mat.invalidLines} invalid jsonl line(s); inspect before rotating`);
     if (!mat.cursorValid)
         out.push('material cursor is unreadable; retention uses effectiveCursor=0 until the cursor is repaired');
     if (mat.cursorValid && !mat.cursorInRange)
-        out.push(`material cursor ${mat.cursor} is outside material record range 0..${mat.records}; retention uses effectiveCursor=${mat.effectiveCursor}`);
+        out.push(`material cursor ${mat.cursor} is outside material record range 0..${mat.historyRecords}; retention uses effectiveCursor=${mat.effectiveCursor}`);
     if (root.state === 'over_limit')
-        out.push('root_events exceeds retention thresholds; plan archive support before deleting audit lines');
+        out.push('root_events exceeds retention thresholds for the active log; preview archive rotation before writing');
+    if (mat.archiveInvalidLines > 0)
+        out.push(`material archive has ${mat.archiveInvalidLines} invalid jsonl line(s); repair archive integrity before rotating again`);
+    if (!mat.archiveRotationSafe)
+        out.push('material active/archive/cursor state is not safe for rotation; run archive-material preview after repairing integrity');
     if (mat.state === 'over_limit')
-        out.push('material store exceeds retention thresholds; archive consumed prefix only with cursor rewrite');
+        out.push('material active store exceeds retention thresholds; preview absolute-cursor archive rotation before writing');
     if (mat.pending > 0)
         out.push(`material store has ${mat.pending} pending record(s); do not prune pending material`);
     return out;
 }
 function buildNextActions(root, mat) {
     const out = [
-        'keep destructive prune disabled until archive readers are wired into reports, replay and cycle recovery',
+        'archive rotation is available; keep destructive prune disabled for archive deletion',
     ];
     if (root.state !== 'ok')
-        out.push(`root_events ${root.state}: keep at least the last ${root.protectTailEvents} event(s) active after future archive`);
+        out.push(`root_events ${root.state}: run retention archive-root preview, then keep at least the last ${root.protectTailEvents} active event(s)`);
     if (!mat.cursorValid || !mat.cursorInRange)
-        out.push('material: repair the cycle cursor before archiving consumed material');
-    if (mat.consumedPrefix > 0)
-        out.push(`material: ${mat.consumedPrefix} consumed prefix record(s) are archive candidates after atomic cursor rewrite exists`);
+        out.push('material: repair the cycle cursor and any other durable consumer cursor before archiving consumed material');
+    if (mat.consumedPrefix > mat.archiveRecords)
+        out.push(`material: ${mat.consumedPrefix - mat.archiveRecords} consumed prefix record(s) may be archived with archive-material without rewriting cursors`);
     if (mat.pending > 0)
         out.push('material: process or inspect pending records before any future prune');
     return out;

package/dist/exec/autoExec.js

@@ -122,6 +122,9 @@ export async function runAutoExecTask(deps, rawTask, safety) {
         const gi = intakeGene({
             category: 'repair', signals_match: cycleSignals, strategy: [...task.strategy],
             summary: task.expectedEffect.slice(0, 80), ...(task.validationCmds ? { validation: [...task.validationCmds] } : {}),
+            // A task's seeded strategy is an execution-entry seed (the operator/daemon supplied a learned strategy to
+            // run/evolve), not a skill/session transcription → `evolved` per V1 #302 classifyProvenance.
+            generation_meta: { source: 'evolved' },
         });
         if (gi.ok && gi.gene) {
             await deps.store.put(gi.gene);

package/dist/exec/claudeBridge.js

@@ -96,9 +96,32 @@ export function scrubAgentEnv(env, opts = {}) {
     for (const [k, v] of Object.entries(env)) {
         if (v === undefined)
             continue;
+        // Windows treats env keys case-insensitively, but plain JS objects can contain both PATH and Path. Package
+        // runners such as pnpm may prepend their bins to PATH while the inherited user executables remain in Path.
+        // Canonicalize those aliases below so the whitelist does not silently discard either half.
+        if (process.platform === 'win32' && k.toLowerCase() === 'path')
+            continue;
         if (allowKeys.has(k) || allowPrefixes.some((p) => k.startsWith(p)))
             out[k] = v;
     }
+    if (process.platform === 'win32') {
+        const pathValues = Object.entries(env)
+            .filter(([key, value]) => key.toLowerCase() === 'path' && value !== undefined)
+            .sort(([a], [b]) => a === 'PATH' ? -1 : b === 'PATH' ? 1 : 0)
+            .map(([, value]) => value);
+        const seen = new Set();
+        const merged = pathValues.flatMap((value) => value.split(';')).filter((entry) => {
+            if (!entry)
+                return false;
+            const key = entry.toLowerCase();
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        if (merged.length > 0)
+            out['PATH'] = merged.join(';');
+    }
     return out;
 }
 /** Default git runner: spawn `git <args>` in cwd, return stdout (empty string on error). Env scrubbed — git never needs evolver/hub secrets. */

package/dist/exec/runnerRegistry.d.ts

@@ -20,20 +20,21 @@ export declare class UnboundedSkipPermissionsError extends Error {
 export declare class UnsupportedCursorSkipPermissionsError extends Error {
     constructor();
 }
-/** Thrown when Cursor's built-in runner is requested on Windows before its launcher path is run-verified. */
+/** Thrown when Cursor's Windows installation cannot be reduced to a shell-free node.exe + index.js launch. */
 export declare class UnsupportedCursorWindowsRunnerError extends Error {
     constructor();
 }
-export declare function assertCursorRunnerPlatformSupported(platform?: NodeJS.Platform): void;
+export declare function assertCursorRunnerPlatformSupported(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): void;
 /**
  * Make a bare command name spawnable shell-free on Windows. `spawn(shell:false)` cannot execute an npm CLI
  * shim (a `.cmd`/`.bat`), and routing through a shell would expose the prompt arg to cmd.exe quoting
  * (injection). npm shims are node wrappers, so we resolve the bare name on PATH and, when it's a node shim,
- * run `node <entry.js>` directly (shell-free, args passed safely). A native `.exe` (claude) resolves to itself.
- * No-op on POSIX and for any command that is already a path or has an extension. Surfaced by codex on Windows
- * (codex is `codex.cmd`, while claude is `claude.exe`), #66.
+ * run `node <entry.js>` directly. Cursor's installer uses a PowerShell shim around a bundled
+ * `versions/<version>/node.exe + index.js`; that known layout is resolved directly too, without invoking
+ * cmd.exe or PowerShell. A native `.exe` (claude) resolves to itself. No-op on POSIX and for any command that
+ * is already a path or has an extension. Surfaced by codex/cursor-agent on Windows (#66).
  */
-export declare function resolveSpawnCommand(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv): {
+export declare function resolveSpawnCommand(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): {
     cmd: string;
     args: string[];
 };
@@ -49,6 +50,7 @@ export declare function spawnCapture(cmd: string, args: readonly string[], opts:
     timeoutMs: number;
     input?: string;
     env?: NodeJS.ProcessEnv;
+    resolvePlatform?: NodeJS.Platform;
 }): Promise<{
     code: number | null;
     stdout: string;

package/dist/exec/runnerRegistry.js

@@ -5,7 +5,7 @@
 // nothing here spawns a real agent in tests except through spawnCapture, which the bridge injects fakes around.
 import { spawn } from 'node:child_process';
 import { join as joinPath, delimiter as pathDelimiter } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 export const DEFAULT_TIMEOUT_MS = 600_000;
 /** Thrown when permission bypass is requested without bounding the agent's tools (would be an unbounded autonomous agent). */
 export class UnboundedSkipPermissionsError extends Error {
@@ -21,29 +21,34 @@ export class UnsupportedCursorSkipPermissionsError extends Error {
         this.name = 'UnsupportedCursorSkipPermissionsError';
     }
 }
-/** Thrown when Cursor's built-in runner is requested on Windows before its launcher path is run-verified. */
+/** Thrown when Cursor's Windows installation cannot be reduced to a shell-free node.exe + index.js launch. */
 export class UnsupportedCursorWindowsRunnerError extends Error {
     constructor() {
-        super('cursor runner on Windows is not yet supported/run-verified due to cursor-agent shim spawn issue; use claude/codex or an injected cursor runner until the Windows launcher is run-verified');
+        super('cursor runner on Windows could not resolve the installed cursor-agent bundle shell-free; reinstall/update cursor-agent or use claude/codex until node.exe + index.js are available');
         this.name = 'UnsupportedCursorWindowsRunnerError';
     }
 }
-export function assertCursorRunnerPlatformSupported(platform = process.platform) {
-    if (platform === 'win32')
+export function assertCursorRunnerPlatformSupported(platform = process.platform, env = process.env) {
+    if (platform !== 'win32')
+        return;
+    if (resolveSpawnCommand('cursor-agent', [], env, platform).cmd === 'cursor-agent') {
         throw new UnsupportedCursorWindowsRunnerError();
+    }
 }
 /**
  * Make a bare command name spawnable shell-free on Windows. `spawn(shell:false)` cannot execute an npm CLI
  * shim (a `.cmd`/`.bat`), and routing through a shell would expose the prompt arg to cmd.exe quoting
  * (injection). npm shims are node wrappers, so we resolve the bare name on PATH and, when it's a node shim,
- * run `node <entry.js>` directly (shell-free, args passed safely). A native `.exe` (claude) resolves to itself.
- * No-op on POSIX and for any command that is already a path or has an extension. Surfaced by codex on Windows
- * (codex is `codex.cmd`, while claude is `claude.exe`), #66.
+ * run `node <entry.js>` directly. Cursor's installer uses a PowerShell shim around a bundled
+ * `versions/<version>/node.exe + index.js`; that known layout is resolved directly too, without invoking
+ * cmd.exe or PowerShell. A native `.exe` (claude) resolves to itself. No-op on POSIX and for any command that
+ * is already a path or has an extension. Surfaced by codex/cursor-agent on Windows (#66).
  */
-export function resolveSpawnCommand(cmd, args, env = process.env) {
-    if (process.platform !== 'win32' || /[\\/]/.test(cmd) || /\.[a-z0-9]+$/i.test(cmd))
+export function resolveSpawnCommand(cmd, args, env = process.env, platform = process.platform) {
+    if (platform !== 'win32' || /[\\/]/.test(cmd) || /\.[a-z0-9]+$/i.test(cmd))
         return { cmd, args: [...args] };
-    for (const dir of (env['PATH'] ?? '').split(pathDelimiter).filter(Boolean)) {
+    const delimiter = platform === 'win32' ? ';' : pathDelimiter;
+    for (const dir of (env['PATH'] ?? '').split(delimiter).filter(Boolean)) {
         for (const ext of ['.exe', '.cmd', '.bat']) {
             const full = joinPath(dir, cmd + ext);
             if (!existsSync(full))
@@ -58,6 +63,11 @@ export function resolveSpawnCommand(cmd, args, env = process.env) {
                     if (existsSync(js))
                         return { cmd: process.execPath, args: [js, ...args] };
                 }
+                if (cmd.toLowerCase() === 'cursor-agent' && /cursor-agent\.ps1/i.test(shim)) {
+                    const cursor = resolveCursorAgentBundle(dir, args);
+                    if (cursor)
+                        return cursor;
+                }
             }
             catch { /* unreadable shim — keep searching */ }
             // A .cmd/.bat whose node entry we can't extract is NOT runnable shell-free — DON'T return it (that would
@@ -66,6 +76,44 @@ export function resolveSpawnCommand(cmd, args, env = process.env) {
     }
     return { cmd, args: [...args] };
 }
+function resolveCursorAgentBundle(dir, args) {
+    const direct = cursorBundleAt(dir, args);
+    if (direct)
+        return direct;
+    let versions;
+    try {
+        versions = readdirSync(joinPath(dir, 'versions'), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && cursorVersionKey(entry.name) !== undefined)
+            .map((entry) => entry.name)
+            .sort((a, b) => cursorVersionKey(b).localeCompare(cursorVersionKey(a)));
+    }
+    catch {
+        return undefined;
+    }
+    for (const version of versions) {
+        const resolved = cursorBundleAt(joinPath(dir, 'versions', version), args);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}
+function cursorBundleAt(dir, args) {
+    const node = joinPath(dir, 'node.exe');
+    const entry = joinPath(dir, 'index.js');
+    return existsSync(node) && existsSync(entry) ? { cmd: node, args: [entry, ...args] } : undefined;
+}
+function cursorVersionKey(version) {
+    const match = /^(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-(\d{1,2})-(\d{1,2})-(\d{1,2}))?-[a-f0-9]+$/i.exec(version);
+    if (!match)
+        return undefined;
+    const year = match[1];
+    const month = match[2];
+    const day = match[3];
+    const hour = match[4] ?? '0';
+    const minute = match[5] ?? '0';
+    const second = match[6] ?? '0';
+    return [year, month, day, hour, minute, second].map((part, index) => index === 0 ? part : part.padStart(2, '0')).join('');
+}
 /**
  * Promise wrapper over spawn (shell:false). Optionally writes `input` to stdin; resolves with stdout/exit.
  * On timeout the WHOLE process group is killed, not just the direct child (finding #39.5): an agent spawns
@@ -76,7 +124,7 @@ export function resolveSpawnCommand(cmd, args, env = process.env) {
 export function spawnCapture(cmd, args, opts) {
     return new Promise((resolve, reject) => {
         const detached = process.platform !== 'win32';
-        const r = resolveSpawnCommand(cmd, args, opts.env);
+        const r = resolveSpawnCommand(cmd, args, opts.env, opts.resolvePlatform ?? process.platform);
         const child = spawn(r.cmd, r.args, { cwd: opts.cwd, shell: false, detached, ...(opts.env ? { env: opts.env } : {}) });
         let stdout = '';
         let stderr = '';
@@ -185,10 +233,10 @@ export function makeCodexHeadlessRunner(opts = {}) {
 //   - `--model <model>` exists (e.g. gpt-5, sonnet-4, sonnet-4-thinking); `--list-models` enumerates.
 //   - auth: `CURSOR_API_KEY` or `--api-key` (the spec's envAllow prefix is CURSOR_).
 //   - cursor has its OWN `--sandbox enabled|disabled` and `-w/--worktree`; we still wrap with our git worktree.
-// STILL NOT run-verified end to end (needs an authed cursor-agent; claude/codex were each run-verified). Two known
-// gaps surfaced while testing: (1) on Windows `cursor-agent.cmd` is a powershell shim, NOT an npm node-shim, so
-// resolveSpawnCommand cannot rewrite it; the built-in runner fail-fasts there instead of surfacing ENOENT;
-// (2) the installed launcher's version-discovery regex rejects the real version dir name (Cursor's own bug).
+// STILL NOT run-verified end to end (needs an authed cursor-agent; claude/codex were each run-verified). The
+// Windows launcher is a PowerShell shim and its own version regex rejects the current timestamped version-dir
+// shape. resolveSpawnCommand therefore bypasses both scripts and runs the newest verified node.exe + index.js
+// bundle directly, shell-free. If that known bundle layout cannot be found, the runner still fail-fasts.
 //
 // SAFETY: `-p --force --trust` auto-approves shell+write with no verified per-run allowlist/sandbox mapping.
 // Until Cursor can really map agentOptions into per-run permissions, skipPermissions is refused outright. The
@@ -215,9 +263,14 @@ export function cursorRunnerArgs(opts = {}) {
 export function makeCursorHeadlessRunner(opts = {}, platform = process.platform) {
     const args = cursorRunnerArgs(opts);
     return async (prompt, ctx) => {
-        assertCursorRunnerPlatformSupported(platform);
+        assertCursorRunnerPlatformSupported(platform, ctx.env ?? process.env);
         try {
-            const r = await spawnCapture('cursor-agent', [...args, prompt], { cwd: ctx.cwd, timeoutMs: ctx.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(ctx.env ? { env: ctx.env } : {}) });
+            const r = await spawnCapture('cursor-agent', [...args, prompt], {
+                cwd: ctx.cwd,
+                timeoutMs: ctx.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                resolvePlatform: platform,
+                ...(ctx.env ? { env: ctx.env } : {}),
+            });
             return r.code === 0 ? { ok: true, output: r.stdout } : { ok: false, output: r.stdout, error: r.stderr || `exit ${r.code}` };
         }
         catch (e) {

package/dist/exec/selfPrObfuscation.d.ts

@@ -9,7 +9,8 @@ export declare function resetObfuscatedCache(reader?: ReadManifest): void;
 /**
  * Load the obfuscated-file set from the manifest. Returns a normalized Set, or null when the manifest is
  * missing / unreadable / structurally invalid (NOT an `obfuscate` array of literal string paths). null is the
- * fail-closed signal: the caller must then reject all files. Result is cached per reader.
+ * fail-closed signal: the caller must then reject all files. Success is cached per reader; failures retry briefly
+ * so startup-time transient filesystem errors do not disable self-PR until process restart.
  */
 export declare function loadObfuscatedFiles(readManifest: ReadManifest): Set<string> | null;
 /**

package/dist/exec/selfPrObfuscation.js

@@ -28,8 +28,10 @@ export function defaultReadManifest(repoRoot) {
         }
     };
 }
+const MANIFEST_TRANSIENT_RETRY_MS = 5 * 60 * 1000;
 // Resettable cache keyed by the reader identity, so distinct readers (e.g. per test) don't bleed into each other.
-// `null` = a load was attempted and FAILED (fail-closed); a Set = the loaded obfuscate paths.
+// Success is cached permanently for the reader. Failures remain fail-closed, but transient reads retry for a
+// short window before stabilizing to null for the process lifetime.
 const cache = new WeakMap();
 /** Test/maintenance hook: drop any cached load for a reader (or all readers) so the load path re-runs. */
 export function resetObfuscatedCache(reader) {
@@ -40,11 +42,15 @@ export function resetObfuscatedCache(reader) {
 /**
  * Load the obfuscated-file set from the manifest. Returns a normalized Set, or null when the manifest is
  * missing / unreadable / structurally invalid (NOT an `obfuscate` array of literal string paths). null is the
- * fail-closed signal: the caller must then reject all files. Result is cached per reader.
+ * fail-closed signal: the caller must then reject all files. Success is cached per reader; failures retry briefly
+ * so startup-time transient filesystem errors do not disable self-PR until process restart.
  */
 export function loadObfuscatedFiles(readManifest) {
-    if (cache.has(readManifest))
-        return cache.get(readManifest) ?? null;
+    const cached = cache.get(readManifest);
+    if (cached?.kind === 'loaded')
+        return cached.files;
+    if (cached?.kind === 'failed' && cached.stable)
+        return null;
     let result;
     try {
         const raw = readManifest();
@@ -63,9 +69,16 @@ export function loadObfuscatedFiles(readManifest) {
         result = new Set(manifest.obfuscate.map((f) => normalizeManifestPath(f)).filter(Boolean));
     }
     catch {
-        result = null; // fail-closed: an unreadable/invalid manifest rejects everything
+        const now = Date.now();
+        const firstFailedAt = cached?.kind === 'failed' ? cached.firstFailedAt : now;
+        cache.set(readManifest, {
+            kind: 'failed',
+            firstFailedAt,
+            stable: now - firstFailedAt >= MANIFEST_TRANSIENT_RETRY_MS,
+        });
+        return null; // fail-closed: an unreadable/invalid manifest rejects everything
     }
-    cache.set(readManifest, result);
+    cache.set(readManifest, { kind: 'loaded', files: result });
     return result;
 }
 /**

package/dist/hub/agentDirectory.d.ts

@@ -0,0 +1,90 @@
+export declare const AGENT_DIRECTORY_DEFAULT_LIMIT = 20;
+export declare const AGENT_DIRECTORY_MAX_LIMIT = 50;
+export declare const AGENT_DIRECTORY_DEFAULT_TIMEOUT_MS = 8000;
+export declare const AGENT_DIRECTORY_MAX_TIMEOUT_MS = 30000;
+export declare const AGENT_DIRECTORY_MAX_QUERY_LENGTH = 500;
+export declare const AGENT_DIRECTORY_MAX_SIGNAL_COUNT = 20;
+export declare const AGENT_DIRECTORY_MAX_SIGNAL_LENGTH = 64;
+export declare const AGENT_DIRECTORY_MAX_CURSOR_LENGTH = 256;
+export declare const AGENT_DIRECTORY_MAX_AGENT_ID_LENGTH = 128;
+export type AgentAvailability = 'online' | 'busy' | 'offline' | 'unknown';
+export type AgentDirectorySort = 'relevance' | 'reputation' | 'recent' | 'availability';
+export type SortOrder = 'asc' | 'desc';
+export interface AgentSearchRequest {
+    query?: string;
+    signals?: readonly string[];
+    availability?: AgentAvailability;
+    sort?: AgentDirectorySort;
+    order?: SortOrder;
+    cursor?: string;
+    limit?: number;
+    timeoutMs?: number;
+}
+export interface AgentTaskDiscoveryRequest {
+    title: string;
+    description?: string;
+    signals?: readonly string[];
+    availability?: AgentAvailability;
+    sort?: AgentDirectorySort;
+    order?: SortOrder;
+    cursor?: string;
+    limit?: number;
+    timeoutMs?: number;
+}
+export interface AgentDirectoryEntry {
+    agentId: string;
+    displayName?: string;
+    summary?: string;
+    capabilities?: string[];
+    domains?: string[];
+    score?: number;
+    reputation?: number;
+    completedTaskCount?: number;
+    availability?: AgentAvailability;
+    lastSeenAt?: number;
+}
+export interface AgentProfile {
+    agentId: string;
+    displayName?: string;
+    summary?: string;
+    capabilities?: string[];
+    domains?: string[];
+    reputation?: number;
+    completedTaskCount?: number;
+    availability?: AgentAvailability;
+    lastSeenAt?: number;
+}
+export interface AgentDirectoryPage {
+    items: AgentDirectoryEntry[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export type AgentDirectoryFailureCode = 'capability_unavailable' | 'permission_denied' | 'hub_unavailable' | 'timeout' | 'invalid_request' | 'invalid_response';
+export interface AgentDirectoryFailure {
+    code: AgentDirectoryFailureCode;
+    retryable: boolean;
+    message?: string;
+}
+export type AgentDirectoryResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AgentDirectoryFailure;
+};
+export interface AgentDirectoryCapability {
+    search(request: AgentSearchRequest): Promise<AgentDirectoryResult<AgentDirectoryPage>>;
+    getProfile(agentId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AgentDirectoryResult<AgentProfile | null>>;
+    discoverForTask(request: AgentTaskDiscoveryRequest): Promise<AgentDirectoryResult<AgentDirectoryPage>>;
+}
+export declare class AgentDirectoryInputError extends Error {
+    readonly code = "invalid_request";
+}
+export declare function normalizeAgentSearchRequest(input: AgentSearchRequest): Required<Pick<AgentSearchRequest, 'limit' | 'timeoutMs' | 'sort' | 'order'>> & AgentSearchRequest;
+export declare function normalizeAgentTaskDiscoveryRequest(input: AgentTaskDiscoveryRequest): AgentTaskDiscoveryRequest & Required<Pick<AgentTaskDiscoveryRequest, 'limit' | 'timeoutMs' | 'sort' | 'order'>>;
+export declare function normalizeAgentId(value: string): string;
+export declare function normalizeAgentDirectoryTimeout(value: number | undefined): number;
+export declare function capabilityUnavailable(message?: string): AgentDirectoryResult<never>;
+export declare function unsupportedAgentDirectoryCapability(message?: string): AgentDirectoryCapability;