brainclaw 1.28.1 → 1.28.3

package/dist/core/code-map/cascade-jobs.js

@@ -0,0 +1,174 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { loadConfig } from '../config.js';
+import { writeFileAtomic } from '../io.js';
+import { codeMapDir } from './paths.js';
+import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+export function summarizeCascadeRefreshJob(job) {
+    const { result, ...summary } = job;
+    if (!result)
+        return summary;
+    const projects = [result.root_result, ...result.children];
+    const outcomeCounts = {};
+    for (const project of projects)
+        outcomeCounts[project.outcome] = (outcomeCounts[project.outcome] ?? 0) + 1;
+    const problemProjects = projects
+        .filter((project) => project.outcome !== 'indexed')
+        .map((project) => ({ path: project.path, outcome: project.outcome, ...(project.reason ? { reason: project.reason } : {}), ...(project.error ? { error: project.error } : {}) }));
+    return { ...summary, outcome_counts: outcomeCounts, ...(problemProjects.length ? { problem_projects: problemProjects } : {}) };
+}
+function jobsDir(root) {
+    return path.join(codeMapDir(root), 'cascade-jobs');
+}
+function jobPath(root, jobId) {
+    return path.join(jobsDir(root), `${jobId}.json`);
+}
+function writeJob(job) {
+    const dir = jobsDir(job.root);
+    fs.mkdirSync(dir, { recursive: true });
+    const target = jobPath(job.root, job.job_id);
+    writeFileAtomic(target, `${JSON.stringify(job, null, 2)}\n`);
+}
+export function readCascadeRefreshJob(root, jobId) {
+    try {
+        return JSON.parse(fs.readFileSync(jobPath(path.resolve(root), jobId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function latestCascadeRefreshJob(root) {
+    const dir = jobsDir(path.resolve(root));
+    try {
+        const jobs = fs.readdirSync(dir)
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((job) => job !== null)
+            .sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        return jobs[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function processAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function startCascadeRefreshJob(root, scope) {
+    const resolvedRoot = path.resolve(root);
+    try {
+        if (loadConfig(resolvedRoot).project_mode !== 'multi-project')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const previous = latestCascadeRefreshJob(resolvedRoot);
+    if (previous && (previous.status === 'queued' || previous.status === 'running') && processAlive(previous.pid)) {
+        return previous;
+    }
+    const now = new Date().toISOString();
+    const job = {
+        job_id: `cmj_${crypto.randomBytes(8).toString('hex')}`,
+        root: resolvedRoot,
+        scope,
+        status: 'queued',
+        created_at: now,
+        updated_at: now,
+        projects_total: inspectNestedProjects(resolvedRoot).projects.length + 1,
+        projects_completed: 0,
+        current_project: null,
+    };
+    writeJob(job);
+    const worker = fileURLToPath(new URL('./cascade-worker.js', import.meta.url));
+    const child = spawn(process.execPath, [worker, resolvedRoot, job.job_id, scope], {
+        cwd: resolvedRoot,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    const markWorkerExit = (detail) => {
+        const current = readCascadeRefreshJob(resolvedRoot, job.job_id);
+        if (!current || current.status === 'completed' || current.status === 'failed')
+            return;
+        const completed = new Date().toISOString();
+        writeJob({
+            ...current,
+            status: 'failed',
+            error: detail,
+            current_project: null,
+            completed_at: completed,
+            updated_at: completed,
+        });
+    };
+    child.once('error', (error) => {
+        markWorkerExit(`cascade worker failed to start: ${error.message}`);
+    });
+    child.once('exit', (code, signal) => {
+        // The worker writes its terminal state synchronously before exiting. If no
+        // terminal state exists here, the launch/runtime failed outside its guard.
+        markWorkerExit(`cascade worker exited before completion (code=${code ?? 'null'}, signal=${signal ?? 'none'})`);
+    });
+    child.unref();
+    const current = readCascadeRefreshJob(resolvedRoot, job.job_id) ?? job;
+    if (current.status === 'queued') {
+        current.pid = child.pid;
+        current.updated_at = new Date().toISOString();
+        writeJob(current);
+    }
+    return current;
+}
+/** Worker entry seam, exported for deterministic tests and the tiny worker file. */
+export async function runCascadeRefreshJob(root, jobId, scope) {
+    const job = readCascadeRefreshJob(root, jobId);
+    if (!job)
+        throw new Error(`cascade job not found: ${jobId}`);
+    const started = new Date().toISOString();
+    writeJob({ ...job, status: 'running', pid: process.pid, started_at: started, updated_at: started });
+    try {
+        const result = await refreshWorkspaceCascade({
+            rootCwd: root,
+            scope,
+            onProgress: (progress) => {
+                const current = readCascadeRefreshJob(root, jobId) ?? job;
+                writeJob({
+                    ...current,
+                    status: 'running',
+                    pid: process.pid,
+                    projects_total: progress.total,
+                    projects_completed: progress.completed,
+                    current_project: progress.current_project,
+                    ...(progress.last_result ? { last_result: progress.last_result } : {}),
+                    updated_at: new Date().toISOString(),
+                });
+            },
+        });
+        const current = readCascadeRefreshJob(root, jobId) ?? job;
+        const completed = new Date().toISOString();
+        writeJob({ ...current, status: 'completed', result, current_project: null, projects_completed: current.projects_total, completed_at: completed, updated_at: completed });
+    }
+    catch (error) {
+        const current = readCascadeRefreshJob(root, jobId) ?? job;
+        const completed = new Date().toISOString();
+        writeJob({ ...current, status: 'failed', error: error instanceof Error ? error.message : String(error), current_project: null, completed_at: completed, updated_at: completed });
+    }
+}
+//# sourceMappingURL=cascade-jobs.js.map

package/dist/core/code-map/cascade-worker.js

@@ -0,0 +1,15 @@
+import { runCascadeRefreshJob } from './cascade-jobs.js';
+const [root, jobId, rawScope] = process.argv.slice(2);
+if (!root || !jobId)
+    process.exit(2);
+const scope = rawScope === 'all' ? 'all' : 'changed';
+try {
+    await runCascadeRefreshJob(root, jobId, scope);
+    // Tree-sitter/native handles can keep Node's event loop alive after the
+    // durable terminal record has been flushed. This process owns no other work.
+    process.exit(0);
+}
+catch {
+    process.exit(1);
+}
+//# sourceMappingURL=cascade-worker.js.map

package/dist/core/code-map/cascade.js

@@ -20,7 +20,7 @@
  * refreshes existing brainclaw projects, it does not initialise new ones.
  */
 import path from 'node:path';
-import { scanNestedBrainclawProjects } from '../workspace-projects.js';
+import { scanNestedBrainclawProjectsDetailed } from '../workspace-projects.js';
 import { loadConfig } from '../config.js';
 import { refresh as runRefresh } from './refresh.js';
 import { readManifest } from './store.js';
@@ -54,10 +54,14 @@ function projectIdFor(cwd, fallbackId) {
  * cascade and the `status --cascade` recap so both agree on the project set.
  */
 export function listNestedProjects(rootCwd) {
+    return inspectNestedProjects(rootCwd).projects;
+}
+export function inspectNestedProjects(rootCwd) {
     const root = path.resolve(rootCwd);
-    return Array.from(new Set(scanNestedBrainclawProjects(root)
-        .map((c) => path.resolve(c.path))
-        .filter((abs) => abs !== root && isStrictlyUnder(abs, root)))).sort();
+    const discovered = scanNestedBrainclawProjectsDetailed(root);
+    return { projects: Array.from(new Set(discovered.projects
+            .map((c) => path.resolve(c.path))
+            .filter((abs) => abs !== root && isStrictlyUnder(abs, root)))).sort(), truncated: discovered.truncated };
 }
 /**
  * Refresh the whole multi-project workspace: every nested brainclaw project +
@@ -68,7 +72,8 @@ export async function refreshWorkspaceCascade(input) {
     const rootCwd = path.resolve(input.rootCwd);
     // Enumerate nested brainclaw projects strictly under the root (FS scan, so it
     // is strategy-agnostic). De-dup + sort by path for deterministic output.
-    const childAbsPaths = listNestedProjects(rootCwd);
+    const discovery = inspectNestedProjects(rootCwd);
+    const childAbsPaths = discovery.projects;
     // Every project to refresh, root first.
     const allProjects = [rootCwd, ...childAbsPaths];
     const refreshOne = async (projectCwd, isRoot) => {
@@ -77,40 +82,72 @@ export async function refreshWorkspaceCascade(input) {
         const nestedUnder = allProjects.filter((p) => p !== projectCwd && isStrictlyUnder(p, projectCwd));
         const extraIgnorePatterns = nestedUnder.map((p) => `${toPosix(path.relative(projectCwd, p))}/**`);
         const projectId = projectIdFor(projectCwd);
-        const result = await runRefresh({
-            projectId,
-            projectRoot: projectCwd,
-            scope: input.scope,
-            cwd: projectCwd,
-            extraIgnorePatterns,
-            ownerAgent: input.ownerAgent ?? null,
-            ownerAgentId: input.ownerAgentId ?? null,
-        });
-        return {
-            path: isRoot ? '.' : toPosix(path.relative(rootCwd, projectCwd)),
-            project_id: projectId,
-            is_root: isRoot,
-            ran: result.ran,
-            lock_acquired: result.lock_acquired,
-            files_parsed: result.files_parsed,
-            files_compacted: result.files_compacted,
-            freshness: result.freshness.status,
-            ...(result.lock_status ? { lock_status: result.lock_status } : {}),
-        };
+        const projectPath = isRoot ? '.' : toPosix(path.relative(rootCwd, projectCwd));
+        try {
+            const result = await runRefresh({
+                projectId,
+                projectRoot: projectCwd,
+                scope: input.scope,
+                cwd: projectCwd,
+                extraIgnorePatterns,
+                ownerAgent: input.ownerAgent ?? null,
+                ownerAgentId: input.ownerAgentId ?? null,
+            });
+            const filesIndexed = readManifest(projectCwd)?.stats.files_indexed ?? 0;
+            const outcome = !result.lock_acquired
+                ? 'locked'
+                : filesIndexed === 0 ? 'no_eligible_files' : 'indexed';
+            return {
+                path: projectPath,
+                project_id: projectId,
+                is_root: isRoot,
+                ran: result.ran,
+                lock_acquired: result.lock_acquired,
+                files_parsed: result.files_parsed,
+                files_compacted: result.files_compacted,
+                files_indexed: filesIndexed,
+                freshness: result.freshness.status,
+                outcome,
+                ...(outcome === 'no_eligible_files' ? { reason: 'no eligible source files found' } : {}),
+                ...(result.lock_status ? { lock_status: result.lock_status, reason: result.lock_status } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                path: projectPath,
+                project_id: projectId,
+                is_root: isRoot,
+                ran: false,
+                lock_acquired: false,
+                files_parsed: 0,
+                files_compacted: 0,
+                files_indexed: readManifest(projectCwd)?.stats.files_indexed ?? null,
+                freshness: 'partial',
+                outcome: 'failed',
+                reason: 'refresh_failed',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
     };
     // Children first, then the root (sequential — each holds its own project lock
     // briefly; never blocks bclaw_work, rule 8).
     const children = [];
+    const total = childAbsPaths.length + 1;
+    input.onProgress?.({ completed: 0, total, current_project: childAbsPaths[0] ? toPosix(path.relative(rootCwd, childAbsPaths[0])) : '.' });
     for (const childCwd of childAbsPaths) {
-        children.push(await refreshOne(childCwd, false));
+        const result = await refreshOne(childCwd, false);
+        children.push(result);
+        input.onProgress?.({ completed: children.length, total, current_project: children.length < childAbsPaths.length ? toPosix(path.relative(rootCwd, childAbsPaths[children.length])) : '.', last_result: result });
     }
     const rootResult = await refreshOne(rootCwd, true);
+    input.onProgress?.({ completed: total, total, current_project: null, last_result: rootResult });
     return {
         is_cascade: true,
         root: rootCwd,
         root_result: rootResult,
         children,
         children_refreshed: children.length,
+        discovery_truncated: discovery.truncated,
     };
 }
 //# sourceMappingURL=cascade.js.map

package/dist/core/code-map/query.js

@@ -232,7 +232,7 @@ export function isTestPath(p) {
 /**
  * Score a symbol index entry against the query. Matching is separator/case
  * INSENSITIVE (pln#601): an exact NORMALIZED match scores highest, then prefix,
- * then substring, then the sub-token floor. Exported symbols + components/hooks
+ * then substring; sub-token-only candidates score zero. Exported symbols + components/hooks
  * get a small boost; test-file symbols are biased DOWN so a test helper never
  * outranks the real definition of the same name (the Fable-audit brief-noise
  * companion to the find defect). Exported for focused ranking tests.
@@ -250,7 +250,7 @@ export function scoreEntry(entry, query) {
     else if (name.includes(q))
         score += 3; // substring
     else
-        score += 1; // matched only via a sub-token bucket
+        return 0; // shared-token noise is not a match
     score *= entry.score_hint; // exported (1.0) vs internal (0.8)
     if (entry.subtype === 'component' || entry.subtype === 'hook')
         score += 1;
@@ -367,6 +367,9 @@ export function findInStore(query, ctx, checker, acc) {
         const confident = validateEntry(entry, checker, acc, root, maxBytes, ctx.cwd, ctx.preferredDirName);
         if (!confident)
             continue;
+        const score = scoreEntry(entry, query);
+        if (score <= 0)
+            continue;
         ranked.push({
             match: {
                 node_id: entry.node_id,
@@ -375,7 +378,7 @@ export function findInStore(query, ctx, checker, acc) {
                 file_id: entry.file_id,
                 kind: entry.kind,
                 subtype: entry.subtype ?? null,
-                score: scoreEntry(entry, query),
+                score,
             },
             centrality: importCentrality(entry, resolutionIndex),
         });

package/dist/core/entity-operations.js

@@ -15,6 +15,7 @@
  */
 import path from 'node:path';
 import { loadState, mutateState } from './state.js';
+import { detectDuplicates } from './duplicates.js';
 import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
 import { findActiveClaimsForPlan, listClaims, loadClaim, logCascadeReleaseResult, markClaimStale, releaseClaimsCascade, releaseClaimWithCascade, saveClaim, } from './claims.js';
@@ -511,6 +512,19 @@ export function getEntity(name, idOrShortLabel, cwd) {
 // ─── CREATE ────────────────────────────────────────────────────────────
 export function createEntity(name, data, cwd) {
     assertKnownEntity(name, 'create');
+    const proximityKinds = new Set(['decision', 'constraint', 'trap']);
+    const nearby = proximityKinds.has(name) && typeof data.text === 'string'
+        ? detectDuplicates(data.text, name, loadState(cwd), listCandidates(undefined, cwd).filter((candidate) => candidate.status === 'pending')).slice(0, 3).map((match) => ({
+            id: match.id,
+            source: match.source,
+            reason: match.reason,
+            preview: match.text.length > 160 ? `${match.text.slice(0, 157)}…` : match.text,
+        }))
+        : [];
+    const result = (base) => ({
+        ...base,
+        ...(nearby.length ? { nearby_items: nearby } : {}),
+    });
     switch (name) {
         case 'plan': {
             // Explicit field whitelist + required-author check brings plan create in line
@@ -530,7 +544,7 @@ export function createEntity(name, data, cwd) {
                 estimatedEffort: data.estimated_effort,
             }, cwd);
             stampProvenanceOnStateItem('plan', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'decision': {
             const res = createDecision({
@@ -542,7 +556,7 @@ export function createEntity(name, data, cwd) {
                 planId: data.plan_id,
             }, cwd);
             stampProvenanceOnStateItem('decision', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'constraint': {
             const res = createConstraint({
@@ -553,7 +567,7 @@ export function createEntity(name, data, cwd) {
                 relatedPaths: data.related_paths,
             }, cwd);
             stampProvenanceOnStateItem('constraint', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'trap': {
             const res = createTrap({
@@ -564,7 +578,7 @@ export function createEntity(name, data, cwd) {
                 relatedPaths: data.related_paths,
             }, cwd);
             stampProvenanceOnStateItem('trap', res.id, defaultProvenance(data), cwd);
-            return { entity: name, id: res.id, short_label: res.shortLabel };
+            return result({ entity: name, id: res.id, short_label: res.shortLabel });
         }
         case 'runtime_note': {
             const id = generateId('runtime_note');

package/dist/core/execution-adapters.js

@@ -197,13 +197,27 @@ export function withCodexWorkspaceRoot(invoke, agent, worktreePath, isWin32 = pr
     args.splice(insertAt, 0, '--cd', worktreePath);
     const quote = (value) => isWin32
         ? `"${value.replace(/"/g, '""')}"`
-        : `'${value.replace(/'/g, `'\\''`)}'`;
-    const flags = `--cd ${quote(worktreePath)}`;
-    const prefix = invoke.executable;
-    const suffix = invoke.bashCommand.startsWith(`${prefix} `)
-        ? invoke.bashCommand.slice(prefix.length + 1)
-        : invoke.bashCommand;
-    return { ...invoke, args, bashCommand: `${prefix} ${flags} ${suffix}` };
+        : `"${value.replace(/\\/g, '\\\\').replace(/\$/g, '\\$').replace(/`/g, '\\`').replace(/"/g, '\\"')}"`;
+    // Re-render from structured argv. bashCommand also contains the model-authored
+    // prompt, so searching it for "| codex" can mistake prompt data for the real
+    // executable boundary and splice --cd inside quoted content.
+    const command = [invoke.executable, ...args.map(quote)].join(' ');
+    const prompt = invoke.promptText ?? '';
+    const escapedPrompt = prompt.replace(/'/g, "'\\''");
+    let bashCommand = command;
+    if (!isWin32 && invoke.promptDelivery === 'stdin_pipe') {
+        bashCommand = `printf '%s' '${escapedPrompt}' | ${command}`;
+    }
+    else if (!isWin32 && invoke.promptDelivery === 'temp_file' && invoke.tempFilePath) {
+        bashCommand = `printf '%s' '${escapedPrompt}' > ${quote(invoke.tempFilePath)} && ${command}`;
+    }
+    return { ...invoke, args, bashCommand };
+}
+/** Refuse a stdin-delivery invoke that would otherwise inherit `/dev/null`. */
+export function assertPromptDelivery(invoke) {
+    if (invoke.promptDelivery === 'stdin_pipe' && !invoke.promptText?.trim()) {
+        throw new Error('Invalid stdin_pipe invocation: promptText is empty; refusing to spawn an agent with ignored stdin.');
+    }
 }
 export class CliExecutionAdapter {
     id = 'cli';
@@ -273,6 +287,7 @@ export class CliExecutionAdapter {
         };
     }
     start(invoke, options) {
+        assertPromptDelivery(invoke);
         const isWin32 = process.platform === 'win32';
         invoke = withCodexWorkspaceRoot(invoke, options.agent, options.worktreePath, isWin32);
         // F7 (trp_0e5150d3): route worker env through buildWorkerIdentityEnv so the
@@ -309,7 +324,7 @@ export class CliExecutionAdapter {
         }
         const spawnExecutable = resolvedExecutable ?? invoke.executable;
         const useShell = isWin32 && /\.(cmd|bat)$/i.test(spawnExecutable);
-        const needsStdin = invoke.promptDelivery === 'stdin_pipe' && invoke.promptText;
+        const needsStdin = invoke.promptDelivery === 'stdin_pipe';
         // pln#520 step 4: when we ack-wrap, the SHELL redirects stdout/stderr to the
         // per-assignment log files (fds passed via stdio are NOT inherited through
         // the cmd.exe → .cmd → node shim — the empty-logs bug of can_f792cacd), and

package/dist/core/hygiene-policy.js

@@ -25,7 +25,8 @@ import { logger } from './logger.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 export const DEFAULT_HYGIENE_POLICY = {
     disabled: false,
-    assignment_offered_ttl_ms: 3 * DAY_MS,
+    // A never-accepted dispatch should not survive into the next day's dogfood.
+    assignment_offered_ttl_ms: 1 * DAY_MS,
     assignment_accepted_ttl_ms: 1 * DAY_MS,
     assignment_started_ttl_ms: 1 * DAY_MS,
     handoff_closed_ttl_ms: 30 * DAY_MS,

package/dist/core/loop-turn-dispatch.js

@@ -10,7 +10,7 @@ import { resolveModel } from './agent-capability.js';
 import { listAgentIdentities } from './agent-registry.js';
 import { transitionAgentRun } from './agentruns.js';
 import { loadAssignment, patchAssignmentMessageId, transitionAssignment } from './assignments.js';
-import { attachAssignmentMessageToClaim, createCoordinatorClaim, ensureClaimAssignmentBinding, } from './claims.js';
+import { attachAssignmentMessageToClaim, createCoordinatorClaim, ensureClaimAssignmentBinding, releaseClaimIfActive, } from './claims.js';
 import { generateDispatchBrief } from './dispatcher.js';
 import { search } from './search.js';
 import { attemptExecution } from './execution.js';
@@ -21,6 +21,7 @@ import { buildIdeationBrief } from './loops/brief-assembly.js';
 import { getLoop } from './loops/store.js';
 import { prepareTurnExecution } from './loops/turn-execution.js';
 import { sendMessage } from './messaging.js';
+import { removeWorktree } from './worktree.js';
 export async function dispatchLoopTurn(input) {
     const loop = getLoop(input.loop_id, input.cwd);
     if (!loop)
@@ -131,6 +132,22 @@ export async function dispatchLoopTurn(input) {
         if (prepared.kind !== 'won') {
             result.execution_status = 'inbox_only';
             result.error = prepared.reason;
+            if (prepared.claim_disposition === 'release' && !claim.reusedExisting) {
+                try {
+                    const released = releaseClaimIfActive(claim.claimId, input.cwd);
+                    if (released.released && claim.worktreePath) {
+                        try {
+                            removeWorktree(input.cwd, claim.worktreePath, { force: true });
+                        }
+                        catch (cleanupError) {
+                            result.error += `; denied-claim worktree cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`;
+                        }
+                    }
+                }
+                catch (cleanupError) {
+                    result.error += `; denied-claim cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`;
+                }
+            }
             return result;
         }
         result.assignment_id = prepared.assignment_id;

package/dist/core/loops/attempt-authority.js

@@ -219,6 +219,7 @@ export function executionContractForGeneration(reservation, generation) {
         }
         return { contract, ref };
     }
+    const snapshot = generation.executor?.capability_snapshot ?? reservation.capability_snapshot;
     const contract = ExecutionContractSchema.parse({
         ...reservation.execution_contract,
         identity: {
@@ -234,7 +235,7 @@ export function executionContractForGeneration(reservation, generation) {
             isolation: 'worktree',
         },
     });
-    const ref = executionContractRef(contract, reservation.capability_snapshot);
+    const ref = executionContractRef(contract, snapshot);
     if (ref.hash !== generation.contract_hash) {
         throw new AttemptGenerationError('fenced', `generation ${generation.attempt_epoch} contract hash ${generation.contract_hash} does not match derived ${ref.hash}`);
     }
@@ -269,6 +270,12 @@ export function bootstrapAttemptAuthorityV2(input) {
         workspace_path: workspacePath,
         workspace_digest: attemptWorkspaceDigest(workspacePath, reservation.turn_id, 0),
         launch_nonce: grant.token,
+        executor: {
+            agent: reservation.agent,
+            agent_id: reservation.agent_id,
+            claim_id: reservation.claim_id,
+            capability_snapshot: reservation.capability_snapshot,
+        },
     });
     if (initial.assignment_id !== reservation.child_ids.assignment_id
         || initial.run_id !== reservation.child_ids.run_id
@@ -331,7 +338,8 @@ export function prepareAttemptTakeoverV2(input) {
             && close.decision === expectedMode
             && close.cause === requestedCause
             && canonicalWorkspacePath(close.next_generation.workspace_path) === canonicalWorkspacePath(input.next_workspace_path)
-            && JSON.stringify(close.next_generation.authority_home) === JSON.stringify(input.authority_home)) {
+            && JSON.stringify(close.next_generation.authority_home) === JSON.stringify(input.authority_home)
+            && (!input.next_executor || JSON.stringify(close.next_generation.executor) === JSON.stringify(input.next_executor))) {
             const generationContract = executionContractForGeneration(reservation, close.next_generation);
             return {
                 won: false,
@@ -376,9 +384,10 @@ export function prepareAttemptTakeoverV2(input) {
         contract_hash: '0'.repeat(64),
         workspace_path: nextWorkspacePath,
         workspace_digest: attemptWorkspaceDigest(nextWorkspacePath, input.turn_id, nextEpoch),
+        executor: input.next_executor,
     });
     const baseContract = reservation.execution_contract;
-    const snapshot = reservation.capability_snapshot;
+    const snapshot = input.next_executor?.capability_snapshot ?? reservation.capability_snapshot;
     if (!baseContract || !snapshot) {
         throw new AttemptGenerationError('invalid_transition', `turn ${input.turn_id} lacks a contracted capability snapshot`);
     }
@@ -402,6 +411,7 @@ export function prepareAttemptTakeoverV2(input) {
         contract_hash: nextRef.hash,
         workspace_path: nextWorkspacePath,
         workspace_digest: attemptWorkspaceDigest(nextWorkspacePath, input.turn_id, nextEpoch),
+        executor: input.next_executor,
         launch_nonce: provisional.launch_nonce,
         created_at: provisional.created_at,
     });
@@ -419,7 +429,15 @@ export function prepareAttemptTakeoverV2(input) {
     if (generationDigest(incumbent.next_generation) !== generationDigest(next)) {
         throw new AttemptGenerationError('fenced', `a different successor already won generation ${current.attempt_epoch}`);
     }
-    rebuildAttemptGenerationHead(input.cwd, current);
+    // The close cell above is the immutable authority boundary. `head.json` is
+    // only a rebuildable read cache, so a projection failure after a winning
+    // close must never escape as a pre-commit takeover failure: callers could
+    // otherwise roll back claims while the successor generation already owns
+    // the turn. Readers repair the cache from immutable cells on replay.
+    try {
+        rebuildAttemptGenerationHead(input.cwd, current);
+    }
+    catch { /* immutable close(epoch) remains authoritative */ }
     return {
         won: published.won,
         rollout,