brainclaw 1.26.2 → 1.28.0

package/dist/core/agentrun-reconciler.js

@@ -33,13 +33,17 @@
  * @module
  */
 import { spawnSync } from 'node:child_process';
-import { loadAgentRun, transitionAgentRun, listAgentRuns } from './agentruns.js';
+import fs from 'node:fs';
+import { loadAgentRun, recordExecutionContractAnomaly, transitionAgentRun, listAgentRuns } from './agentruns.js';
 import { loadClaim, releaseClaim } from './claims.js';
 import { loadAssignment } from './assignments.js';
 import { createRuntimeEvent } from './events.js';
 import { nowISO } from './ids.js';
-import { readHeartbeat, readLogTail, signalExists, latestActivityMs, readCompletionSignals } from './runtime-signals.js';
+import { readContractAck, readHeartbeat, readLogTail, signalExists, latestActivityMs, readCompletionSignals } from './runtime-signals.js';
+import { validateWorkerContractAcceptance } from './execution-contract.js';
 import { findReservationByRunId, evidenceMatchesAttempt, launchGrant, revokeLaunchGrant } from './loops/attempt-reservation.js';
+import { executionContractForGeneration } from './loops/attempt-authority.js';
+import { readLaunchDecision, resolveTurnGenerationChain } from './loops/attempt-generations.js';
 import { reconcileFailedTurn } from './loops/reconcile-turn.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
@@ -55,6 +59,15 @@ export const DEFAULT_HEALTH_CHECK_GRACE_MS = 60_000;
 export const DEFAULT_STALE_AFTER_MS = 30 * 60_000;
 export const DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS = 5 * 60_000;
 export const DEFAULT_DEAD_PID_READ_SWEEP_LIMIT = 50;
