brainclaw 1.26.2 → 1.28.0

package/dist/commands/loops-handlers.js

@@ -1,10 +1,11 @@
 import { ZodError } from 'zod';
 import { listAgentRuns } from '../core/agentruns.js';
 import { reconcileAgentRun } from '../core/agentrun-reconciler.js';
+import { dispatchLoopTurn } from '../core/loop-turn-dispatch.js';
 import { findReservationByRunId } from '../core/loops/attempt-reservation.js';
 import { runVerify } from '../core/loops/verify-command.js';
 import { runImplBind } from '../core/loops/impl-bind.js';
-import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, turn, VersionConflictError, withLoopLock, } from '../core/loops/index.js';
+import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, takeoverLoopAttempt, readLocalAuthorityHome, turn, VersionConflictError, withLoopLock, } from '../core/loops/index.js';
 import { BclawLoopRequestSchema, BCLAW_LOOP_INTENTS, } from '../core/loops/facade-schema.js';
 // NextExpectedHint type now lives in src/core/loops/next-expected.ts
 // (hoisted per can_e57c7782 follow-up so MCP facade + CLI share the
@@ -15,6 +16,10 @@ function resolveActor(req, defaultActor) {
     return { actor, agentId };
 }
 function successResponse(intent, result, artifacts, side_effects, warnings, durationMs, summary) {
+    const resultLoop = result && typeof result === 'object' && 'loop' in result
+        ? result.loop
+        : undefined;
+    const nextActions = resultLoop ? pipelineNextActions(resultLoop) : [];
     return {
         response: {
             status: 'ok',
@@ -24,10 +29,59 @@ function successResponse(intent, result, artifacts, side_effects, warnings, dura
             side_effects,
             warnings,
             duration_ms: durationMs,
+            ...(nextActions.length > 0 ? { next_actions: nextActions } : {}),
         },
         summary,
     };
 }
+/** Cross-loop affordances: explicit next calls, never hidden orchestration. */
+function pipelineNextActions(loop) {
+    if (loop.kind === 'ideation') {
+        const draft = [...loop.artifacts].reverse().find((artifact) => artifact.type === 'plan_draft');
+        if (!draft || (loop.current_phase !== 'synthesis' && loop.status !== 'completed'))
+            return [];
+        const planIds = loop.linked?.plan_ids ?? [];
+        const sequenceIds = loop.linked?.sequence_ids ?? [];
+        if (planIds.length > 0 && sequenceIds.length > 0) {
+            return [{
+                    tool: 'bclaw_loop',
+                    args: {
+                        intent: 'open', kind: 'implementation', title: `Implement ${loop.title}`,
+                        goal: loop.goal, linked: { plan_ids: planIds, sequence_ids: sequenceIds, source_loop_id: loop.id },
+                        verify: draft.implementation_verify,
+                        slots: [{ role: 'implementer' }], allow_orphan: true,
+                    },
+                    when: 'start implementation from the accepted synthesis',
+                }];
+        }
+        return [{
+                tool: 'bclaw_create',
+                args: { entity: 'plan', text: draft.body ?? '<materialize the plan_draft artifact>', status: 'todo' },
+                when: 'materialize the synthesis before opening its implementation loop',
+            }];
+    }
+    if (loop.kind === 'implementation' && (loop.current_phase === 'handoff_ready' || loop.status === 'completed')) {
+        const handoff = [...loop.artifacts].reverse().find((artifact) => artifact.type === 'handoff');
+        const reviewScope = [...new Set(loop.slots.map((slot) => slot.scope_hint?.trim()).filter((scope) => Boolean(scope)))].join(',');
+        return [{
+                tool: 'bclaw_coordinate',
+                args: {
+                    intent: 'review', open_loop: true,
+                    task: handoff?.ref
+                        ? `Review implementation loop ${loop.id}; handoff ${handoff.ref.kind}:${handoff.ref.id}`
+                        : `Review implementation loop ${loop.id} (${loop.title})`,
+                    targetAgents: ['<reviewer>'],
+                    ...(reviewScope ? { scope: reviewScope } : {}),
+                    ...(handoff?.ref && (handoff.ref.kind === 'commit' || handoff.ref.kind === 'branch')
+                        ? { ref: handoff.ref.id }
+                        : {}),
+                    linked: { source_loop_id: loop.id, plan_ids: loop.linked?.plan_ids, sequence_ids: loop.linked?.sequence_ids },
+                },
+                when: 'implementation evidence is handoff-ready',
+            }];
+    }
+    return [];
+}
 function errorResponse(intent, code, message, durationMs, result = null) {
     return {
         response: {
@@ -115,12 +169,11 @@ const SLOT_BOUND_INTENTS = new Set(['complete_turn']);
  * took over" window — the verb will not proceed if the lock's mutation_id
  * changed between `acquireLock` and `work` dispatch. It does NOT cover mid-verb
  * fs operations: the verbs themselves (`openLoop`, `advance`, …) perform their
- * atomic-rename + JSONL append without consulting the fence. That gap is
- * intentional for the MVP because the verbs are synchronous and complete in
- * single-digit milliseconds, much shorter than any reasonable hard_deadline
- * (default 30_000 ms). If a future slice adds async dispatch inside a
- * mutation, thread `fenceCheck` down into the verb and call it before each
- * committing write.
+ * atomic-rename + JSONL append without consulting the fence. Safety therefore
+ * depends on lock.ts refusing deadline/lease-based takeover of a still-live
+ * local process (and failing closed for remote-host owners). If a future slice
+ * adds async work inside a mutation or enables time-based/remote takeover,
+ * `fenceCheck` must first be threaded to every committing write.
  */
 function withLockedLoopMutation(req, agentId, cwd, work) {
     return withLoopLock({
@@ -128,7 +181,7 @@ function withLockedLoopMutation(req, agentId, cwd, work) {
         intent: req.intent,
         agentId,
         scope: { kind: 'loop', loopId: req.loop_id },
-        expectedVersion: req.expected_version,
+        expectedVersion: 'expected_version' in req ? req.expected_version : undefined,
         clientRequestId: req.client_request_id,
         requestPayload: requestPayload(req),
         currentVersion: () => currentLoopVersion(req.loop_id, cwd),
@@ -295,6 +348,45 @@ export async function handleBclawLoop(options) {
                 return successResponse('list', { loops: sliced, total: loops.length }, sliced.map((l) => loopArtifactEntry(l.id)), [], [], Date.now() - startMs, `✔ list ${sliced.length}/${loops.length} loops`);
             }
             case 'turn': {
+                if (req.dispatch) {
+                    if (!req.slot_id) {
+                        return errorResponse('turn', 'validation_error', 'turn dispatch requires slot_id', Date.now() - startMs);
+                    }
+                    const dispatched = await dispatchLoopTurn({
+                        loop_id: req.loop_id,
+                        slot_id: req.slot_id,
+                        task: req.input ?? `Execute ${req.loop_id} slot ${req.slot_id}`,
+                        dispatcher_agent: actor,
+                        dispatcher_agent_id: req.agentId,
+                        session_id: options.sessionId,
+                        model: req.model,
+                        auto_execute: req.auto_execute,
+                        candidate_agents: req.target_agents,
+                        cwd: options.cwd ?? process.cwd(),
+                    });
+                    // Before AttemptAuthority exists an error is a true denial. Once the
+                    // launch grant has crossed, however, transport may fall back to a
+                    // manual command or become crossed_unknown. Preserve the created
+                    // entities in a successful structured response instead of reporting
+                    // an empty-side-effect error that invites a dangerous retry.
+                    if (dispatched.error && !dispatched.turn_id) {
+                        return errorResponse('turn', 'dispatch_denied', dispatched.error, Date.now() - startMs);
+                    }
+                    const loop = getLoop(req.loop_id, options.cwd);
+                    return successResponse('turn', { loop, dispatch: dispatched, next_expected: loop ? computeNextExpected(loop) : undefined }, [
+                        loopArtifactEntry(req.loop_id),
+                        ...(dispatched.assignment_id ? [{ type: 'assignment', id: dispatched.assignment_id }] : []),
+                        ...(dispatched.run_id ? [{ type: 'agent_run', id: dispatched.run_id }] : []),
+                        ...(dispatched.claim_id ? [{ type: 'claim', id: dispatched.claim_id }] : []),
+                    ], [
+                        sideEffectUpdate('loop', req.loop_id),
+                        ...(dispatched.claim_id ? [{ action: 'create', entity: 'claim', id: dispatched.claim_id }] : []),
+                        ...(dispatched.assignment_id ? [{ action: 'create', entity: 'assignment', id: dispatched.assignment_id }] : []),
+                        ...(dispatched.run_id ? [{ action: 'create', entity: 'agent_run', id: dispatched.run_id }] : []),
+                    ], dispatched.error ? [dispatched.error] : [], Date.now() - startMs, dispatched.error
+                        ? `⚠ ${dispatched.kind}.${dispatched.phase} turn ${dispatched.turn_id} crossed; ${dispatched.error}`
+                        : `✔ dispatched ${dispatched.kind}.${dispatched.phase} turn ${dispatched.turn_id}`);
+                }
                 return withLockedLoopMutation(req, agentId, options.cwd, () => {
                     const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
                     const loop = turn({
@@ -316,6 +408,13 @@ export async function handleBclawLoop(options) {
                     const loop = complete_turn({
                         id: req.loop_id,
                         slot_id: req.slot_id,
+                        assignment_id: req.assignment_id,
+                        turn_id: req.turn_id,
+                        run_id: req.run_id,
+                        nonce: req.nonce,
+                        attempt_epoch: req.attempt_epoch,
+                        execution_contract_hash: req.execution_contract_hash,
+                        workspace_digest: req.workspace_digest,
                         outcome: req.outcome,
                         failure_reason: req.failure_reason,
                         artifact: req.artifact
@@ -325,6 +424,7 @@ export async function handleBclawLoop(options) {
                                 body: req.artifact.body,
                                 ref: req.artifact.ref,
                                 addresses_critique: req.artifact.addresses_critique,
+                                implementation_verify: req.artifact.implementation_verify,
                             }
                             : undefined,
                         actor,
@@ -337,6 +437,32 @@ export async function handleBclawLoop(options) {
                     return successResponse('complete_turn', { loop, next_expected: computeNextExpected(loop) }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summarizeLoop(loop));
                 });
             }
+            case 'takeover': {
+                const authorityHome = readLocalAuthorityHome(options.cwd ?? process.cwd());
+                if (!authorityHome) {
+                    return errorResponse('takeover', 'authority_home_unavailable', 'local store/device authority identity is not initialized', Date.now() - startMs);
+                }
+                const result = takeoverLoopAttempt({
+                    loop_id: req.loop_id,
+                    slot_id: req.slot_id,
+                    turn_id: req.turn_id,
+                    expected_epoch: req.expected_epoch,
+                    authority_home: authorityHome,
+                    actor,
+                    actor_id: agentId,
+                    writer_id: agentId,
+                    cause: req.cause,
+                    liveness_evidence: req.liveness_evidence,
+                    external_effect_policy: req.external_effect_policy,
+                    next_workspace_path: req.next_workspace_path,
+                    mode: req.takeover_mode,
+                    cwd: options.cwd ?? process.cwd(),
+                });
+                return successResponse('takeover', {
+                    ...result,
+                    next_action: 'dispatch the same logical turn; the common path will project and contend on launch(next_epoch)',
+                }, [loopArtifactEntry(result.loop.id)], [sideEffectUpdate('loop', result.loop.id)], [], Date.now() - startMs, `✔ takeover ${result.turn_id} epoch=${result.attempt_epoch} run=${result.run_id} (armed, not spawned)`);
+            }
             case 'advance': {
                 return withLockedLoopMutation(req, agentId, options.cwd, () => {
                     const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
@@ -360,9 +486,9 @@ export async function handleBclawLoop(options) {
                             phase: req.artifact.phase,
                             type: req.artifact.type,
                             body: req.artifact.body,
-                            produced_by: req.artifact.produced_by,
                             ref: req.artifact.ref,
                             addresses_critique: req.artifact.addresses_critique,
+                            implementation_verify: req.artifact.implementation_verify,
                         },
                         actor,
                     }, options.cwd);
@@ -451,7 +577,7 @@ export async function handleBclawLoop(options) {
                     return errorResponse('verify', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
                 }
                 const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
-                const result = runVerify({ loop_id: req.loop_id, actor }, options.cwd);
+                const result = runVerify({ loop_id: req.loop_id, slot_id: req.slot_id, actor }, options.cwd);
                 const newEvents = findNewLoopEvents(result.thread.id, beforeEvents, options.cwd);
                 const summary = result.unconfigured
                     ? `verify: loop has no protocol.verify — falling back to an agent-narrated verify_report`
@@ -467,10 +593,9 @@ export async function handleBclawLoop(options) {
                 }, [loopArtifactEntry(result.thread.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', result.thread.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summary);
             }
             case 'bind': {
-                // pln#632 impl-loop bind — dispatch the loop's linked sequence + advance
-                // bind→execute. runImplBind awaits the async spawn (the advance takes its own
-                // lock via the verb), so it is NOT wrapped in withLockedLoopMutation — it mirrors
-                // coordinate(open_loop)'s async-handler-spawns pattern, not a synchronous verb.
+                // Implementation bind is engine-only: validate the linked sequence and
+                // advance bind -> execute. Worker launch belongs exclusively to
+                // turn(dispatch=true), the common AttemptAuthority path.
                 const existing = getLoop(req.loop_id, options.cwd);
                 if (!existing) {
                     return errorResponse('bind', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
@@ -504,7 +629,7 @@ export async function handleBclawLoop(options) {
                     dispatched: bind.messages_sent,
                     dispatch: bind.dispatch,
                     next_expected: computeNextExpected(loop),
-                }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], sideEffects, bind.dispatch?.warnings ?? [], Date.now() - startMs, bind.reason);
+                }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], sideEffects, [...bind.warnings, ...(bind.dispatch?.warnings ?? [])], Date.now() - startMs, bind.reason);
             }
         }
     }
@@ -538,6 +663,9 @@ export async function handleBclawLoop(options) {
             });
         }
         const message = err instanceof Error ? err.message : String(err);
+        if (message.startsWith('attempt_fence_')) {
+            return errorResponse(req.intent, 'attempt_fence_rejected', message, Date.now() - startMs);
+        }
         if (message.includes('unauthorized_slot_write')) {
             return errorResponse(req.intent, 'unauthorized_slot_write', message, Date.now() - startMs);
         }

package/dist/commands/mcp-catalog.js

@@ -854,6 +854,16 @@ const MCP_WRITE_TOOLS = [
                 targetAgents: { type: 'array', items: { type: 'string' }, description: 'Agent names to target. If omitted, all spawnable agents are used.' },
                 constraints: { type: 'object', description: 'Optional structured constraints passed alongside the brief (e.g. deadline, reviewCriteria).' },
                 threadId: { type: 'string', description: 'Thread ID for summarize intent.' },
+                linked: {
+                    type: 'object',
+                    description: 'Optional pipeline provenance persisted on a review loop opened by this call.',
+                    properties: {
+                        plan_ids: { type: 'array', items: { type: 'string' } },
+                        sequence_ids: { type: 'array', items: { type: 'string' } },
+                        source_loop_id: { type: 'string', pattern: '^lop_[0-9a-z]+$' },
+                    },
+                    additionalProperties: false,
+                },
                 autoExecute: { type: 'boolean', description: 'Attempt to spawn target agents after delivery (default: true). Applies to the spawning intents assign/review/reroute AND to multi-agent ideate (with targetAgents, it spawns one worktree-isolated critic worker per target). consult is inbox-only and ignores autoExecute; summarize just reads a thread and ignores it. When false on a spawning intent, returns command_ready_manual with bash commands for the supervisor to run.' },
                 open_loop: { type: 'boolean', description: 'For intent=review only: also open a review Loop on top of the candidate (author + reviewer slots, advance to `findings`, dispatch turns). Default false — existing review callers are unaffected. See docs/concepts/loop-engine.md §Automation.' },
                 review_mode: { type: 'string', enum: ['asymmetric', 'symmetric'], description: 'Optional review Loop mode when open_loop=true. `asymmetric` (default) keeps the classical author→reviewer handoff; `symmetric` lets each reviewer turn also apply fixes directly, halving round-trips for spec/doc reviews. Ignored when open_loop is false.' },
@@ -872,7 +882,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_loop',
-        description: 'Loop engine facade: open/turn/complete_turn/advance/add_artifact/pause/resume/close/get/list multi-turn work loops (review, ideation, implementation, research, debug). Returns a FacadeResponse with the loop thread, the newly-appended event, and a next_expected hint describing the natural next intent. Experimental — schema may evolve; gate production callers behind MCP versioning (pln#392).',
+        description: 'Loop engine facade: open/turn/complete_turn/takeover/advance/add_artifact/pause/resume/close/verify/request_input/provide_input/get/list multi-turn work loops (review, ideation, implementation, research, debug). Direct open requires allow_orphan=true because the caller owns subsequent dispatch. `takeover` fences one physical run and arms a fresh generation; it never changes protocol gates.',
         // schemaSource is informational for now — grep target so future migrators
         // can locate zod-derived tools quickly. The parity test in
         // tests/unit/mcp-zod-parity.test.ts hard-codes its (tool, zod-schema)
@@ -890,12 +900,8 @@ const MCP_WRITE_TOOLS = [
             properties: {
                 intent: {
                     type: 'string',
-                    // 'open' is intentionally NOT exposed standalone (pln#542): it
-                    // created a loop structure without dispatching the first turn, so
-                    // nothing ever ran. Loops are opened via
-                    // bclaw_coordinate(intent='review', open_loop=true) or intent='ideate'.
-                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close', 'bind'],
-                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. `bind` (implementation loops only) dispatches the loop\'s linked sequence and advances bind→execute — the engine action for the `bind` phase. See docs/concepts/loop-engine.md.',
+                    enum: ['open', 'get', 'list', 'turn', 'complete_turn', 'takeover', 'advance', 'add_artifact', 'pause', 'resume', 'close', 'verify', 'bind', 'request_input', 'provide_input'],
+                    description: 'Loop lifecycle intent. Review/ideation normally start via bclaw_coordinate; implementation/research/debug may use open with allow_orphan=true and then explicitly bind/turn/dispatch. `verify` runs the configured verification; request_input/provide_input are cross-kind clarification primitives.',
                 },
                 loop_id: { type: 'string', description: 'Target loop id (lop_…). Required for every intent except open and list.' },
                 kind: { type: 'string', enum: ['review', 'ideation', 'implementation', 'research', 'debug'], description: 'Loop kind for open / list filter.' },
@@ -906,28 +912,56 @@ const MCP_WRITE_TOOLS = [
                 linked: { type: 'object', description: 'Optional top-level plan/sequence refs (open).' },
                 stop_condition: { type: 'object', description: 'Optional stop_condition override (open). Composite any/all supported.' },
                 mode: { type: 'string', enum: ['asymmetric', 'symmetric'], description: 'Review mode selector for open (review kind only).' },
+                allow_orphan: { type: 'boolean', description: 'Required true for direct open: acknowledges that the caller owns subsequent turn/bind/dispatch.' },
+                verify: { type: 'object', description: 'Optional open-time verification policy, e.g. { command: ["npm", "test"] }.' },
                 status: { type: 'string', description: 'For intent="list": filter value (any loop status). For intent="close": target final status — accepted values are `completed` | `cancelled` | `blocked` only (NOT `failed`; map crashed/dead loops to `cancelled` with a `reason`).' },
                 include_events: { type: 'boolean', description: 'get: include the event journal in the response.' },
                 limit: { type: 'number', description: 'list: max loops returned.' },
                 offset: { type: 'number', description: 'list: pagination offset.' },
-                slot_id: { type: 'string', description: 'Slot id for turn / complete_turn.' },
+                slot_id: { type: 'string', description: 'Slot id for turn / complete_turn / takeover.' },
+                turn_id: { type: 'string', description: 'takeover: stable logical turn id; complete_turn: required as part of the full AttemptAuthority v2 generation fence.' },
+                expected_epoch: { type: 'number', description: 'takeover: active physical generation epoch expected by the caller.' },
+                cause: { type: 'string', description: 'takeover: audited reason for fencing the current producer.' },
+                liveness_evidence: { type: 'string', description: 'takeover: concrete evidence that the current producer cannot safely continue.' },
+                external_effect_policy: { type: 'string', enum: ['none', 'idempotent', 'externally_fenced'], description: 'takeover: declaration required before automatic re-execution.' },
+                next_workspace_path: { type: 'string', description: 'takeover: existing isolated workspace for the successor generation.' },
+                takeover_mode: { type: 'string', enum: ['takeover', 'retry'], description: 'takeover: causal close decision kind (default takeover).' },
                 role: { type: 'string', description: 'Slot role for turn (resolves the first non-done slot with that role).' },
                 input: { type: 'string', description: 'turn: free-form input passed to the slot.' },
-                assignment_id: { type: 'string', description: 'turn: assignment id produced by the dispatcher to be recorded on the slot.' },
-                dispatch: { type: 'boolean', description: 'turn: whether the caller has already dispatched the downstream work (recorded for auditability; no spawn happens here).' },
+                assignment_id: { type: 'string', description: 'turn: assignment id produced by an external dispatcher; complete_turn: current logical assignment id in the full v2 fence.' },
+                run_id: { type: 'string', description: 'complete_turn: current physical AgentRun id in the full AttemptAuthority v2 fence.' },
+                nonce: { type: 'string', description: 'complete_turn: current immutable launch nonce in the full AttemptAuthority v2 fence.' },
+                attempt_epoch: { type: 'number', description: 'complete_turn: current physical generation epoch in the full AttemptAuthority v2 fence.' },
+                execution_contract_hash: { type: 'string', description: 'complete_turn: SHA-256 hash of the current generation ExecutionContract.' },
+                workspace_digest: { type: 'string', description: 'complete_turn: digest binding the current generation to its isolated workspace.' },
+                dispatch: { type: 'boolean', description: 'turn: when true, run the trusted production driver (claim + AttemptAuthority + inbox + real worker launch). Plain turn remains a Loop Engine state mutation and never spawns.' },
                 outcome: { type: 'string', enum: ['done', 'failed', 'cancelled'], description: 'complete_turn outcome (default done).' },
                 failure_reason: { type: 'string', description: 'complete_turn: optional failure/cancel reason.' },
                 artifact: { type: 'object', description: 'complete_turn / add_artifact payload: { phase, type, body?, produced_by?, ref? }.' },
-                dry_run: { type: 'boolean', description: 'bind: analyze + report what would dispatch; no spawn, no advance.' },
-                lanes: { type: 'array', items: { type: 'string' }, description: 'bind: restrict the dispatch to specific sequence lanes.' },
-                auto_execute: { type: 'boolean', description: 'bind: deliver briefs without spawning (→ manual launch commands).' },
-                model: { type: 'string', description: 'bind: model override for the dispatched agents.' },
-                max_assignments: { type: 'number', description: 'bind: cap assignments made in this bind.' },
+                dry_run: { type: 'boolean', description: 'bind: validate the linked sequence without advancing; bind never spawns.' },
+                lanes: { type: 'array', items: { type: 'string' }, description: 'Deprecated bind launch option retained for compatibility and ignored; dispatch independent slots with turn(dispatch=true).' },
+                auto_execute: { type: 'boolean', description: 'turn dispatch: false returns a contract-wrapped manual launch command. Deprecated and ignored for engine-only bind.' },
+                model: { type: 'string', description: 'turn dispatch: model override. Deprecated and ignored for engine-only bind.' },
+                target_agents: { type: 'array', items: { type: 'string' }, description: 'turn dispatch: deterministic capability candidate pool used when the slot has no frozen agent.' },
+                max_assignments: { type: 'number', description: 'Deprecated bind launch option retained for compatibility and ignored.' },
                 to_phase: { type: 'string', description: 'advance: explicit target phase (otherwise the next phase).' },
                 force: { type: 'boolean', description: 'advance: allow going backwards (increments iteration_count).' },
                 reason: { type: 'string', description: 'advance / pause / close: optional reason string.' },
-                expected_version: { type: 'number', description: 'Accepted for RFC compatibility on mutating intents, but not enforced until lock/CAS wiring lands.' },
-                client_request_id: { type: 'string', description: 'Accepted for RFC compatibility on mutating intents, but not enforced until lock/idempotency wiring lands.' },
+                expected_version: { type: 'number', description: 'Optimistic-CAS version enforced under the loop lock for mutating intents; stale values fail with version_conflict before mutation.' },
+                phase: { type: 'string', description: 'request_input: current loop phase.' },
+                question_text: { type: 'string', description: 'request_input: operator question (max 500 characters).' },
+                evidence: { type: 'array', items: { type: 'string' }, description: 'request_input: concrete evidence motivating the question.' },
+                suggested_default: { type: 'string', description: 'request_input: optional default answer.' },
+                options: { type: 'array', items: { type: 'object' }, description: 'request_input: optional 2-4 structured choices.' },
+                pause_scope: { type: 'string', enum: ['slot', 'loop'], description: 'request_input: pause only the slot or the whole loop.' },
+                on_timeout: { type: 'string', enum: ['use_default', 'cancel_loop', 'continue_incomplete'], description: 'request_input: timeout policy.' },
+                timeout_at: { type: 'string', description: 'request_input: optional ISO timestamp.' },
+                replies_to: { type: 'string', description: 'provide_input: question id (qst_…).' },
+                resolved_via: { type: 'string', enum: ['answer', 'choose', 'skip', 'timeout_default'], description: 'provide_input: how the answer was resolved.' },
+                answer_text: { type: 'string', description: 'provide_input: free-form answer.' },
+                chosen_option_id: { type: 'string', description: 'provide_input: selected option id.' },
+                by: { type: 'string', enum: ['operator', 'system'], description: 'provide_input: answer actor (default operator).' },
+                client_request_id: { type: 'string', description: 'Idempotency key enforced for mutating intents: exact replay returns the cached result; owner/payload reuse conflicts fail closed.' },
                 project: { type: 'string', description: 'Optional linked project name/path. Routes loop reads and mutations to that project. Defaults to the current cwd.' },
                 agent: { type: 'string', description: 'Caller agent name.' },
                 agentId: { type: 'string', description: 'Caller registered agent id (enforced for slot-bound auth in complete_turn).' },
@@ -937,7 +971,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_assignment_update',
-        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Workers call this to report: accepted (acknowledging receipt), started (work begun), progress (heartbeat), completed (done with artifacts), failed (error), or blocked (external blocker). The assignment_id is provided in the dispatch brief. OWNERSHIP (trp#291): only the agent the assignment is OWNED BY (the dispatched worker) may update it — a different agent (e.g. the coordinator) gets `Agent <x> cannot update assignment owned by <y>`. If you are the coordinator and need to converge a worker run, do NOT call this; verify via bclaw_dispatch_status instead (the reconciler infers completion from sentinels/commits).',
+        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Legacy workers may report accepted/started/progress/completed/failed/blocked. For an AttemptAuthority v2 logical Assignment, the complete current generation fence is mandatory and only accepted/started/progress are allowed; terminal outcome goes through full-fence LANE-RESULT settlement, which then projects Assignment/Claim convergence. The assignment_id is provided in the dispatch brief. OWNERSHIP (trp#291): only the assigned agent may update it. Coordinators should verify via bclaw_dispatch_status rather than impersonating the worker.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: { ...generatedSchemas.AssignmentUpdateRequest },
     },

package/dist/commands/mcp-schemas.generated.js

@@ -283,6 +283,26 @@ export const generatedSchemas = {
             "phase": {
                 "type": "string"
             },
+            "lane": {
+                "type": "string"
+            },
+            "scope_hint": {
+                "type": "string"
+            },
+            "plan_ids": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "minLength": 1
+                }
+            },
+            "step_ids": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "minLength": 1
+                }
+            },
             "status": {
                 "type": "string",
                 "enum": [
@@ -650,6 +670,28 @@ export const generatedSchemas = {
             "coordinator_override": {
                 "type": "boolean",
                 "description": "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."
+            },
+            "turn_id": {
+                "type": "string"
+            },
+            "run_id": {
+                "type": "string"
+            },
+            "nonce": {
+                "type": "string"
+            },
+            "attempt_epoch": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+            },
+            "execution_contract_hash": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+            },
+            "workspace_digest": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
             }
         },
         "required": [
@@ -1014,6 +1056,28 @@ export const generatedSchemas = {
                 ],
                 "description": "Optional ActionRequired payload when status=blocked. Lets the worker request approval, user input, or clarification before resuming."
             },
+            "turn_id": {
+                "type": "string"
+            },
+            "run_id": {
+                "type": "string"
+            },
+            "nonce": {
+                "type": "string"
+            },
+            "attempt_epoch": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+            },
+            "execution_contract_hash": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+            },
+            "workspace_digest": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+            },
             "agent": {
                 "type": "string",
                 "description": "Agent name."

package/dist/commands/mcp-write-claims.js

@@ -247,8 +247,9 @@ export async function handleBclawReleaseClaim(payload, ctx) {
         };
     }
     const cwd = located.location?.cwd ?? payload.cwd;
+    let routedClaim;
     try {
-        loadClaim(claimId, cwd); // validate existence before delegating
+        routedClaim = loadClaim(claimId, cwd); // validate existence before delegating
     }
     catch {
         const scope = located.enumeration_incomplete
@@ -290,6 +291,30 @@ export async function handleBclawReleaseClaim(payload, ctx) {
             };
         }
     }
+    if (routedClaim.assignment_id) {
+        const { findReservationByAssignmentId } = await import('../core/loops/attempt-reservation.js');
+        const { resolveTurnGenerationChain } = await import('../core/loops/attempt-generations.js');
+        const reservation = findReservationByAssignmentId(routedClaim.assignment_id, cwd);
+        const chain = reservation
+            ? resolveTurnGenerationChain(reservation.store_root, reservation.turn_id)
+            : undefined;
+        if (reservation && chain) {
+            if (coordinatorOverrideRequested) {
+                const { getLoop } = await import('../core/loops/store.js');
+                const loop = getLoop(reservation.loop_id, cwd);
+                if (!loop || loop.created_by !== releaseIdentity.identity.agent_id) {
+                    return {
+                        response: createToolErrorResponse('trust_error', `AttemptAuthority v2 coordinator override requires the authenticated loop creator (${loop?.created_by ?? 'unknown'}); caller is ${releaseIdentity.identity.agent_id}`, { claim_id: claimId, loop_id: reservation.loop_id }),
+                    };
+                }
+            }
+            else {
+                return {
+                    response: createToolErrorResponse('validation_error', `Claim ${claimId} belongs to a logical AttemptAuthority v2 Assignment and is released only after immutable settlement; worker release is refused`, { claim_id: claimId, active_epoch: chain.latest_generation.attempt_epoch }),
+                };
+            }
+        }
+    }
     const releaseAuth = {
         agent: releaseIdentity.identity.agent_name,
         agent_id: releaseIdentity.identity.agent_id,
@@ -661,6 +686,108 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
         if (assignment.agent !== callerAgent) {
             return { response: createToolErrorResponse('trust_error', `Agent ${callerAgent} cannot update assignment owned by ${assignment.agent}`) };
         }
+        // AttemptAuthority v2 keeps Assignment stable across physical generations.
+        // Therefore agent ownership alone is insufficient: a late epoch-0 worker
+        // still owns the same Assignment. Require its complete current fence before
+        // ANY progress/status mutation, AgentRun synchronization, or claim cascade.
+        const { findReservationByAssignmentId, evidenceMatchesAttempt } = await import('../core/loops/attempt-reservation.js');
+        const { resolveTurnGenerationChain } = await import('../core/loops/attempt-generations.js');
+        const reservation = findReservationByAssignmentId(assignmentId, cwd);
+        const generationChain = reservation
+            ? resolveTurnGenerationChain(reservation.store_root, reservation.turn_id)
+            : undefined;
+        if (reservation && generationChain) {
+            const matches = evidenceMatchesAttempt(reservation, {
+                assignment_id: assignmentId,
+                turn_id: typeof args.turn_id === 'string' ? args.turn_id : undefined,
+                run_id: typeof args.run_id === 'string' ? args.run_id : undefined,
+                nonce: typeof args.nonce === 'string' ? args.nonce : undefined,
+                attempt_epoch: typeof args.attempt_epoch === 'number' ? args.attempt_epoch : undefined,
+                contract_hash: typeof args.execution_contract_hash === 'string' ? args.execution_contract_hash : undefined,
+                workspace_digest: typeof args.workspace_digest === 'string' ? args.workspace_digest : undefined,
+            });
+            if (!matches) {
+                return {
+                    response: createToolErrorResponse('validation_error', `Assignment ${assignmentId} mutation rejected: missing or stale AttemptAuthority v2 generation fence`, { assignment_id: assignmentId, active_epoch: generationChain.latest_generation.attempt_epoch }),
+                };
+            }
+        }
+        // A v2 Assignment is the stable LOGICAL identity shared by every physical
+        // generation. Worker lifecycle reports therefore drive only the current
+        // AgentRun; terminal Assignment/Claim convergence is reserved for
+        // reconcileTurn after close(epoch)=settled. This also lets a successor
+        // acknowledge/start while the stable Assignment is already `started`.
+        if (generationChain) {
+            const generation = generationChain.latest_generation;
+            if (!['accepted', 'started', 'progress'].includes(status)) {
+                return {
+                    response: createToolErrorResponse('validation_error', `AttemptAuthority v2 Assignment ${assignmentId} is logical and cannot transition to '${status}' from a worker; submit full-fence LANE-RESULT evidence for settlement`, { assignment_id: assignmentId, run_id: generation.run_id, attempt_epoch: generation.attempt_epoch }),
+                };
+            }
+            if (status === 'accepted') {
+                if (assignment.status === 'offered') {
+                    transitionAsgn(assignmentId, 'accepted', {
+                        session_id: effectiveSessionId,
+                        actor: callerAgent,
+                        actor_id: resolved.identity.agent_id,
+                    }, cwd);
+                }
+                else if (assignment.status !== 'accepted' && assignment.status !== 'started') {
+                    return { response: createToolErrorResponse('operation_error', `Logical Assignment ${assignmentId} is ${assignment.status}, expected offered/accepted/started`) };
+                }
+                if (assignment.message_id) {
+                    try {
+                        const { ackMessage } = await import('../core/messaging.js');
+                        ackMessage(assignment.message_id, callerAgent, cwd, { claimId: assignment.claim_id });
+                    }
+                    catch { /* best-effort */ }
+                }
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Attempt generation ${generation.attempt_epoch} accepted for logical Assignment ${assignmentId}` }],
+                        assignment_id: assignmentId,
+                        status: assignment.status === 'offered' ? 'accepted' : assignment.status,
+                        run_id: generation.run_id,
+                        attempt_epoch: generation.attempt_epoch,
+                    }),
+                };
+            }
+            if (status === 'started') {
+                if (assignment.status === 'accepted') {
+                    transitionAsgn(assignmentId, 'started', {
+                        session_id: effectiveSessionId,
+                        actor: callerAgent,
+                        actor_id: resolved.identity.agent_id,
+                    }, cwd);
+                }
+                else if (assignment.status !== 'started') {
+                    return { response: createToolErrorResponse('operation_error', `Logical Assignment ${assignmentId} is ${assignment.status}, expected accepted/started`) };
+                }
+                const { transitionAgentRun } = await import('../core/agentruns.js');
+                transitionAgentRun(generation.run_id, 'running', {
+                    actor: callerAgent,
+                    actor_id: resolved.identity.agent_id,
+                    session_id: effectiveSessionId,
+                }, cwd);
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Attempt generation ${generation.attempt_epoch} started for logical Assignment ${assignmentId}` }],
+                        assignment_id: assignmentId,
+                        status: 'started',
+                        run_id: generation.run_id,
+                        attempt_epoch: generation.attempt_epoch,
+                    }),
+                };
+            }
+            const { recordAgentRunProgress } = await import('../core/agentruns.js');
+            recordAgentRunProgress(generation.run_id, {
+                message,
+                artifacts,
+                actor: callerAgent,
+                actor_id: resolved.identity.agent_id,
+                session_id: effectiveSessionId,
+            }, cwd);
+        }
         if (status === 'progress') {
             const updated = recordProg(assignmentId, {
                 message,