brainclaw 1.26.2 → 1.28.0

package/dist/core/assignment-sweeper.js

@@ -17,6 +17,7 @@ import { spawnSync } from 'node:child_process';
 import { listAssignments, transitionAssignment } from './assignments.js';
 import { signalExists, readHeartbeat, latestActivityMs } from './runtime-signals.js';
 import { DEFAULT_HYGIENE_POLICY } from './hygiene-policy.js';
+import { currentAttemptRunIdForAssignment } from './loops/attempt-reservation.js';
 function lastCommitAgeMs(worktreePath, nowMs) {
     if (!worktreePath)
         return undefined;
@@ -46,6 +47,7 @@ function lastCommitAgeMs(worktreePath, nowMs) {
  */
 function collectImplicitEvidence(assignment, cwd, nowMs, sinceMs, freshTtlMs) {
     const root = cwd ?? process.cwd();
+    const runId = currentAttemptRunIdForAssignment(assignment.id, cwd);
     const parts = [];
     let freshest;
     const bump = (ageMs) => {
@@ -55,12 +57,12 @@ function collectImplicitEvidence(assignment, cwd, nowMs, sinceMs, freshTtlMs) {
             freshest = ageMs;
     };
     try {
-        if (signalExists(root, assignment.id, 'ack'))
+        if (signalExists(root, assignment.id, 'ack', runId))
             parts.push('ack sentinel');
     }
     catch { /* defensive */ }
     try {
-        const hb = readHeartbeat(root, assignment.id, assignment.worktree_path);
+        const hb = readHeartbeat(root, assignment.id, assignment.worktree_path, runId);
         if (hb.exists && hb.mtimeMs !== undefined) {
             const age = nowMs - hb.mtimeMs;
             parts.push(`heartbeat ${Math.round(age / 1000)}s old`);
@@ -69,7 +71,7 @@ function collectImplicitEvidence(assignment, cwd, nowMs, sinceMs, freshTtlMs) {
     }
     catch { /* defensive */ }
     try {
-        const lastFs = latestActivityMs(root, assignment.id, assignment.worktree_path);
+        const lastFs = latestActivityMs(root, assignment.id, assignment.worktree_path, runId);
         if (lastFs !== undefined) {
             const age = nowMs - lastFs;
             parts.push(`fs activity ${Math.round(age / 1000)}s old`);

package/dist/core/assignments.js

@@ -48,37 +48,41 @@ function assignmentStoreForDir(dirPath) {
 // ── CRUD ─────────────────────────────────────────────────────
 export function saveAssignment(assignment, cwd) {
     mutate({ cwd }, () => {
-        ensureAssignmentsDir(cwd);
-        const store = new JsonStore({
-            dirPath: assignmentsDir(cwd, 'write'),
-            documentType: 'assignment',
-            getId: (a) => a.id,
-            sort: (a, b) => a.created_at.localeCompare(b.created_at),
-        });
-        const parsed = AssignmentSchema.parse(assignment);
-        // pln#568 (I2): journal the post-image BEFORE the projection write.
-        const created = !store.exists(parsed.id);
-        emitRegistryPostImage('assignment', 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, exactly as saveClaim does. Without this, a save wrote
-        // canonical and LEFT a legacy copy holding the stale status: `loadAssignment` reads
-        // canonical first so the record looked right, but `deleteAssignment` removed only the
-        // canonical one and the stale copy became the record again — a zombie resurrection.
-        // Best effort on purpose: `listAssignments` reads both dirs, so a missed cleanup stays
-        // visible rather than silently dropping data. (Fable audit; claims.ts already had it.)
-        const writeDir = assignmentsDir(cwd, 'write');
-        for (const dirPath of entityRecordDirs('assignments', 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 */ }
-        }
+        saveAssignmentUnlocked(assignment, cwd);
+    });
+}
+/** Store-lock caller variant used by create-or-validate projection repair. */
+function saveAssignmentUnlocked(assignment, cwd) {
+    ensureAssignmentsDir(cwd);
+    const store = new JsonStore({
+        dirPath: assignmentsDir(cwd, 'write'),
+        documentType: 'assignment',
+        getId: (a) => a.id,
+        sort: (a, b) => a.created_at.localeCompare(b.created_at),
     });
+    const parsed = AssignmentSchema.parse(assignment);
+    // pln#568 (I2): journal the post-image BEFORE the projection write.
+    const created = !store.exists(parsed.id);
+    emitRegistryPostImage('assignment', 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, exactly as saveClaim does. Without this, a save wrote
+    // canonical and LEFT a legacy copy holding the stale status: `loadAssignment` reads
+    // canonical first so the record looked right, but `deleteAssignment` removed only the
+    // canonical one and the stale copy became the record again — a zombie resurrection.
+    // Best effort on purpose: `listAssignments` reads both dirs, so a missed cleanup stays
+    // visible rather than silently dropping data. (Fable audit; claims.ts already had it.)
+    const writeDir = assignmentsDir(cwd, 'write');
+    for (const dirPath of entityRecordDirs('assignments', 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 loadAssignment(id, cwd) {
     // JsonStore.load throws when the id is missing; honor the declared
@@ -357,14 +361,14 @@ export function recordProgress(id, options, cwd) {
  * Create a new assignment. Called by the dispatcher after creating a claim
  * and sending an inbox message.
  */
-export function createAssignment(options, cwd) {
+function buildAssignment(options, cwd) {
     const generated = options.id ? undefined : generateAssignmentId(cwd);
     const id = options.id ?? generated.id;
     // `generated` is undefined whenever the caller supplied an id, so the old
     // `generated!.short_label` threw a TypeError on the perfectly reasonable call
     // "give me this id, derive the rest". Found while pinning the layout primitive.
     const short_label = options.short_label ?? generated?.short_label ?? id;
-    const assignment = AssignmentSchema.parse({
+    return AssignmentSchema.parse({
         schema_version: 1,
         id,
         short_label,
@@ -388,6 +392,8 @@ export function createAssignment(options, cwd) {
         description: options.description,
         lane: options.lane,
         worktree_path: options.worktree_path,
+        execution_contract_ref: options.execution_contract_ref,
+        capability_snapshot: options.capability_snapshot,
         status: 'created',
         created_at: nowISO(),
         heartbeat_ttl_ms: options.heartbeat_ttl_ms,
@@ -397,7 +403,8 @@ export function createAssignment(options, cwd) {
         artifacts: [],
         tags: options.tags ?? [],
     });
-    saveAssignment(assignment, cwd);
+}
+function emitAssignmentCreatedSideEffects(assignment, options, cwd) {
     emitAssignmentEvent(assignment, 'assignment_created', options.dispatcher_agent, cwd);
     appendAuditEntry({
         actor: options.dispatcher_agent,
@@ -406,8 +413,99 @@ export function createAssignment(options, cwd) {
         item_type: 'assignment',
         after: { agent: options.agent, scope: options.scope, claim_id: options.claim_id },
     }, cwd);
+}
+export function createAssignment(options, cwd) {
+    const assignment = buildAssignment(options, cwd);
+    saveAssignment(assignment, cwd);
+    emitAssignmentCreatedSideEffects(assignment, options, cwd);
     return assignment;
 }
+export class AssignmentProjectionConflictError extends Error {
+    assignmentId;
+    constructor(assignmentId, detail) {
+        super(`Assignment projection conflict for ${assignmentId}: ${detail}`);
+        this.assignmentId = assignmentId;
+        this.name = 'AssignmentProjectionConflictError';
+    }
+}
+const TERMINAL_PROJECTION_ASSIGNMENT_STATUSES = new Set([
+    'completed', 'cancelled', 'failed', 'blocked', 'timed_out', 'expired', 'rerouted',
+]);
+function assertAssignmentProjectionMatches(existing, expected) {
+    const fields = [
+        'id', 'claim_id', 'agent', 'dispatcher_agent', 'scope', 'description',
+    ];
+    for (const field of fields) {
+        if (existing[field] !== expected[field]) {
+            throw new AssignmentProjectionConflictError(expected.id, `${String(field)} differs (existing=${String(existing[field])}, expected=${String(expected[field])})`);
+        }
+    }
+    // project_id was added after the entity shipped. An absent legacy owner remains readable;
+    // when present it must identify the same authoritative store.
+    if (existing.project_id !== undefined && existing.project_id !== expected.project_id) {
+        throw new AssignmentProjectionConflictError(expected.id, 'project_id differs');
+    }
+    // Turn-owned Assignments created before P0B did not persist agent_id. Accept and
+    // enrich that legacy omission when the named agent still matches; a present,
+    // divergent identity remains a hard conflict.
+    if (existing.agent_id !== undefined && existing.agent_id !== expected.agent_id) {
+        throw new AssignmentProjectionConflictError(expected.id, 'agent_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 AssignmentProjectionConflictError(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 AssignmentProjectionConflictError(expected.id, 'capability_snapshot differs');
+    }
+    if (TERMINAL_PROJECTION_ASSIGNMENT_STATUSES.has(existing.status)) {
+        throw new AssignmentProjectionConflictError(expected.id, `existing status is terminal (${existing.status})`);
+    }
+}
+/**
+ * Create-or-validate the deterministic Assignment projection for one logical turn.
+ *
+ * The read/decision/write sequence is serialized by the store lock. Identical recovery is
+ * a strict no-op (no registry/runtime/audit duplicate); any divergent projection fails closed.
+ */
+export function ensureAssignmentProjection(options, cwd) {
+    let created = false;
+    let repaired = false;
+    const expected = buildAssignment(options, cwd);
+    const assignment = mutate({ cwd }, () => {
+        const existing = loadAssignment(options.id, cwd);
+        if (existing) {
+            assertAssignmentProjectionMatches(existing, expected);
+            const requiredTags = options.tags ?? [];
+            const missingAgentId = existing.agent_id === undefined && expected.agent_id !== undefined;
+            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));
+            if (!missingAgentId && !missingContractRef && !missingCapabilitySnapshot && !missingTags)
+                return existing;
+            const enriched = AssignmentSchema.parse({
+                ...existing,
+                ...(missingAgentId ? { agent_id: expected.agent_id } : {}),
+                ...(missingContractRef ? { execution_contract_ref: expected.execution_contract_ref } : {}),
+                ...(missingCapabilitySnapshot ? { capability_snapshot: expected.capability_snapshot } : {}),
+                tags: [...new Set([...existing.tags, ...requiredTags])],
+                updated_at: nowISO(),
+            });
+            saveAssignmentUnlocked(enriched, cwd);
+            repaired = true;
+            return enriched;
+        }
+        saveAssignmentUnlocked(expected, cwd);
+        created = true;
+        return expected;
+    });
+    if (created)
+        emitAssignmentCreatedSideEffects(assignment, options, cwd);
+    return { assignment, created, ...(repaired ? { repaired: true } : {}) };
+}
 // ── Active Assignment Lookup ─────────────────────────────────
 /** Statuses that indicate a finished assignment (no longer active). */
 const TERMINAL_STATUSES = new Set(['completed', 'cancelled', 'expired', 'rerouted']);

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

@@ -68,5 +68,12 @@ export const ReleaseClaimRequestSchema = z.object({
         .boolean()
         .describe('Opt-in override for a trusted+ caller releasing a claim they do NOT own (cross-agent teardown, ghost-claim cleanup). Rejected for contributor-level callers; audited when used. trp#928.')
         .optional(),
+    /** AttemptAuthority v2 fence; mandatory for a worker-owned claim linked to a v2 Assignment. */
+    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(),
 });
 //# sourceMappingURL=claim-request-schema.js.map

package/dist/core/claims.js

@@ -16,6 +16,8 @@ import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
 import { latestActivityMs, readHeartbeat } from './runtime-signals.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
+import { loadAssignment } from './assignments.js';
+import { currentAttemptRunIdForAssignment } from './loops/attempt-reservation.js';
 /** Parse duration string like '4h', '30m' to ms. */
 function parseTtl(value) {
     const match = /^(\d+)([mhd])$/i.exec(value.trim());
@@ -632,6 +634,7 @@ function freshestEvidenceAgeMs(claim, nowMs, cwd) {
     if (!claim.assignment_id)
         return undefined;
     const root = cwd ?? process.cwd();
+    const runId = currentAttemptRunIdForAssignment(claim.assignment_id, cwd);
     let freshest;
     const consider = (ms) => {
         if (ms === undefined)
@@ -647,13 +650,13 @@ function freshestEvidenceAgeMs(claim, nowMs, cwd) {
             freshest = normalised;
     };
     try {
-        const hb = readHeartbeat(root, claim.assignment_id, claim.worktree_path);
+        const hb = readHeartbeat(root, claim.assignment_id, claim.worktree_path, runId);
         if (hb.exists)
             consider(hb.mtimeMs);
     }
     catch { /* evidence is best-effort */ }
     try {
-        consider(latestActivityMs(root, claim.assignment_id, claim.worktree_path));
+        consider(latestActivityMs(root, claim.assignment_id, claim.worktree_path, runId));
     }
     catch { /* evidence is best-effort */ }
     return freshest;
@@ -1063,6 +1066,54 @@ export function linkClaimToAssignment(claimId, assignmentId, cwd) {
         saveClaimUnlocked(claim, cwd);
     });
 }
+export class ClaimAssignmentConflictError extends Error {
+    claimId;
+    constructor(claimId, detail) {
+        super(`Claim/Assignment projection conflict for ${claimId}: ${detail}`);
+        this.claimId = claimId;
+        this.name = 'ClaimAssignmentConflictError';
+    }
+}
+/**
+ * Idempotently bind an active claim to the deterministic Assignment of its turn.
+ * Unlike the legacy patch helper, this never overwrites a divergent binding.
+ */
+export function ensureClaimAssignmentBinding(claimId, assignmentId, cwd, options = {}) {
+    return mutate({ cwd }, () => {
+        const claim = loadClaim(claimId, cwd);
+        if (claim.status !== 'active') {
+            throw new ClaimAssignmentConflictError(claimId, `claim is ${claim.status}, expected active`);
+        }
+        if (claim.assignment_id !== undefined && claim.assignment_id !== assignmentId) {
+            // Symmetric review/fix cycles intentionally retain one active coordinator
+            // claim across rounds. A later deterministic turn may advance that pointer,
+            // but only after the previous Assignment is durably terminal.
+            const prior = loadAssignment(claim.assignment_id, cwd);
+            const priorTerminal = prior && [
+                'completed', 'cancelled', 'expired', 'rerouted',
+            ].includes(prior.status);
+            if (!priorTerminal) {
+                throw new ClaimAssignmentConflictError(claimId, `already bound to non-terminal ${claim.assignment_id}, cannot bind ${assignmentId}`);
+            }
+        }
+        let changed = false;
+        if (claim.assignment_id !== assignmentId) {
+            claim.assignment_id = assignmentId;
+            changed = true;
+        }
+        // AttemptAuthority keeps one logical Assignment/claim across physical
+        // generations. Rebind the claim's liveness and GC root to the current
+        // generation workspace in the SAME mutation as its Assignment pointer.
+        if (options.worktreePath !== undefined && claim.worktree_path !== options.worktreePath) {
+            claim.worktree_path = options.worktreePath;
+            changed = true;
+        }
+        if (!changed)
+            return claim;
+        saveClaimUnlocked(claim, cwd);
+        return claim;
+    });
+}
 /**
  * Adopt a claim from a spawned instance's session.
  * Sets session_id + adopted_at on the claim. Refuses if the claim is already

package/dist/core/dispatch-status.js

@@ -28,7 +28,8 @@ import { loadClaim } from './claims.js';
 import { getLoop, listLoops } from './loops/store.js';
 import { isProcessAlive } from './agentrun-reconciler.js';
 import { findRuntimeNoteById } from './runtime.js';
-import { latestActivityMs, decodeOemAwareBuffer } from './runtime-signals.js';
+import { latestActivityMs, decodeOemAwareBuffer, getRuntimeLogPath, getRuntimeSignalPath } from './runtime-signals.js';
+import { currentAttemptRunIdForAssignment } from './loops/attempt-reservation.js';
 import { LaneResultSchema } from './schema.js';
 const DEFAULT_TAIL = 20;
 const DEFAULT_STALL_MS = 5 * 60_000;
@@ -422,10 +423,19 @@ export function getDispatchStatus(options) {
     // coordination root. Use the cwd or the runtime cwd as the anchor; the
     // dispatcher writes them under cwd/.brainclaw/coordination/runtime/...
     const projectRoot = cwd ?? process.cwd();
-    const runtimeRoot = path.join(projectRoot, '.brainclaw', 'coordination', 'runtime');
-    const ackPath = assignmentId ? path.join(runtimeRoot, 'ack', `${assignmentId}.ack`) : undefined;
-    const stdoutPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stdout.log`) : undefined;
-    const stderrPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stderr.log`) : undefined;
+    const currentAttemptRunId = assignmentId
+        ? currentAttemptRunIdForAssignment(assignmentId, cwd)
+        : undefined;
+    const runtimeRunId = currentAttemptRunId ? (agentRun?.id ?? currentAttemptRunId) : undefined;
+    const ackPath = assignmentId
+        ? getRuntimeSignalPath(projectRoot, assignmentId, 'ack', runtimeRunId)
+        : undefined;
+    const stdoutPath = assignmentId
+        ? getRuntimeLogPath(projectRoot, assignmentId, 'stdout', runtimeRunId)
+        : undefined;
+    const stderrPath = assignmentId
+        ? getRuntimeLogPath(projectRoot, assignmentId, 'stderr', runtimeRunId)
+        : undefined;
     // pln#527 — filesystem-activity age: max mtime across the captured logs + the
     // run's worktree files (skipping junctions). The truer liveness signal when
     // the heartbeat / last_event_at is stale during a long single operation.
@@ -436,7 +446,7 @@ export function getDispatchStatus(options) {
     const worktreeForFs = agentRun?.worktree_path ?? claim?.worktree_path ?? assignment?.worktree_path;
     let lastFsActivityMs;
     if (assignmentId) {
-        const lastFs = latestActivityMs(projectRoot, assignmentId, worktreeForFs);
+        const lastFs = latestActivityMs(projectRoot, assignmentId, worktreeForFs, runtimeRunId);
         if (lastFs !== undefined)
             lastFsActivityMs = nowMs - lastFs;
     }

package/dist/core/dispatcher.js

@@ -44,7 +44,8 @@ import { memoryDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, dispatchCanCommit, isSandboxedSpawn, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
+import { resolveBriefMode, getCapabilityProfile, dispatchHasMcp, dispatchCanCommit, isSandboxedSpawn, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
+import { buildHarnessInvocation } from './harness-adapters/index.js';
 import { getRuntimeSignalPath, getWorktreeHeartbeatPath } from './runtime-signals.js';
 import { attemptExecution } from './execution.js';
 import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
@@ -67,9 +68,8 @@ function buildEnvPrefix(claimId) {
 /**
  * Analyze a sequence and categorize each item as ready, active, blocked, or done.
  *
- * `sequenceId` (pln#632 impl-loop bind) targets a SPECIFIC sequence by id instead of
- * the project's active one — so an implementation loop can dispatch its own linked
- * sequence without hijacking the global active-sequence pointer. Omitted → the active
+ * `sequenceId` targets a SPECIFIC sequence by id instead of the project's
+ * active one, without hijacking the global active-sequence pointer. Omitted → the active
  * sequence (byte-identical to the historical behaviour; the resolver is non-throwing,
  * so an unknown id yields `null` exactly like "no active sequence").
  */
@@ -283,9 +283,11 @@ export function buildLivenessSection(cwd, assignmentId, worktreePath, opts) {
     // cwd is the worktree root) — same file, sandbox-proof spelling.
     const sandboxRelative = opts?.sandboxed === true && !!worktreePath;
     const hbPath = worktreePath
-        ? getWorktreeHeartbeatPath(worktreePath, assignmentId)
-        : getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
-    const targetPath = sandboxRelative ? `.brainclaw-heartbeat-${assignmentId}` : hbPath;
+        ? getWorktreeHeartbeatPath(worktreePath, assignmentId, opts?.runId)
+        : getRuntimeSignalPath(cwd, assignmentId, 'heartbeat', opts?.runId);
+    const targetPath = sandboxRelative
+        ? `.brainclaw-heartbeat-${assignmentId}${opts?.runId ? `-${opts.runId}` : ''}`
+        : hbPath;
     const isWin = process.platform === 'win32';
     const writeCmd = isWin
         ? `echo work_loop_reached ${assignmentId} > "${targetPath}"`
@@ -326,50 +328,35 @@ export function buildWorkingDefaultsSection(opts) {
         '',
     ].join('\n');
 }
-/**
- * pln#638 PR-4 — the transport section, for BOTH declared-MCP and MCP-less agents.
- *
- * WHY THIS EXISTS AS ONE FUNCTION. The MCP-less block was duplicated verbatim in
- * `generateBrief` and `generateDispatchBrief`; that duplication is exactly what
- * lets two brief paths drift, which is the class of bug PR-3 just fixed one layer
- * up. One function, two callers.
- *
- * WHY A DECLARED-MCP AGENT ALSO GETS A SECTION — the part that was missing. A
- * profile's `runtime.mcp_direct` is a STATIC flag: it asserts nothing about
- * whether the config exists on this machine, whether the server started, or
- * whether stdio came up. Proven in production during pln#638's own ideation: a
- * codex critic ran with `mcp_direct=true` and NO reachable MCP. Its 3654-character
- * critique survived only because the brief happened to spell out a file fallback
- * by hand. So the brief must never ASSERT the capability — it states the
- * expectation and names the fallback, and the worker decides from what it
- * actually observes.
- *
- * The store path is deliberately NOT mentioned. `.brainclaw/` is gitignored
- * (.gitignore:10), so it does not exist in a worker's worktree — the previous
- * wording told workers to write candidates into a directory they cannot see.
- */
-/**
- * The ONE LANE-RESULT shape every brief quotes.
- *
- * There used to be two. `buildProtocolSection` has emitted a fallback since
- * pln#526 with `{summary, files_changed, artifacts}` and NO `body`, while the
- * transport section below asked for `body`. A full-mode worker with an assignment
- * id received both and had to pick — and a worker that followed the older one
- * recreated trp_8efdbf9d (a substantial review collapsed into a one-line summary
- * because the contract had nowhere to put the reasoning). Caught in review by
- * Fable before this shipped.
- */
-export function laneResultShape(assignmentId) {
+export function laneResultShape(assignmentId, contractRef, fence) {
     const asgn = assignmentId ?? '<assignment_id>';
-    return `{"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<one line>","body":"<your full output — the reasoning, not just a label>","files_changed":["..."],"artifacts":["..."]}`;
+    const generation = fence
+        ? `,"turn_id":"${fence.turn_id}","run_id":"${fence.run_id}","nonce":"${fence.nonce}","attempt_epoch":${fence.attempt_epoch},"workspace_digest":"${fence.workspace_digest}"`
+        : '';
+    const contract = contractRef
+        ? `,"execution_contract_hash":"${contractRef.hash}","capability_snapshot_hash":"${contractRef.snapshot_hash}"`
+        : '';
+    return `{"assignment_id":"${asgn}"${generation}${contract},"status":"completed|blocked|failed","summary":"<one line>","body":"<your full output — the reasoning, not just a label>","files_changed":["..."],"artifacts":["..."]}`;
 }
 export function buildTransportSection(opts) {
-    const laneResult = `write LANE-RESULT.json at the worktree ROOT: ${laneResultShape(opts.assignmentId)}`;
+    const laneResult = `write LANE-RESULT.json at the worktree ROOT: ${laneResultShape(opts.assignmentId, opts.executionContractRef, opts.attemptFence)}`;
+    const acceptance = opts.executionContractRef
+        ? [
+            `Execution contract: ${opts.executionContractRef.hash}`,
+            `Capability snapshot: ${opts.executionContractRef.snapshot_hash}`,
+            'These values are also available as BRAINCLAW_EXECUTION_CONTRACT_HASH and BRAINCLAW_CAPABILITY_SNAPSHOT_HASH. Echo both unchanged in LANE-RESULT.json. If either differs from what your runtime accepted, report blocked immediately; Brainclaw withholds convergence and never respawns this crossed generation.',
+            ...(opts.attemptFence ? [
+                `Attempt generation fence: turn=${opts.attemptFence.turn_id}, run=${opts.attemptFence.run_id}, nonce=${opts.attemptFence.nonce}, epoch=${opts.attemptFence.attempt_epoch}, workspace_digest=${opts.attemptFence.workspace_digest}.`,
+                'Include every fence field in bclaw_assignment_update as well as LANE-RESULT.json; an incomplete or stale update is rejected before mutating Assignment, AgentRun, or Claim.',
+            ] : []),
+        ]
+        : [];
     if (!opts.hasMcp) {
         return [
             '## ⚠ Transport: no MCP (file protocol only)',
             'Your runtime has no brainclaw MCP access — any `bclaw_*` instruction above does NOT apply to you. Report your outcome via the FILE protocol only; it is authoritative for this run:',
             `- When done, ${laneResult}.`,
+            ...acceptance,
             // RESTORED after review. Removing this orphaned a real, shipped consumer:
             // `collectWorktreeCandidateFiles` (harvest.ts:191-205) scans exactly this
             // directory inside WORKER worktrees, and `bclaw_harvest_candidates` exposes
@@ -386,6 +373,7 @@ export function buildTransportSection(opts) {
         'Your profile declares brainclaw MCP access, but that is a DECLARATION, not a verified fact — the config may be absent on this machine or the server may not have started. Decide from what you actually observe:',
         '- If `bclaw_*` tools respond: use them, as instructed above.',
         `- If they are unavailable or error: do not stop and do not discard your work — ${laneResult}. The coordinator harvests it.`,
+        ...acceptance,
         '',
     ].join('\n');
 }
@@ -463,11 +451,17 @@ export function buildProtocolSection(options) {
         parts.push(`${options.worktreePath ? '3' : '2'}. Call bclaw_assignment_update(assignment_id: "${options.assignmentId}", status: "started")`);
         parts.push(`${options.worktreePath ? '4' : '3'}. Work on the assigned scope`);
         parts.push(`${options.worktreePath ? '5' : '4'}. Periodically call bclaw_assignment_update(status: "progress", message: "...") as heartbeat`);
-        parts.push(`${options.worktreePath ? '6' : '5'}. When done: bclaw_assignment_update(status: "completed", artifacts: [...])`);
-        const claimRef = options?.claimId ? `id: "${options.claimId}"` : 'id: "<claim_id>"';
-        parts.push(`${options.worktreePath ? '7' : '6'}. Release the claim: bclaw_release_claim(${claimRef}, planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
-        parts.push(`${options.worktreePath ? '8' : '7'}. If blocked: bclaw_assignment_update(status: "blocked", blocker: "...")`);
-        parts.push(`${options.worktreePath ? '9' : '8'}. If failed: bclaw_assignment_update(status: "failed", error_message: "...")`);
+        if (options.attemptFence) {
+            parts.push(`${options.worktreePath ? '6' : '5'}. Report the terminal outcome in full-fence LANE-RESULT.json; do NOT terminalize the logical Assignment or release its Claim. Brainclaw settles close(epoch) first, then replays those projections.`);
+            parts.push(`${options.worktreePath ? '7' : '6'}. If blocked or failed, encode that status and explanation in LANE-RESULT.json with the same complete generation fence.`);
+        }
+        else {
+            parts.push(`${options.worktreePath ? '6' : '5'}. When done: bclaw_assignment_update(status: "completed", artifacts: [...])`);
+            const claimRef = options?.claimId ? `id: "${options.claimId}"` : 'id: "<claim_id>"';
+            parts.push(`${options.worktreePath ? '7' : '6'}. Release the claim: bclaw_release_claim(${claimRef}, planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
+            parts.push(`${options.worktreePath ? '8' : '7'}. If blocked: bclaw_assignment_update(status: "blocked", blocker: "...")`);
+            parts.push(`${options.worktreePath ? '9' : '8'}. If failed: bclaw_assignment_update(status: "failed", error_message: "...")`);
+        }
         // pln#479: compile-check contract for code workers — a per-worktree
         // pre-commit gate may HARD-block a commit that fails tsc (opt-in).
         if (options.worktreePath) {
@@ -763,7 +757,10 @@ export function generateDispatchBrief(options) {
     // sprint 1.5 — task-based briefs get the same step-0 liveness contract as
     // plan-based briefs (worktree-local heartbeat, writable from any sandbox).
     if (options.assignmentId && options.worktreePath) {
-        parts.push(buildLivenessSection(options.worktreePath, options.assignmentId, options.worktreePath, { sandboxed: taskSandboxed }));
+        parts.push(buildLivenessSection(options.worktreePath, options.assignmentId, options.worktreePath, {
+            sandboxed: taskSandboxed,
+            runId: options.attemptFence?.run_id,
+        }));
     }
     // pln#554 step 4 — working defaults (incremental commits + validation bar).
     parts.push(buildWorkingDefaultsSection({ canCommit: taskBriefProfile ? dispatchCanCommit(taskBriefProfile) : true }));
@@ -779,6 +776,7 @@ export function generateDispatchBrief(options) {
             claimId: options.claimId,
             worktreePath: options.worktreePath,
             assignmentId: options.assignmentId,
+            attemptFence: options.attemptFence,
         }));
     }
     // pln#628 Focus 4A — transport addendum keyed to the ACTUAL missing capability
@@ -792,6 +790,8 @@ export function generateDispatchBrief(options) {
         parts.push(buildTransportSection({
             hasMcp: taskBriefProfile ? dispatchHasMcp(taskBriefProfile) : true,
             assignmentId: options.assignmentId,
+            executionContractRef: options.executionContractRef,
+            attemptFence: options.attemptFence,
         }));
     }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs
@@ -1087,7 +1087,7 @@ export async function dispatch(options, cwd) {
             // `sandboxed` flag. A --dry-run that previews a DIFFERENT brief than the one
             // that ships is worse than no preview.
             const brief = generateBrief(readyItem.plan, readyItem.item, cwd, briefMode, { claimId, worktreePath, agent: targetAgent });
-            const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
+            const invokeCmd = buildHarnessInvocation(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) })?.invoke;
             if (invokeCmd) {
                 const cmdPrefix = buildEnvPrefix(claimId);
                 result.commands.push({ agent: targetAgent, lane: readyItem.lane, plan_id: readyItem.plan.id, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
@@ -1143,7 +1143,7 @@ export async function dispatch(options, cwd) {
             agent: targetAgent,
         });
         // Step 3: Build invoke command
-        const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
+        const invokeCmd = buildHarnessInvocation(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) })?.invoke;
         if (invokeCmd) {
             const cmdPrefix = buildEnvPrefix(claimId);
             result.commands.push({

package/dist/core/entity-operations.js

@@ -26,6 +26,9 @@ import { loadAllSessions } from './identity.js';
 import { loadInstructions } from './instructions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
+import { currentAttemptRunIdForAssignment } from './loops/attempt-reservation.js';
+import { findReservationByAssignmentId } from './loops/attempt-reservation.js';
+import { getLoop } from './loops/store.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, reconcileStrandedFailureClaimAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { isObserverMode } from './observer-mode.js';
 import { deleteRuntimeNote, listRuntimeNotes, parkRuntimeNoteBackup, saveRuntimeNote, } from './runtime.js';
@@ -709,6 +712,9 @@ export function updateEntity(name, id, patch, cwd) {
             const assignment = loadAssignment(id, cwd);
             if (!assignment)
                 throw new EntityNotFoundError(name, id);
+            if (currentAttemptRunIdForAssignment(id, cwd)) {
+                throw new Error(`assignment '${id}' is managed by AttemptAuthority v2; generic update is fenced until authoritative loop settlement/recovery`);
+            }
             const patched = { ...assignment, ...patch };
             saveAssignment(patched, cwd);
             return { entity: name, id };
@@ -894,6 +900,9 @@ export function removeEntity(name, id, cwd, purge = false) {
             const assignment = loadAssignment(id, cwd);
             if (!assignment)
                 throw new EntityNotFoundError(name, id);
+            if (currentAttemptRunIdForAssignment(id, cwd)) {
+                throw new Error(`assignment '${id}' is managed by AttemptAuthority v2; remove is fenced until authoritative loop settlement/recovery`);
+            }
             if (purge) {
                 const deleted = deleteAssignment(id, cwd);
                 if (!deleted)
@@ -987,6 +996,9 @@ export function transitionEntity(name, id, to, cwd, _reason, auth) {
             throw new InvalidTransitionError(name, from, to);
         }
         case 'assignment': {
+            if (currentAttemptRunIdForAssignment(id, cwd)) {
+                throw new Error(`assignment '${id}' is managed by AttemptAuthority v2; use full-fence bclaw_assignment_update or loop reconciliation`);
+            }
             transitionAssignment(id, to, {
                 actor: 'brainclaw',
                 status_reason: _reason,
@@ -1000,6 +1012,14 @@ export function transitionEntity(name, id, to, cwd, _reason, auth) {
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
         case 'claim': {
+            const claim = loadClaim(id, cwd);
+            if (claim.assignment_id && currentAttemptRunIdForAssignment(claim.assignment_id, cwd)) {
+                const reservation = findReservationByAssignmentId(claim.assignment_id, cwd);
+                const loop = reservation ? getLoop(reservation.loop_id, cwd) : undefined;
+                if (!auth?.override || !loop || auth.agent_id !== loop.created_by) {
+                    throw new Error(`claim '${id}' belongs to an AttemptAuthority v2 assignment; override requires authenticated loop creator ${loop?.created_by ?? 'unknown'}`);
+                }
+            }
             // trp#928 — the entity registry advertised `active → released|stale` but
             // transitionEntity never routed for entity=claim. The isValidTransition
             // check above passed for anyone calling `bclaw_transition(entity='claim',

package/dist/core/events.js

@@ -121,6 +121,10 @@ export function createRuntimeEvent(options, cwd) {
         tags: options.tags ?? [],
         assignment_id: options.assignment_id,
         run_id: options.run_id,
+        turn_id: options.turn_id,
+        nonce: options.nonce,
+        attempt_epoch: options.attempt_epoch,
+        workspace_digest: options.workspace_digest,
         claim_id: options.claim_id,
         message_id: options.message_id,
         plan_id: options.plan_id,