brainclaw 1.26.2 → 1.28.0

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

@@ -14,7 +14,7 @@
 import crypto from 'node:crypto';
 import { buildClaimEnvPrefix } from '../core/execution-profile.js';
 import { resolveProjectCwd } from '../core/cross-project.js';
-import { attachAssignmentMessageToClaim, createCoordinatorClaim, linkClaimToAssignment, listClaims, saveClaim, } from '../core/claims.js';
+import { attachAssignmentMessageToClaim, createCoordinatorClaim, linkClaimToAssignment, listClaims, releaseClaimIfActive, saveClaim, } from '../core/claims.js';
 import { ensureAgentRegisteredForDispatch, findAgentIdentityById, findAgentIdentityByName, } from '../core/agent-registry.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { nowISO } from '../core/ids.js';
@@ -26,10 +26,13 @@ import { agentValidationFailedWarning, consultAutoExecuteNoOpWarning, planAlread
 import { ackMessage, getThread, hasActiveAssignment, sendMessage } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
 import { CoordinateRequestSchema } from '../core/facade-schema.js';
-import { buildInvokeCommand, getCapabilityProfile, getSpawnableAgents, resolveModel, validateAgentForDispatch, } from '../core/agent-capability.js';
+import { getCapabilityProfile, getSpawnableAgents, resolveModel, validateAgentForDispatch, } from '../core/agent-capability.js';
+import { buildHarnessInvocation, resolveHarnessBinding } from '../core/harness-adapters/index.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
 import { prepareTurnOwnedReviewDispatch, turnOwnedReviewEnabled } from '../core/review-loop-turn-dispatch.js';
+import { prepareTurnExecution } from '../core/loops/turn-execution.js';
+import { removeWorktree } from '../core/worktree.js';
 import { createAssignment, generateAssignmentId, patchAssignmentMessageId, transitionAssignment, } from '../core/assignments.js';
 import { createToolErrorResponse, toolResponse, } from './mcp-contract.js';
 import { handleMcpReadToolCall } from './mcp-read-handlers.js';
@@ -492,16 +495,16 @@ export async function handleBclawCoordinate(args, ctx) {
             if (execResult.error)
                 opts.warnings.push(`${entry.agent}: ${execResult.error}`);
             if (turnEcho) {
-                // pln#630 risk #1 — a turn-owned reviewer's run was ALREADY created (`created`) by
-                // prepareTurnOwnedReviewDispatch. Do NOT mint a second run here (double-mint). Transition
-                // the deterministic run → running on a real spawn (mirrors dispatchReviewLoopTurn); leave
+                // A turn-owned loop run was ALREADY created (`created`) before crossing.
+                // Do NOT mint a second run here (double-mint). Transition the
+                // deterministic run → running on a real spawn; leave
                 // it `created` otherwise so the no-sentinel legacy fallback (turnOwnedLaneEvidence) + the
                 // pre-run lease reconciler govern it. Non-turn-owned entries take the unchanged else-branch.
                 if (execResult.execution_status === 'delivered_and_started') {
                     try {
                         transitionAgentRun(turnEcho.run_id, 'running', {
                             actor: opts.senderAgent, actor_id: opts.senderAgentId, pid: execResult.pid,
-                            status_reason: 'turn-owned reviewer spawned by coordinator',
+                            status_reason: 'turn-owned loop worker spawned by coordinator',
                         }, opts.cwd);
                     }
                     catch { /* best-effort — the reconciler converges if this races */ }
@@ -626,6 +629,8 @@ export async function handleBclawCoordinate(args, ctx) {
             scope: options?.scope,
             worktreePath: options?.worktreePath,
             assignmentId: options?.assignmentId,
+            executionContractRef: options?.executionContractRef,
+            attemptFence: options?.attemptFence,
             // pln#638 PR-6b — the envelope must read the TARGET project's store: on a
             // cross-project dispatch, defaulting to process.cwd() would inline the
             // WRONG project's constraints/traps into the worker's brief.
@@ -659,7 +664,7 @@ export async function handleBclawCoordinate(args, ctx) {
         }, dispatchCwd);
         artifacts.push({ type: 'message', id: msgResult.id });
         side_effects.push({ action: 'create', entity: 'message', id: msgResult.id });
-        const invoke = buildInvokeCommand(input.agent, input.text, {
+        const invoke = buildHarnessInvocation(input.agent, input.text, {
             mode: input.commandMode ?? 'worker',
             // pln#520/#606 — decouple model from agent identity. req.model is the
             // override link; when unset, resolveModel intentionally falls back to
@@ -670,7 +675,8 @@ export async function handleBclawCoordinate(args, ctx) {
             // (gpt-5.6-luna review). Flows to both the manual commandHint and the
             // auto-spawn path (runCoordinateExecution reuses this invoke).
             model: resolveModel(input.agent, { override: req.model }),
-        });
+            binding: input.harnessBinding,
+        })?.invoke;
         // Build env prefix for claim routing — centralised in
         // execution-profile.ts:buildClaimEnvPrefix as of pln#496 step
         // stp_a9afe59d (handles all five shells, not just Windows/POSIX).
@@ -996,6 +1002,7 @@ export async function handleBclawCoordinate(args, ctx) {
                     created_by: creatorActor,
                     slots,
                     mode: req.review_mode ?? 'asymmetric',
+                    linked: req.linked,
                 }, dispatchCwd);
                 out.loopId = loop.id;
                 out.artifacts.push({ type: 'loop', id: loop.id });
@@ -1024,7 +1031,10 @@ export async function handleBclawCoordinate(args, ctx) {
                     // no ids, so a harvest could only match reviewer slots by agent name —
                     // which completes the WRONG slot in symmetric (multi-reviewer) mode.
                     try {
-                        const reviewScope = `review-loop:${loop.id}`;
+                        // One claim owns one reviewer slot. A loop-wide claim cannot safely
+                        // represent parallel assignments because Claim has one assignment_id
+                        // projection; keep the parseable loop prefix and add slot identity.
+                        const reviewScope = `review-loop:${loop.id}:slot:${slot.slot_id}`;
                         const reviewDescription = `Review loop turn for ${loop.id} slot ${slot.slot_id} phase findings. `
                             + `Mode: ${advanced.loop.protocol?.review_mode ?? 'asymmetric'}. ${req.task}`;
                         const claimResult = createCoordinatorClaim({
@@ -1046,6 +1056,8 @@ export async function handleBclawCoordinate(args, ctx) {
                         });
                         let reviewAssignmentId;
                         let reviewTurnEcho;
+                        let reviewExecutionContractRef;
+                        let reviewWorktreePath = claimResult.worktreePath;
                         // pln#630 — turn-own the INITIAL reviewer dispatch (same default + kill-switch as the
                         // fix cycle). Skipped for cross-project reviews (no local worktree/sentinel → they never
                         // spawn here). WON: prepare minted the DETERMINISTIC assignment + run + turn()-bound the
@@ -1070,12 +1082,25 @@ export async function handleBclawCoordinate(args, ctx) {
                                 dispatcherAgent: senderAgent,
                                 dispatcherAgentId: senderAgentId,
                                 sessionId: connectionSessionId,
+                                model: resolveModel(slot.agent ?? '', { override: req.model }),
                                 isReviewer: true,
                                 cwd: dispatchCwd,
                             });
                             if (prep.kind === 'won') {
                                 reviewAssignmentId = prep.assignmentId; // deterministic — harvest correlates on it
-                                reviewTurnEcho = { turn_id: prep.turnId, run_id: prep.runId, nonce: prep.nonce };
+                                reviewExecutionContractRef = prep.executionContractRef;
+                                reviewTurnEcho = {
+                                    turn_id: prep.turnId,
+                                    run_id: prep.runId,
+                                    nonce: prep.nonce,
+                                    ...(prep.executionContractRef ? {
+                                        contract_hash: prep.executionContractRef.hash,
+                                        capability_snapshot_hash: prep.executionContractRef.snapshot_hash,
+                                    } : {}),
+                                    ...(prep.attemptEpoch !== undefined ? { attempt_epoch: prep.attemptEpoch } : {}),
+                                    ...(prep.workspaceDigest ? { workspace_digest: prep.workspaceDigest } : {}),
+                                };
+                                reviewWorktreePath = prep.workspacePath;
                                 out.artifacts.push({ type: 'assignment', id: prep.assignmentId });
                                 usedTurnOwned = true; // prepare already created the assignment + run + bound the slot
                             }
@@ -1124,8 +1149,16 @@ export async function handleBclawCoordinate(args, ctx) {
                         const reviewBrief = buildCoordinateBrief(slot.agent ?? '', reviewDescription + reviewVerdictBriefSuffix, {
                             claimId: claimResult.claimId,
                             scope: reviewScope,
-                            worktreePath: claimResult.worktreePath,
+                            worktreePath: reviewWorktreePath,
                             assignmentId: reviewAssignmentId,
+                            executionContractRef: reviewExecutionContractRef,
+                            attemptFence: reviewTurnEcho?.attempt_epoch !== undefined && reviewTurnEcho.workspace_digest ? {
+                                turn_id: reviewTurnEcho.turn_id,
+                                run_id: reviewTurnEcho.run_id,
+                                nonce: reviewTurnEcho.nonce,
+                                attempt_epoch: reviewTurnEcho.attempt_epoch,
+                                workspace_digest: reviewTurnEcho.workspace_digest,
+                            } : undefined,
                         });
                         const queued = queueCoordinateMessage({
                             agent: slot.agent ?? '',
@@ -1145,7 +1178,7 @@ export async function handleBclawCoordinate(args, ctx) {
                                 scope: reviewScope,
                                 claim_id: claimResult.claimId,
                                 ...(reviewAssignmentId ? { assignment_id: reviewAssignmentId } : {}),
-                                worktree_path: claimResult.worktreePath,
+                                worktree_path: reviewWorktreePath,
                             },
                             commandMode: 'worker',
                         });
@@ -1164,7 +1197,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         out.preparedReviews.push({
                             entry: queued.entry,
                             invoke: queued.invoke,
-                            worktreePath: claimResult.worktreePath,
+                            worktreePath: reviewWorktreePath,
                             turnEcho: reviewTurnEcho,
                         });
                     }
@@ -1441,7 +1474,7 @@ export async function handleBclawCoordinate(args, ctx) {
             // pln#513 step 2 — labelled block (ideate:) so the bootstrap
             // join-or-lock path can break out early after assigning result.
             const loopsModuleRef = await import('../core/loops/index.js');
-            const { openLoop, add_artifact, advance, turn, getLoop, buildIdeationBrief } = loopsModuleRef;
+            const { openLoop, add_artifact, advance, getLoop, buildIdeationBrief } = loopsModuleRef;
             const presetSelected = req.preset
                 ? (await import('../core/loops/presets/index.js')).PRESETS[req.preset]
                 : undefined;
@@ -1553,6 +1586,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         goal: req.scope,
                         created_by: creatorActor,
                         slots,
+                        linked: req.linked,
                         ...(presetSelected
                             ? {
                                 phases: presetSelected.phases,
@@ -1645,6 +1679,7 @@ export async function handleBclawCoordinate(args, ctx) {
                                 category,
                                 text: r.text,
                                 score: r.score,
+                                relatedPaths: r.related_paths,
                             }));
                         },
                     };
@@ -1708,55 +1743,86 @@ export async function handleBclawCoordinate(args, ctx) {
                                 entity: 'claim',
                                 id: claimResult.claimId,
                             });
-                            let criticAssignmentId;
-                            try {
-                                const preId = generateAssignmentId(dispatchCwd);
-                                const assignment = createAssignment({
-                                    id: preId.id,
-                                    short_label: preId.short_label,
-                                    claim_id: claimResult.claimId,
-                                    agent: slot.agent,
-                                    dispatcher_agent: senderAgent,
-                                    dispatcher_session_id: connectionSessionId,
-                                    scope: criticScope,
-                                    description: criticDescription,
-                                    tags: ['coordinate', 'ideate', 'loop'],
-                                }, dispatchCwd);
-                                criticAssignmentId = assignment.id;
-                                artifacts.push({ type: 'assignment', id: assignment.id });
-                            }
-                            catch (asgErr) {
-                                warnings.push(`ideate assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
-                            }
-                            // pln#629 — bind the slot to its claim/assignment NOW that both
-                            // exist (mirrors the review path, pln#628 BLOCKING 2). The turn()
-                            // used to fire BEFORE the assignment was created, leaving
-                            // slot.assignment_id undefined: bclaw_loop get's reconcile then
-                            // skipped the critic slot (loops-handlers.ts `if (!assignmentId)
-                            // continue`) and dispatch_status(lop_) resolved no assignment, so
-                            // ideate loops could never be reconciled (trp_dfe0b941 /
-                            // trp_2187b340 / trp_1de94516). Runs even if assignment creation
-                            // failed (undefined id → legacy agent-match fallback, as review).
-                            turn({
-                                id: loopId,
+                            // P0C / dec#171 — ideation crosses the same attempt fence as every
+                            // worker-backed LoopKind phase. Assignment, AgentRun, claim binding
+                            // and slot binding are all durable before the irreversible crossing.
+                            const criticModel = resolveModel(slot.agent, { override: req.model });
+                            const criticHarnessBinding = resolveHarnessBinding(slot.agent, criticModel);
+                            const attempt = prepareTurnExecution({
+                                kind: 'ideation',
+                                loop_id: loopId,
                                 slot_id: slot.slot_id,
-                                actor: creatorActor,
-                                input: briefResult.text,
-                                assignment_id: criticAssignmentId,
+                                phase: advancedLoop.current_phase,
+                                agent: slot.agent,
+                                agent_id: slot.agent_id,
                                 claim_id: claimResult.claimId,
-                            }, dispatchCwd);
+                                dispatcher_agent: senderAgent,
+                                dispatcher_agent_id: senderAgentId,
+                                dispatcher_session_id: connectionSessionId,
+                                scope: criticScope,
+                                description: criticDescription,
+                                task: briefResult.text,
+                                cwd: dispatchCwd,
+                                worktree_path: claimResult.worktreePath,
+                                model: criticModel,
+                                harness_binding: criticHarnessBinding,
+                                assignment_tags: ['coordinate', 'ideate', 'loop', 'turn-owned'],
+                                run_tags: ['turn-owned', 'ideate', 'loop'],
+                            });
+                            if (attempt.kind !== 'won') {
+                                warnings.push(`ideate attempt denied for slot ${slot.slot_id}: ${attempt.reason}; no worker spawned`);
+                                // A pre-identity refusal or an authority owned by another claim
+                                // cannot use this freshly created lane claim. Release only claims
+                                // created by THIS call; a reused claim may belong to a concurrent
+                                // winner and must remain intact. Repairable/same-claim authority is
+                                // also retained so projections can be replayed safely.
+                                if (attempt.claim_disposition === 'release' && !claimResult.reusedExisting) {
+                                    try {
+                                        const released = releaseClaimIfActive(claimResult.claimId, dispatchCwd);
+                                        if (released.released) {
+                                            side_effects.push({ action: 'release', entity: 'claim', id: claimResult.claimId });
+                                            if (claimResult.worktreePath) {
+                                                try {
+                                                    removeWorktree(dispatchCwd, claimResult.worktreePath, { force: true });
+                                                }
+                                                catch (cleanupError) {
+                                                    warnings.push(`ideate denied-claim worktree cleanup failed for ${claimResult.claimId}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                                                }
+                                            }
+                                        }
+                                    }
+                                    catch (cleanupError) {
+                                        warnings.push(`ideate denied-claim cleanup failed for ${claimResult.claimId}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                                    }
+                                }
+                                continue;
+                            }
+                            const criticAssignmentId = attempt.assignment_id;
+                            const criticTurnEcho = {
+                                turn_id: attempt.turn_id,
+                                run_id: attempt.run_id,
+                                nonce: attempt.nonce,
+                                ...(attempt.execution_contract_ref ? {
+                                    contract_hash: attempt.execution_contract_ref.hash,
+                                    capability_snapshot_hash: attempt.execution_contract_ref.snapshot_hash,
+                                } : {}),
+                                ...(attempt.attempt_epoch !== undefined ? { attempt_epoch: attempt.attempt_epoch } : {}),
+                                ...(attempt.workspace_digest ? { workspace_digest: attempt.workspace_digest } : {}),
+                            };
+                            artifacts.push({ type: 'assignment', id: criticAssignmentId });
                             // pln#626 Phase 2 — the critique-only contract must reach the
                             // DELIVERED brief, not just the claim record: buildCoordinateBrief
                             // wraps this in a worker envelope, so prepend the constraint + the
                             // reply path (MCP complete_turn, or LANE-RESULT.json for a sandboxed
                             // critic without brainclaw MCP) ahead of the ideation brief body.
                             const criticTaskText = `CRITIQUE-ONLY TASK — do NOT edit code or commit. Read the proposal below and reply with your critique: `
-                                + `call bclaw_loop(intent='complete_turn') if you have brainclaw MCP, otherwise write your critique to LANE-RESULT.json in your worktree root (the coordinator harvests it).\n\n`
+                                + `call bclaw_loop(intent='complete_turn') if you have brainclaw MCP, otherwise write LANE-RESULT.json in your worktree root with `
+                                + `"status":"completed", "artifact_type":"critique", and the full critique in "body" (the coordinator harvests it).\n\n`
                                 + briefResult.text;
                             const criticBrief = buildCoordinateBrief(slot.agent, criticTaskText, {
                                 claimId: claimResult.claimId,
                                 scope: criticScope,
-                                worktreePath: claimResult.worktreePath,
+                                worktreePath: attempt.workspace_path,
                                 assignmentId: criticAssignmentId,
                                 // The ideation brief above already inlines a BM25-selected,
                                 // budget-managed memory bundle (with its own truncation warning).
@@ -1764,6 +1830,14 @@ export async function handleBclawCoordinate(args, ctx) {
                                 // and break the documented ~48K content cap + dispatch-envelope
                                 // math pinned by ideation-loop-e2e.
                                 contextEnvelope: false,
+                                executionContractRef: attempt.execution_contract_ref,
+                                attemptFence: attempt.attempt_epoch !== undefined && attempt.workspace_digest ? {
+                                    turn_id: attempt.turn_id,
+                                    run_id: attempt.run_id,
+                                    nonce: attempt.nonce,
+                                    attempt_epoch: attempt.attempt_epoch,
+                                    workspace_digest: attempt.workspace_digest,
+                                } : undefined,
                             });
                             const queued = queueCoordinateMessage({
                                 agent: slot.agent,
@@ -1783,9 +1857,10 @@ export async function handleBclawCoordinate(args, ctx) {
                                     iteration: advancedLoop.iteration_count,
                                     proposal_artifact_id: proposalArtifactId,
                                     ...(criticAssignmentId ? { assignment_id: criticAssignmentId } : {}),
-                                    worktree_path: claimResult.worktreePath,
+                                    worktree_path: attempt.workspace_path,
                                 },
                                 commandMode: 'worker',
+                                harnessBinding: criticHarnessBinding,
                             });
                             if (criticAssignmentId) {
                                 try {
@@ -1802,7 +1877,8 @@ export async function handleBclawCoordinate(args, ctx) {
                             preparedCritics.push({
                                 entry: queued.entry,
                                 invoke: queued.invoke,
-                                worktreePath: claimResult.worktreePath,
+                                worktreePath: attempt.workspace_path,
+                                turnEcho: criticTurnEcho,
                             });
                             dispatchedCritics += 1;
                         }
@@ -1966,34 +2042,31 @@ export async function handleBclawCoordinate(args, ctx) {
 }
 export async function handleBclawLoop(args, ctx) {
     const { cwd, connectionSessionId } = ctx;
-    // pln#542: intent='open' is no longer exposed standalone over MCP — it
-    // creates a loop without dispatching the first turn (the documented
-    // anti-pattern, now removed instead of documented). Internal callers
-    // (bclaw_coordinate, CLI bootstrap) use core openLoop directly.
-    if (args?.intent === 'open') {
-        return {
-            response: createToolErrorResponse('intent_not_exposed', "bclaw_loop(intent='open') is not exposed standalone: it creates a loop structure without dispatching any turn, so the work never starts. Use bclaw_coordinate(intent='review', open_loop=true, targetAgents=[…]) or bclaw_coordinate(intent='ideate') — they open the loop AND dispatch the first turn."),
-        };
-    }
-    // pln#632 — `bind` SPAWNE de vrais workers (il dispatche la séquence liée de la
-    // boucle), donc il est protégé au barreau 'trusted' comme les autres surfaces de
-    // dispatch.
-    //
-    // LA BRANCHE `turn && dispatch === true` A ÉTÉ RETIRÉE (pln#626 phase 4). Le drapeau
-    // `TurnInput.dispatch` était déclaré, transporté jusqu'à `turn()` — et JAMAIS LU. Une
-    // porte de confiance sur un no-op est pire qu'absente : elle fait croire qu'un chemin
-    // sensible est gardé, et un lecteur qui la voit conclut à tort que `dispatch: true` a
-    // un effet. Le drapeau lui-même est supprimé dans le même commit ; garder la porte
-    // aurait laissé la fausse impression intacte.
-    if (args?.intent === 'bind') {
-        const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', cwd, connectionSessionId);
+    // Direct open is public for implementation/research/debug orchestration.
+    // The facade schema requires allow_orphan=true, making the caller explicitly
+    // own the subsequent bind/turn/dispatch. Review and ideation still have the
+    // higher-level coordinate shortcuts that open and dispatch together.
+    // `turn(dispatch=true)` is now a REAL generic spawn path (claim + immutable
+    // attempt + inbox + execution adapter). Plain turn remains a pure Loop Engine
+    // mutation. `bind` is also engine-only; takeover and real turn dispatch are
+    // the two trusted authority-changing paths here.
+    const targetCwd = resolveProjectCwd(args?.project, cwd);
+    let effectiveArgs = args;
+    if (args?.intent === 'takeover' || (args?.intent === 'turn' && args?.dispatch === true)) {
+        const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', targetCwd, connectionSessionId);
         if (resolved.error) {
             return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
         }
+        if ((args.intent === 'takeover' || args.intent === 'turn') && resolved.identity) {
+            effectiveArgs = {
+                ...args,
+                agent: resolved.identity.agent_name,
+                agentId: resolved.identity.agent_id,
+            };
+        }
     }
     const { handleBclawLoop: runLoopIntent } = await import('./loops-handlers.js');
-    const targetCwd = resolveProjectCwd(args?.project, cwd);
-    const result = await runLoopIntent({ args: args, cwd: targetCwd, sessionId: connectionSessionId });
+    const result = await runLoopIntent({ args: effectiveArgs, cwd: targetCwd, sessionId: connectionSessionId });
     return {
         response: toolResponse({
             content: [{ type: 'text', text: result.summary }],

package/dist/core/agent-capability.js

@@ -166,7 +166,7 @@ const PROFILES = {
         // giving Codex the same session-lifecycle wiring as Claude Code.
         hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
         instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
-        role_capabilities: ['execute', 'review'],
+        role_capabilities: ['execute', 'review', 'consult'],
         runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
         max_concurrent_tasks: 5,
         // pln#475: prefer stdin_pipe to avoid Windows cmd.exe arg-parsing breaking