+function normalizedWorkspace(value) {
+    try {
+        const resolved = fs.realpathSync.native(value);
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * pln#520 step 1 — a heartbeat older than this (with no completion signal) means
  * the worker reached its loop then went silent: `stalled`. Default 10 min.
@@ -164,17 +177,25 @@ export function collectEvidence(run, cwd, options) {
     // coordination dir (the dispatcher's ackRoot), which is `cwd` for the
     // reconciler. Keyed by assignment_id.
     const signalRoot = cwd ?? process.cwd();
+    const signalReservation = findReservationByRunId(run.id, cwd);
+    let v2SignalRunId;
+    try {
+        if (signalReservation && resolveTurnGenerationChain(signalReservation.store_root, signalReservation.turn_id)) {
+            v2SignalRunId = run.id;
+        }
+    }
+    catch { /* strict evidence handling below remains fail-closed */ }
     let completed_signal = false;
     let failed_signal = false;
     let heartbeat_exists = false;
     let heartbeat_age_ms;
     try {
-        completed_signal = signalExists(signalRoot, run.assignment_id, 'completed');
-        failed_signal = signalExists(signalRoot, run.assignment_id, 'failed');
+        completed_signal = signalExists(signalRoot, run.assignment_id, 'completed', v2SignalRunId);
+        failed_signal = signalExists(signalRoot, run.assignment_id, 'failed', v2SignalRunId);
         // sprint 1.5: also read the worktree-local heartbeat — the only location a
         // sandboxed worker can write (the project-root signal dir is outside its
         // writable roots).
-        const hb = readHeartbeat(signalRoot, run.assignment_id, run.worktree_path);
+        const hb = readHeartbeat(signalRoot, run.assignment_id, run.worktree_path, v2SignalRunId);
         heartbeat_exists = hb.exists;
         if (hb.exists && hb.mtimeMs !== undefined)
             heartbeat_age_ms = now - hb.mtimeMs;
@@ -185,7 +206,7 @@ export function collectEvidence(run, cwd, options) {
     // its heartbeat is frozen (written once at step 0).
     let fs_activity_age_ms;
     try {
-        const lastFs = latestActivityMs(signalRoot, run.assignment_id, run.worktree_path);
+        const lastFs = latestActivityMs(signalRoot, run.assignment_id, run.worktree_path, v2SignalRunId);
         if (lastFs !== undefined)
             fs_activity_age_ms = now - lastFs;
     }
@@ -198,20 +219,63 @@ export function collectEvidence(run, cwd, options) {
     // (no owning reservation) keep presence-based acceptance.
     let turn_owned = false;
     let turn_keyed_completed = false;
+    let contract_acceptance_anomaly = Boolean(run.execution_contract_anomaly);
     try {
         const reservation = findReservationByRunId(run.id, cwd);
         if (reservation) {
             turn_owned = true;
-            const bodies = readCompletionSignals(signalRoot, run.assignment_id);
+            const bodies = readCompletionSignals(signalRoot, run.assignment_id, v2SignalRunId);
+            const bootstrapAck = readContractAck(signalRoot, run.assignment_id, v2SignalRunId);
+            const hasTerminalBody = bodies.completed !== undefined || bodies.failed !== undefined;
+            const generationChain = resolveTurnGenerationChain(reservation.store_root, reservation.turn_id);
+            const generation = generationChain?.latest_generation;
+            const generationApplies = generation !== undefined && generation.run_id === run.id
+                && (generationChain?.status === 'active' || generationChain?.status === 'settled');
+            const generationLaunch = generationApplies
+                ? readLaunchDecision(reservation.store_root, reservation.turn_id, generation.attempt_epoch)
+                : undefined;
+            const expectedContractRef = generationApplies
+                ? executionContractForGeneration(reservation, generation).ref
+                : reservation.execution_contract_ref;
+            const bootstrapAccepted = !expectedContractRef || (bootstrapAck?.status === 'accepted'
+                && bootstrapAck.turn_id === reservation.turn_id
+                && bootstrapAck.run_id === (generationApplies ? generation.run_id : reservation.child_ids.run_id)
+                && bootstrapAck.nonce === (generationApplies ? generation.launch_nonce : reservation.launch?.token)
+                && (!generationApplies || bootstrapAck.cwd === normalizedWorkspace(generation.workspace_path))
+                && (!generationApplies || bootstrapAck.attempt_epoch === generation.attempt_epoch)
+                && (!generationApplies || bootstrapAck.workspace_digest === generation.workspace_digest)
+                && validateWorkerContractAcceptance(expectedContractRef, {
+                    contract_hash: bootstrapAck.contract_hash,
+                    capability_snapshot_hash: bootstrapAck.capability_snapshot_hash,
+                }, generationApplies ? generationLaunch?.decision : reservation.launch?.status).kind === 'accepted');
+            if (expectedContractRef && ((bootstrapAck && !bootstrapAccepted) || (hasTerminalBody && !bootstrapAccepted))) {
+                contract_acceptance_anomaly = true;
+            }
+            const contractAccepted = (body) => {
+                if (!expectedContractRef)
+                    return true;
+                if (!bootstrapAccepted)
+                    return false;
+                if (!body?.contract_hash || !body.capability_snapshot_hash) {
+                    contract_acceptance_anomaly = Boolean(body);
+                    return false;
+                }
+                const verdict = validateWorkerContractAcceptance(expectedContractRef, { contract_hash: body.contract_hash, capability_snapshot_hash: body.capability_snapshot_hash }, generationApplies ? generationLaunch?.decision : reservation.launch?.status);
+                if (verdict.kind !== 'accepted')
+                    contract_acceptance_anomaly = true;
+                return verdict.kind === 'accepted';
+            };
             // Evidence must be turn-keyed AND carry the RIGHT status (a `.completed`
             // file whose body says status:'failed' is not completion evidence —
             // read-strict trusts the body, not the filename, review PR2b-c #C2).
             const matchedCompleted = bodies.completed !== undefined
                 && bodies.completed.status === 'completed'
-                && evidenceMatchesAttempt(reservation, bodies.completed);
+                && evidenceMatchesAttempt(reservation, { ...bodies.completed, assignment_id: run.assignment_id })
+                && contractAccepted(bodies.completed);
             const matchedFailed = bodies.failed !== undefined
                 && bodies.failed.status === 'failed'
-                && evidenceMatchesAttempt(reservation, bodies.failed);
+                && evidenceMatchesAttempt(reservation, { ...bodies.failed, assignment_id: run.assignment_id })
+                && contractAccepted(bodies.failed);
             if (matchedCompleted && matchedFailed) {
                 // §13 R4 — a completed+failed contradiction WITHHOLDS both (never a
                 // silent accept). Conflict-event journaling is deferred to
@@ -234,7 +298,7 @@ export function collectEvidence(run, cwd, options) {
     return {
         age_ms, has_post_start_commit, claim_released, assignment_completed, process_alive,
         completed_signal, failed_signal, heartbeat_exists, heartbeat_age_ms, fs_activity_age_ms,
-        turn_owned, turn_keyed_completed,
+        turn_owned, turn_keyed_completed, contract_acceptance_anomaly,
     };
 }
 /**
@@ -322,6 +386,16 @@ export function reconcileStrandedFailureClaimAtRead(run, cwd, options = {}) {
     if (!run.claim_id)
         return false;
     const now = options.nowMs ?? Date.now();
+    if (run.status_reason?.startsWith('reserved_never_launched:')) {
+        const reservation = findReservationByRunId(run.id, cwd);
+        const dispatchDeadline = reservation ? Date.parse(reservation.lease_deadline) : Number.NaN;
+        if (reservation?.decision === 'committed'
+            && reservation.launch?.status === 'revoked'
+            && Number.isFinite(dispatchDeadline)
+            && now < dispatchDeadline) {
+            return false;
+        }
+    }
     const anchor = Date.parse(run.completed_at ?? run.updated_at ?? run.created_at);
     if (Number.isFinite(anchor) && now - anchor > STRANDED_RELEASE_RETRY_WINDOW_MS)
         return false;
@@ -366,6 +440,8 @@ function describeEvidence(evidence) {
     const reasons = [];
     if (evidence.completed_signal)
         reasons.push('wrapper wrote completed sentinel');
+    if (evidence.contract_acceptance_anomaly)
+        reasons.push('post-crossing contract acceptance anomaly (respawn forbidden)');
     if (evidence.has_post_start_commit)
         reasons.push('post-start commit on worktree branch');
     if (evidence.claim_released)
@@ -457,7 +533,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
-            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false, contract_acceptance_anomaly: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -473,6 +549,23 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
             evidence, previous_status, current_status: run.status,
         };
     }
+    if (evidence.contract_acceptance_anomaly) {
+        try {
+            recordExecutionContractAnomaly(runId, {
+                source: 'reconciler',
+                reason: 'bootstrap or terminal evidence did not accept the immutable execution contract',
+            }, cwd);
+        }
+        catch { /* ack/sentinel remains a durable fallback fence */ }
+        return {
+            run_id: runId,
+            action: 'health_check_unverified',
+            reason: 'post_crossing_contract_anomaly: accepted contract ref differs or is missing; convergence withheld and respawn=false',
+            evidence,
+            previous_status,
+            current_status: run.status,
+        };
+    }
     // pln#630 PR2c-lease (§4 + R5): a turn-owned run preallocated `created`/
     // `launching` converges on its DISPATCH/LAUNCH LEASE, not the pid/heartbeat
     // heuristics below (which assume a worker already spawned and can emit
@@ -586,8 +679,10 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
  *   - within lease → NO-OP (the worker may yet cross the launch fence / start);
  *   - past lease + launch grant CROSSED → `failed` / `launch_attempted_unknown`
  *     (the worker WAS invoked; its outcome is unknowable, so it must not complete);
- *   - past lease + grant not crossed → `cancelled` / `reserved_never_launched`
- *     (no launch receipt — nothing ran; matches attemptStatus(revoked)='cancelled').
+ *   - past launch lease + grant not crossed, while dispatch lease is live →
+ *     revoke and retain the non-terminal run for re-arm;
+ *   - past dispatch lease + grant not crossed → `cancelled` /
+ *     `reserved_never_launched` (the recovery window is exhausted).
  */
 function reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options) {
     const now = options.nowMs ?? Date.now();
@@ -620,13 +715,8 @@ function reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options)
     }
     // Past lease, no accepted completion — the launch-grant status (authoritative,
     // decision-file reconciled) decides the terminal.
-    const grant = launchGrant(reservation.turn_id, cwd);
-    const crossed = grant?.status === 'crossed';
-    const targetStatus = crossed ? 'failed' : 'cancelled';
-    const action = crossed ? 'inferred_failed' : 'inferred_cancelled';
-    const reason = crossed
-        ? `launch_attempted_unknown: launch grant crossed but run never reached running by lease ${leaseISO} — outcome unknown, never completed`
-        : `reserved_never_launched: no launch receipt by lease ${leaseISO} (grant=${grant?.status ?? 'none'})`;
+    let grant = launchGrant(reservation.turn_id, cwd);
+    let crossed = grant?.status === 'crossed';
     // pln#630 dec#149 R1 (review Finding 2) — make the reserved_never_launched strand REACHABLE
     // through the WIRED lazy reconciler: revoke the still-armed grant so its authoritative status
     // becomes `revoked`. That is what lets reconcileTurn's fix-cycle strand detector see the strand
@@ -638,6 +728,42 @@ function reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options)
             revokeLaunchGrant(reservation.turn_id, grant.epoch, 'reserved_never_launched', cwd, actor);
         }
         catch { /* raced to crossed/revoked — authoritative status governs */ }
+        grant = launchGrant(reservation.turn_id, cwd);
+        crossed = grant?.status === 'crossed';
+    }
+    if (evidence.contract_acceptance_anomaly) {
+        try {
+            recordExecutionContractAnomaly(run.id, {
+                source: 'reconciler',
+                reason: 'bootstrap or terminal evidence did not accept the immutable execution contract',
+            }, cwd);
+        }
+        catch { /* ack/sentinel remains a durable fallback fence */ }
+        return {
+            run_id: run.id,
+            action: 'health_check_unverified',
+            reason: 'post_crossing_contract_anomaly: accepted contract ref differs or is missing; convergence withheld and respawn=false',
+            evidence,
+            previous_status,
+            current_status: run.status,
+        };
+    }
+    const targetStatus = crossed ? 'failed' : 'cancelled';
+    const action = crossed ? 'inferred_failed' : 'inferred_cancelled';
+    const reason = crossed
+        ? `launch_attempted_unknown: launch grant crossed but run never reached running by lease ${leaseISO} — outcome unknown, never completed`
+        : `reserved_never_launched: no launch receipt by lease ${leaseISO} (grant=${grant?.status ?? 'none'})`;
+    const dispatchLeaseMs = Date.parse(reservation.lease_deadline);
+    const dispatchLeaseLive = Number.isFinite(dispatchLeaseMs) && now < dispatchLeaseMs;
+    if (!crossed && dispatchLeaseLive) {
+        return {
+            run_id: run.id,
+            action: 'no_op',
+            reason: `${reason}; retained non-terminal for re-arm until dispatch lease ${reservation.lease_deadline}`,
+            evidence,
+            previous_status,
+            current_status: run.status,
+        };
     }
     try {
         transitionAgentRun(run.id, targetStatus, { actor, status_reason: reason }, cwd);
@@ -680,7 +806,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
-            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false, contract_acceptance_anomaly: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -854,7 +980,7 @@ export function reconcileAllOpenRuns(cwd, filter = {}, options = {}) {
             catch {
                 results.push({
                     run_id: run.id, action: 'no_op', reason: 'reconcile threw — skipped',
-                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined, completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false },
+                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined, completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false, contract_acceptance_anomaly: false },
                     previous_status: run.status, current_status: run.status,
                 });
             }

package/dist/core/agentruns.js

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { AgentRunSchema } from './schema.js';
+import { RuntimeCapabilityObservationSchema } from './execution-contract.js';
 import { resolveOwnerProjectId } from './config.js';
 import { entityRecordDirs, resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
@@ -18,6 +19,47 @@ import { appendAuditEntry } from './audit.js';
 import { appendEvent } from './event-log.js';
 import { createRuntimeEvent } from './events.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
+import { findReservationByRunId } from './loops/attempt-reservation.js';
+import { resolveTurnGenerationChain } from './loops/attempt-generations.js';
+export class AgentRunFencedError extends Error {
+    runId;
+    activeRunId;
+    attemptEpoch;
+    authorityStatus;
+    constructor(runId, activeRunId, attemptEpoch, authorityStatus) {
+        super(`AgentRun ${runId} is fenced by attempt epoch ${attemptEpoch}`
+            + `${activeRunId ? ` (authoritative run: ${activeRunId})` : ''}`
+            + ` [${authorityStatus}]`);
+        this.runId = runId;
+        this.activeRunId = activeRunId;
+        this.attemptEpoch = attemptEpoch;
+        this.authorityStatus = authorityStatus;
+        this.name = 'AgentRunFencedError';
+    }
+}
+/**
+ * Refuse late writes from an AgentRun superseded by attempt-authority v2.
+ *
+ * The immutable generation chain is authoritative; assignment status and the
+ * mutable head projection are deliberately not consulted. A settled latest
+ * generation may still finish its replayable projections after publishing its
+ * close cell. Controllers may explicitly override this guard only to project a
+ * terminal state onto the run that they just fenced.
+ */
+function assertAgentRunMutationAllowed(id, cwd, allowFencedProjection = false) {
+    if (allowFencedProjection)
+        return;
+    const reservation = findReservationByRunId(id, cwd);
+    if (!reservation)
+        return;
+    const chain = resolveTurnGenerationChain(reservation.store_root, reservation.turn_id);
+    if (!chain)
+        return; // Legacy attempt authority remains compatible.
+    const latest = chain.latest_generation;
+    if (latest.run_id === id && (chain.status === 'active' || chain.status === 'settled'))
+        return;
+    throw new AgentRunFencedError(id, chain.status === 'active' ? latest.run_id : null, latest.attempt_epoch, chain.status);
+}
 function agentRunsDir(cwd, mode = 'read') {
     return resolveEntityDir('runs', cwd, mode);
 }
@@ -45,33 +87,37 @@ function agentRunStoreForDir(dirPath) {
 // loader found it; removing it stops the next reader from reintroducing that asymmetry.
 export function saveAgentRun(run, cwd) {
     mutate({ cwd }, () => {
-        ensureAgentRunsDir(cwd);
-        const store = new JsonStore({
-            dirPath: agentRunsDir(cwd, 'write'),
-            documentType: 'agent_run',
-            getId: (item) => item.id,
-            sort: (a, b) => a.created_at.localeCompare(b.created_at),
-        });
-        const parsed = AgentRunSchema.parse(run);
-        // pln#568 (I2): journal the post-image BEFORE the projection write.
-        const created = !store.exists(parsed.id);
-        emitRegistryPostImage('agent_run', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
-        registryFaultPoint('after_registry_journal');
-        store.save(parsed);
-        // Converge the other layout (mirrors saveClaim / saveAssignment): leaving a legacy copy
-        // holding the stale status is what let a deleted record be resurrected by its own zombie.
-        const writeDir = agentRunsDir(cwd, 'write');
-        for (const dirPath of entityRecordDirs('runs', cwd ?? process.cwd())) {
-            if (dirPath === writeDir)
-                continue;
-            const legacyPath = path.join(dirPath, `${parsed.id}.json`);
-            try {
-                if (fs.existsSync(legacyPath))
-                    fs.unlinkSync(legacyPath);
-            }
-            catch { /* best effort — the dual-layout list keeps it visible */ }
-        }
+        saveAgentRunUnlocked(run, cwd);
+    });
+}
+/** Store-lock caller variant used by create-or-validate projection repair. */
+function saveAgentRunUnlocked(run, cwd) {
+    ensureAgentRunsDir(cwd);
+    const store = new JsonStore({
+        dirPath: agentRunsDir(cwd, 'write'),
+        documentType: 'agent_run',
+        getId: (item) => item.id,
+        sort: (a, b) => a.created_at.localeCompare(b.created_at),
     });
+    const parsed = AgentRunSchema.parse(run);
+    // pln#568 (I2): journal the post-image BEFORE the projection write.
+    const created = !store.exists(parsed.id);
+    emitRegistryPostImage('agent_run', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
+    registryFaultPoint('after_registry_journal');
+    store.save(parsed);
+    // Converge the other layout (mirrors saveClaim / saveAssignment): leaving a legacy copy
+    // holding the stale status is what let a deleted record be resurrected by its own zombie.
+    const writeDir = agentRunsDir(cwd, 'write');
+    for (const dirPath of entityRecordDirs('runs', cwd ?? process.cwd())) {
+        if (dirPath === writeDir)
+            continue;
+        const legacyPath = path.join(dirPath, `${parsed.id}.json`);
+        try {
+            if (fs.existsSync(legacyPath))
+                fs.unlinkSync(legacyPath);
+        }
+        catch { /* best effort — the dual-layout list keeps it visible */ }
+    }
 }
 export function loadAgentRun(id, cwd) {
     // Record-specific across both layouts (pln#649, shared io.ts primitive). Resolving
@@ -96,6 +142,92 @@ export function loadAgentRun(id, cwd) {
     }
     return undefined;
 }
+/**
+ * Persist the first execution-contract anomaly for a run.
+ *
+ * The field is deliberately monotone: later correct-looking evidence cannot
+ * erase an already-observed post-crossing mismatch and reopen convergence.
+ */
+export function recordExecutionContractAnomaly(id, anomaly, cwd) {
+    assertAgentRunMutationAllowed(id, cwd);
+    return mutate({ cwd }, () => {
+        const run = loadAgentRun(id, cwd);
+        if (!run)
+            throw new Error(`AgentRun not found: ${id}`);
+        if (run.execution_contract_anomaly)
+            return run;
+        const now = nowISO();
+        run.execution_contract_anomaly = {
+            detected_at: now,
+            source: anomaly.source,
+            reason: anomaly.reason,
+            accepted_contract_hash: anomaly.accepted_contract_hash,
+            accepted_capability_snapshot_hash: anomaly.accepted_capability_snapshot_hash,
+        };
+        run.updated_at = now;
+        run.last_event_at = now;
+        saveAgentRunUnlocked(run, cwd);
+        return run;
+    });
+}
+/** Persist a post-start observation without ever rewriting the frozen snapshot. */
+export function recordRuntimeCapabilityObservation(id, observation, diagnostic, cwd) {
+    assertAgentRunMutationAllowed(id, cwd);
+    return mutate({ cwd }, () => {
+        const run = loadAgentRun(id, cwd);
+        if (!run)
+            throw new Error(`AgentRun not found: ${id}`);
+        const parsed = RuntimeCapabilityObservationSchema.parse(observation);
+        if (run.runtime_capability_observation) {
+            if (JSON.stringify(run.runtime_capability_observation) !== JSON.stringify(parsed)) {
+                throw new Error(`AgentRun ${id} already has a different runtime capability observation`);
+            }
+            return run;
+        }
+        const now = nowISO();
+        run.runtime_capability_observation = parsed;
+        if (diagnostic)
+            run.harness_exit_diagnostic = diagnostic;
+        const frozenRef = run.execution_contract_ref;
+        const frozenHarness = run.capability_snapshot?.resolved.harness;
+        const resolvedModel = frozenHarness?.resolved_model ?? run.capability_snapshot?.resolved.model;
+        const mismatches = [];
+        if (frozenRef?.hash !== parsed.contract_hash) {
+            mismatches.push(`observed contract hash '${parsed.contract_hash}' differs from frozen '${frozenRef?.hash ?? 'absent'}'`);
+        }
+        if (frozenRef?.snapshot_hash !== parsed.capability_snapshot_hash) {
+            mismatches.push(`observed capability snapshot hash '${parsed.capability_snapshot_hash}' differs from frozen '${frozenRef?.snapshot_hash ?? 'absent'}'`);
+        }
+        if (parsed.accepted_contract_hash && parsed.accepted_contract_hash !== frozenRef?.hash) {
+            mismatches.push(`accepted contract hash '${parsed.accepted_contract_hash}' differs from frozen '${frozenRef?.hash ?? 'absent'}'`);
+        }
+        if (parsed.accepted_capability_snapshot_hash && parsed.accepted_capability_snapshot_hash !== frozenRef?.snapshot_hash) {
+            mismatches.push(`accepted capability snapshot hash '${parsed.accepted_capability_snapshot_hash}' differs from frozen '${frozenRef?.snapshot_hash ?? 'absent'}'`);
+        }
+        if (frozenHarness && parsed.adapter_id && frozenHarness.adapter_id !== parsed.adapter_id) {
+            mismatches.push(`observed adapter '${parsed.adapter_id}' differs from frozen '${frozenHarness.adapter_id}'`);
+        }
+        if (frozenHarness && parsed.adapter_version && frozenHarness.adapter_version !== parsed.adapter_version) {
+            mismatches.push(`observed adapter version '${parsed.adapter_version}' differs from frozen '${frozenHarness.adapter_version}'`);
+        }
+        if (resolvedModel && parsed.observed_model && resolvedModel !== parsed.observed_model) {
+            mismatches.push(`observed model '${parsed.observed_model}' differs from frozen resolved model '${resolvedModel}'`);
+        }
+        if (mismatches.length > 0 && !run.execution_contract_anomaly) {
+            run.execution_contract_anomaly = {
+                detected_at: now,
+                source: 'reconciler',
+                reason: mismatches.join('; '),
+                accepted_contract_hash: parsed.accepted_contract_hash,
+                accepted_capability_snapshot_hash: parsed.accepted_capability_snapshot_hash,
+            };
+        }
+        run.updated_at = now;
+        run.last_event_at = now;
+        saveAgentRunUnlocked(run, cwd);
+        return run;
+    });
+}
 /**
  * BOTH LAYOUTS, canonical winning on a duplicate id (mirrors listClaims / listAssignments).
  *
@@ -171,10 +303,10 @@ const VALID_TRANSITIONS = new Map([
     ['timed_out', new Set()],
     ['interrupted', new Set()],
 ]);
-export function createAgentRun(options, cwd) {
+function buildAgentRun(options, cwd) {
     const generated = options.id ? undefined : generateAgentRunId(cwd);
     const now = nowISO();
-    const run = AgentRunSchema.parse({
+    return AgentRunSchema.parse({
         schema_version: 1,
         id: options.id ?? generated.id,
         // Same landmine as createAssignment: `generated` is undefined when the caller
@@ -202,6 +334,8 @@ export function createAgentRun(options, cwd) {
         shell: options.shell,
         pid: options.pid,
         provider_run_id: options.provider_run_id,
+        execution_contract_ref: options.execution_contract_ref,
+        capability_snapshot: options.capability_snapshot,
         created_at: now,
         updated_at: now,
         last_event_at: now,
@@ -211,7 +345,8 @@ export function createAgentRun(options, cwd) {
         artifacts: [],
         tags: options.tags ?? [],
     });
-    saveAgentRun(run, cwd);
+}
+function emitAgentRunCreatedSideEffects(run, options, cwd) {
     emitAgentRunEvent(run, 'run_created', options.agent, cwd);
     if (run.status !== 'created') {
         emitAgentRunEvent(run, `run_${run.status}`, options.agent, cwd);
@@ -226,9 +361,98 @@ export function createAgentRun(options, cwd) {
         scope: run.scope,
         session_id: run.session_id,
     }, cwd);
+}
+export function createAgentRun(options, cwd) {
+    const run = buildAgentRun(options, cwd);
+    saveAgentRun(run, cwd);
+    emitAgentRunCreatedSideEffects(run, options, cwd);
     return run;
 }
+export class AgentRunProjectionConflictError extends Error {
+    runId;
+    constructor(runId, detail) {
+        super(`AgentRun projection conflict for ${runId}: ${detail}`);
+        this.runId = runId;
+        this.name = 'AgentRunProjectionConflictError';
+    }
+}
+const RECOVERABLE_PROJECTION_RUN_STATUSES = new Set([
+    'created', 'launching', 'waiting_input', 'running',
+]);
+function assertAgentRunProjectionMatches(existing, expected) {
+    const fields = [
+        'id', 'assignment_id', 'claim_id', 'agent', 'agent_id', 'transport', 'scope',
+        'worktree_path', 'attempt_index',
+    ];
+    for (const field of fields) {
+        if (existing[field] !== expected[field]) {
+            throw new AgentRunProjectionConflictError(expected.id, `${String(field)} differs (existing=${String(existing[field])}, expected=${String(expected[field])})`);
+        }
+    }
+    if (existing.project_id !== undefined && existing.project_id !== expected.project_id) {
+        throw new AgentRunProjectionConflictError(expected.id, 'project_id differs');
+    }
+    if (existing.execution_contract_ref !== undefined
+        && expected.execution_contract_ref !== undefined
+        && JSON.stringify(existing.execution_contract_ref) !== JSON.stringify(expected.execution_contract_ref)) {
+        throw new AgentRunProjectionConflictError(expected.id, 'execution_contract_ref differs');
+    }
+    if (existing.capability_snapshot !== undefined
+        && expected.capability_snapshot !== undefined
+        && JSON.stringify(existing.capability_snapshot) !== JSON.stringify(expected.capability_snapshot)) {
+        throw new AgentRunProjectionConflictError(expected.id, 'capability_snapshot differs');
+    }
+    if (!RECOVERABLE_PROJECTION_RUN_STATUSES.has(existing.status)) {
+        throw new AgentRunProjectionConflictError(expected.id, `existing status is terminal (${existing.status})`);
+    }
+}
+/**
+ * Create-or-validate a deterministic AgentRun projection for one physical
+ * generation of a logical turn. P0 callers omit `attempt_index` and therefore
+ * keep the legacy value 1; AttemptAuthority v2 supplies the immutable
+ * generation index. Recovery never changes an existing run's generation and
+ * never resets an existing live run to `created`.
+ */
+export function ensureAgentRunProjection(options, cwd) {
+    const normalized = {
+        ...options,
+        attempt_index: options.attempt_index ?? 1,
+    };
+    const expected = buildAgentRun(normalized, cwd);
+    let created = false;
+    let repaired = false;
+    const run = mutate({ cwd }, () => {
+        const existing = loadAgentRun(options.id, cwd);
+        if (existing) {
+            const requiredTags = normalized.tags ?? [];
+            const missingContractRef = existing.execution_contract_ref === undefined && expected.execution_contract_ref !== undefined;
+            const missingCapabilitySnapshot = existing.capability_snapshot === undefined && expected.capability_snapshot !== undefined;
+            const missingTags = !requiredTags.every((tag) => existing.tags.includes(tag));
+            const enriched = !missingContractRef && !missingCapabilitySnapshot && !missingTags
+                ? existing
+                : {
+                    ...existing,
+                    ...(missingContractRef ? { execution_contract_ref: expected.execution_contract_ref } : {}),
+                    ...(missingCapabilitySnapshot ? { capability_snapshot: expected.capability_snapshot } : {}),
+                    tags: [...new Set([...existing.tags, ...requiredTags])],
+                };
+            assertAgentRunProjectionMatches(enriched, expected);
+            if (enriched !== existing) {
+                saveAgentRunUnlocked(enriched, cwd);
+                repaired = true;
+            }
+            return enriched;
+        }
+        saveAgentRunUnlocked(expected, cwd);
+        created = true;
+        return expected;
+    });
+    if (created)
+        emitAgentRunCreatedSideEffects(run, normalized, cwd);
+    return { run, created, ...(repaired ? { repaired: true } : {}) };
+}
 export function transitionAgentRun(id, newStatus, options = {}, cwd) {
+    assertAgentRunMutationAllowed(id, cwd, options.allow_fenced_projection);
     const run = loadAgentRun(id, cwd);
     if (!run)
         throw new Error(`AgentRun not found: ${id}`);
@@ -316,6 +540,7 @@ export function transitionAgentRun(id, newStatus, options = {}, cwd) {
     return { run, previous_status };
 }
 export function recordAgentRunProgress(id, options = {}, cwd) {
+    assertAgentRunMutationAllowed(id, cwd);
     const run = loadAgentRun(id, cwd);
     if (!run)
         throw new Error(`AgentRun not found: ${id}`);

package/dist/core/assignment-request-schema.js

@@ -80,6 +80,13 @@ export const AssignmentUpdateRequestSchema = z.object({
     error_message: z.string().describe('Error details (for failed status).').optional(),
     blocker: z.string().describe('Blocker description (for blocked status).').optional(),
     action_required: ActionRequiredSchema.optional(),
+    /** AttemptAuthority v2 fence. Required together once the Assignment has a v2 generation chain. */
+    turn_id: z.string().optional(),
+    run_id: z.string().optional(),
+    nonce: z.string().optional(),
+    attempt_epoch: z.number().int().nonnegative().optional(),
+    execution_contract_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    workspace_digest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     ...CallerIdentity,
 });
 export const AssignmentActionRequestSchema = z.object({