brainclaw 1.20.3 → 1.21.0

package/dist/commands/export.js

@@ -6,7 +6,7 @@ import { loadConfig, saveConfig } from '../core/config.js';
 import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
 import { resolveInstructions, loadInstructions } from '../core/instructions.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
-import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, resolveLiveCompanionPath, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, resolveLiveCompanionPath, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, BRAINCLAW_PROTOCOL_ARTIFACT_IGNORES, } from '../core/agent-files.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { listClaims } from '../core/claims.js';
 import { listCandidates } from '../core/candidates.js';
@@ -61,7 +61,7 @@ export function runExport(options) {
         });
         if (liveResult)
             gitignoreEntries.push(liveResult.relativePath);
-        ensureGitignoreEntries(cwd, [...gitignoreEntries, ...BRAINCLAW_EXCLUSIVE_DIRECTORIES]);
+        ensureGitignoreEntries(cwd, [...gitignoreEntries, ...BRAINCLAW_EXCLUSIVE_DIRECTORIES, ...BRAINCLAW_PROTOCOL_ARTIFACT_IGNORES]);
         declareAgentIntegrationFromTarget(cwd, target.agentName, 'manual');
         console.log(`✔ Written to ${target.relativePath} (${result.created ? 'created' : 'updated'})`);
         if (liveResult) {
@@ -102,7 +102,7 @@ function runExportDetect(cwd, options) {
     const gitignoreEntries = collectExportGitignoreEntries(cwd, target.relativePath, autoConfigs);
     if (liveResult)
         gitignoreEntries.push(liveResult.relativePath);
-    ensureGitignoreEntries(cwd, [...gitignoreEntries, ...BRAINCLAW_EXCLUSIVE_DIRECTORIES]);
+    ensureGitignoreEntries(cwd, [...gitignoreEntries, ...BRAINCLAW_EXCLUSIVE_DIRECTORIES, ...BRAINCLAW_PROTOCOL_ARTIFACT_IGNORES]);
     declareAgentIntegrationFromTarget(cwd, target.agentName, detected ? 'detected' : 'manual');
     const source = detected ? `${detected.name} [${detected.detection_source}]` : 'fallback (no agent detected)';
     console.log(`✔ Detected: ${source}`);

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline/promises';
+import { clearEnumerationMemo } from '../core/entity-locator.js';
 import { registerAgentIdentity, resolveDefaultAgentName, resolveExistingCurrentAgent } from '../core/agent-registry.js';
 import { MEMORY_DIR, memoryExists, ensureMemoryDir, memoryPath, writeFileAtomic } from '../core/io.js';
 import { emptyState, loadState, saveState } from '../core/state.js';
@@ -371,6 +372,16 @@ export async function runInit(options = {}) {
         console.log(`Tip: run 'brainclaw init' again later to refresh the detected agent's integration files on this project.`);
     }
     console.log(`Tip: in an agent session, call the bclaw_work MCP tool (intent: "consult") to load the shared memory; from a terminal, 'brainclaw context --json' does the same.`);
+    // A STORE JUST CAME INTO EXISTENCE, so the routing memo's candidate list is stale.
+    //
+    // `clearEnumerationMemo` was documented as being "for tests, and for any caller that has
+    // just created a store" — and that second caller did not exist (Fable audit found the
+    // claim describing intent rather than code). The consequence was small but real: for up
+    // to the memo TTL, a mutation routed right after `brainclaw init` / `bclaw_init_project`
+    // could not see the new project. Wiring it HERE rather than in the MCP handler covers
+    // every path that materialises a store, since both the CLI and the tool go through
+    // runInit.
+    clearEnumerationMemo();
 }
 function safeRunMachinePrereqs(agentName) {
     try {

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

@@ -12,10 +12,14 @@
  *
  * @module
  */
+import { spawnSync } from 'node:child_process';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { buildContext } from '../core/context.js';
+import { detectCommitsBehindMainDetailed } from '../core/execution-context.js';
 import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
+import { isLocatableId, locateEntity } from '../core/entity-locator.js';
+import { logger } from '../core/logger.js';
 import { generateClaimId, loadClaim, saveClaim, adoptClaimSession, releaseClaimWithCascade, claimBaselineFields } from '../core/claims.js';
 import { releaseClaimNextActions } from '../core/next-actions.js';
 import { reconcileClaimConformity } from '../core/claim-conformity.js';
@@ -44,6 +48,22 @@ export function parseTtl(ttl) {
     const ms = unit === 'm' ? value * 60_000 : unit === 'h' ? value * 3_600_000 : value * 86_400_000;
     return new Date(Date.now() + ms).toISOString();
 }
+/**
+ * Current git branch via an argv invocation — never a shell string (pln#618).
+ * Returns undefined when git is unavailable, cwd is not a repo, or HEAD is
+ * detached (`--show-current` prints nothing there).
+ */
+function currentGitBranch(cwd) {
+    const result = spawnSync('git', ['branch', '--show-current'], {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 5000,
+        windowsHide: true,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    return result.stdout.trim() || undefined;
+}
 export async function handleBclawClaim(payload, ctx) {
     const { name, args, cwd, connectionSessionId } = payload;
     // project=X naming a workspace sibling auto-localizes (session+switch then
@@ -156,37 +176,21 @@ export async function handleBclawClaim(payload, ctx) {
         : '';
     // Branch guardrail: warn if on master/main without a worktree
     let branchWarn = '';
-    if (!worktreePath) {
-        try {
-            const { execSync } = await import('node:child_process');
-            const branch = execSync('git branch --show-current', { cwd: claimCwd, encoding: 'utf-8' }).trim();
-            if (branch === 'master' || branch === 'main') {
-                const branchSlug = sanitizeBranchComponent(claimScope);
-                branchWarn = `\n⚠️ You are on ${branch}. Create a feature branch before editing: git checkout -b feat/${branchSlug}`;
-            }
-        }
-        catch { /* git not available, skip warning */ }
+    const currentBranch = currentGitBranch(claimCwd);
+    if (!worktreePath && (currentBranch === 'master' || currentBranch === 'main')) {
+        const branchSlug = sanitizeBranchComponent(claimScope);
+        branchWarn = `\n⚠️ You are on ${currentBranch}. Create a feature branch before editing: git checkout -b feat/${branchSlug}`;
     }
-    // Stale-branch detection: warn if behind master
+    // Stale-branch detection: warn if behind master/main. Branch names may
+    // legally contain shell metacharacters — the revspec goes through an argv
+    // invocation, never a shell string (pln#618).
     let staleBranchWarn = '';
-    try {
-        const { execSync: execSyncSB } = await import('node:child_process');
-        const currentBranch = execSyncSB('git branch --show-current', { cwd: claimCwd, encoding: 'utf-8' }).trim();
-        if (currentBranch && currentBranch !== 'master' && currentBranch !== 'main') {
-            for (const mainBranch of ['master', 'main']) {
-                try {
-                    const behind = execSyncSB(`git rev-list --count ${currentBranch}..${mainBranch}`, { cwd: claimCwd, encoding: 'utf-8' }).trim();
-                    const count = parseInt(behind, 10);
-                    if (count > 0) {
-                        staleBranchWarn = `\n⚠ Branch is ${count} commit(s) behind ${mainBranch}. Consider rebasing before editing.`;
-                    }
-                    break;
-                }
-                catch { /* branch doesn't exist, try next */ }
-            }
+    if (currentBranch && currentBranch !== 'master' && currentBranch !== 'main') {
+        const behind = detectCommitsBehindMainDetailed(claimCwd, currentBranch);
+        if (behind && behind.count > 0) {
+            staleBranchWarn = `\n⚠ Branch is ${behind.count} commit(s) behind ${behind.branch}. Consider rebasing before editing.`;
         }
     }
-    catch { /* git not available */ }
     const worktreeNote = worktreePath ? `\n  Worktree: ${worktreePath}` : '';
     const expiryNote = claimExpiresAt ? `\n  Expires: ${claimExpiresAt.slice(0, 16).replace('T', ' ')} UTC` : '';
     const handoffNote = handoffMode ? `\n  Handoff: ${handoffMode} (another agent will review and merge)` : '';
@@ -205,7 +209,7 @@ export async function handleBclawClaim(payload, ctx) {
     };
 }
 export async function handleBclawReleaseClaim(payload, ctx) {
-    const { args, cwd, connectionSessionId } = payload;
+    const { args, connectionSessionId } = payload;
     const crossProjectError = ctx.blockCrossProjectExecution('claim', args);
     if (crossProjectError) {
         return { response: crossProjectError };
@@ -214,11 +218,46 @@ export async function handleBclawReleaseClaim(payload, ctx) {
     if (!claimId) {
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: id') };
     }
+    // ── pln#649 F5, second surface: the CLAIM routes this call.
+    //
+    // `bclaw_assignment_update` was routed first because that is where the field
+    // defect was reproduced. This is the OTHER HALF of the same defect, documented in
+    // trp#1327: `bclaw_release_claim` has no `project` parameter either, so a worker
+    // whose resolved store is not the claim's got `Claim not found` and the claim
+    // stayed active forever. It only LOOKED fixed because completing an assignment
+    // cascade-releases its claim with the routed cwd — a worker that calls
+    // release_claim directly still fell in the hole.
+    //
+    // Same shape as the reviewed surface, deliberately: validate the id before any
+    // path is built, locate, refuse an ambiguity WITHOUT disclosing which projects
+    // (this runs before the ownership check, so an unauthenticated caller must learn a
+    // count and an action, never names or store paths), then rebind `cwd` ONCE so every
+    // downstream use — ownership check, cascade, plan status — is routed by construction.
+    if (!isLocatableId(claimId)) {
+        return { response: createToolErrorResponse('validation_error', `Invalid claim id '${claimId}'`) };
+    }
+    const located = locateEntity('claim', claimId, payload.cwd);
+    if (located.status === 'ambiguous') {
+        logger.warn(`ambiguous claim routing: ${claimId} found in `
+            + located.matches.map((m) => `${m.project_name ?? '(unnamed)'} @ ${m.cwd}`).join(', '));
+        return {
+            response: createToolErrorResponse('validation_error', `Claim ${claimId} exists in ${located.matches.length} projects reachable from here. `
+                + 'Refusing to guess which one you meant — call from the project that owns the work, '
+                + 'or ask an operator to resolve the duplicate (details are in the server log).', { claim_id: claimId, match_count: located.matches.length }),
+        };
+    }
+    const cwd = located.location?.cwd ?? payload.cwd;
     try {
         loadClaim(claimId, cwd); // validate existence before delegating
     }
     catch {
-        return { response: createToolErrorResponse('not_found', `Claim not found: ${claimId}`) };
+        const scope = located.enumeration_incomplete
+            ? `${located.probed.length} reachable project(s), and the search hit its depth ceiling so deeper projects were NOT examined`
+            : `all ${located.probed.length} reachable project(s)`;
+        logger.warn(`claim not found: ${claimId} — searched ${located.probed.join(', ')}`);
+        return {
+            response: createToolErrorResponse('not_found', `Claim not found: ${claimId} (searched ${scope})`, { claim_id: claimId, searched_count: located.probed.length, enumeration_incomplete: located.enumeration_incomplete }),
+        };
     }
     // pln#562 step 5 + trp#928 — release is ownership-checked like acquisition
     // and adoption. Under the trp#928 tightening the coordinator override is
@@ -538,7 +577,45 @@ export async function handleBclawSessionEnd(payload, ctx) {
     };
 }
 export async function handleBclawAssignmentUpdate(payload, ctx) {
-    const { args, cwd, connectionSessionId } = payload;
+    const { args, connectionSessionId } = payload;
+    // ── pln#649 step 3 (F5 of dec#153): the ENTITY routes this call, not the ambient
+    // cwd. This is the surface where the field defect was reproduced: a worker whose
+    // resolved store was not the assignment's got `Assignment not found`, and the
+    // assignment stayed `offered` forever with no way for the coordinator to fix it.
+    //
+    // ORDER IS LOAD-BEARING (review P2-6 of step 2). Routing MUST happen before
+    // ensureTrust: that call resolves identity and trust FROM A STORE, so running it
+    // on the ambient store can reject the caller before the locator ever gets to say
+    // which store owns the work. Same for loadAssignment below. So `cwd` is rebound
+    // once, here, and every downstream use is routed by construction — there is no
+    // second site to forget.
+    const assignmentIdArg = typeof args.assignment_id === 'string' ? args.assignment_id : undefined;
+    if (!assignmentIdArg)
+        return { response: createToolErrorResponse('input_error', 'assignment_id is required') };
+    if (!isLocatableId(assignmentIdArg)) {
+        return { response: createToolErrorResponse('input_error', `Invalid assignment_id '${assignmentIdArg}'`) };
+    }
+    const located = locateEntity('assignment', assignmentIdArg, payload.cwd);
+    if (located.status === 'ambiguous') {
+        // Two stores hold this id. Refusing is the point (T3): picking one would be a
+        // silent cross-project write, the failure mode dec#153 exists against.
+        //
+        // BUT SAY NOTHING ABOUT WHICH PROJECTS (review P2-3). This branch runs BEFORE
+        // ensureTrust — it has to, because trust is resolved FROM a store and the owning
+        // store is not known yet — so an unauthenticated caller who guesses a duplicated
+        // id would otherwise be handed project names and absolute paths. The first
+        // version of this message did exactly that. Routing before trust is required;
+        // DISCLOSING before trust is not, so the operator-facing detail goes to the
+        // server log and the caller gets a count and an action.
+        logger.warn(`ambiguous assignment routing: ${assignmentIdArg} found in `
+            + located.matches.map((m) => `${m.project_name ?? '(unnamed)'} @ ${m.cwd}`).join(', '));
+        return {
+            response: createToolErrorResponse('validation_error', `Assignment ${assignmentIdArg} exists in ${located.matches.length} projects reachable from here. `
+                + 'Refusing to guess which one you meant — call from the project that owns the work, '
+                + 'or ask an operator to resolve the duplicate (details are in the server log).', { assignment_id: assignmentIdArg, match_count: located.matches.length }),
+        };
+    }
+    const cwd = located.location?.cwd ?? payload.cwd;
     // Contributor trust: lowest dispatchable level. The agent-owner guard
     // below ensures only the assigned agent can update its own assignment.
     const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
@@ -546,10 +623,8 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
         return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
     }
     try {
-        const assignmentId = typeof args.assignment_id === 'string' ? args.assignment_id : undefined;
+        const assignmentId = assignmentIdArg;
         const status = typeof args.status === 'string' ? args.status : undefined;
-        if (!assignmentId)
-            return { response: createToolErrorResponse('input_error', 'assignment_id is required') };
         if (!status)
             return { response: createToolErrorResponse('input_error', 'status is required') };
         const message = args.message;
@@ -562,7 +637,24 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
         const { loadAssignment, transitionAssignment: transitionAsgn, recordProgress: recordProg } = await import('../core/assignments.js');
         const assignment = loadAssignment(assignmentId, cwd);
         if (!assignment) {
-            return { response: createToolErrorResponse('not_found', `Assignment not found: ${assignmentId}`) };
+            // Say WHERE we looked. "not found" used to be indistinguishable from "found
+            // in a store I was not routed to" — the exact ambiguity that made the field
+            // report hard to diagnose. And an incomplete enumeration must never read as a
+            // confident absence (step 2, enumeration_incomplete).
+            // The COUNT and the truncation flag are actionable and disclose nothing; the
+            // absolute store PATHS did (review P2-4: a contributor in A could submit an
+            // absent id and enumerate linked/nested project paths), so they go to the log.
+            const scope = located.enumeration_incomplete
+                ? `${located.probed.length} reachable project(s), and the search hit its depth ceiling so deeper projects were NOT examined`
+                : `all ${located.probed.length} reachable project(s)`;
+            logger.warn(`assignment not found: ${assignmentId} — searched ${located.probed.join(', ')}`);
+            return {
+                response: createToolErrorResponse('not_found', `Assignment not found: ${assignmentId} (searched ${scope})`, {
+                    assignment_id: assignmentId,
+                    searched_count: located.probed.length,
+                    enumeration_incomplete: located.enumeration_incomplete,
+                }),
+            };
         }
         // Agent guard: only the assigned agent can update
         const callerAgent = resolved.identity.agent_name;
@@ -758,17 +850,49 @@ export async function handleBclawAssignmentAction(payload, ctx) {
         return { response: createToolErrorResponse('operation_error', err instanceof Error ? err.message : String(err)) };
     }
 }
-export async function handleBclawAddStep(payload, ctx) {
+/**
+ * Route a plan-step mutation by its plan when one was named.  `planId` is a
+ * discriminator, not a suggestion: resolving trust and then editing the ambient
+ * store would reproduce the cross-project write defect this handler is meant to
+ * avoid.  Explicit `project` keeps its existing auto-localisation semantics.
+ */
+function resolvePlanStepWriteTarget(payload, ctx, planId) {
     const { args, cwd, connectionSessionId } = payload;
-    const stepLoc = ctx.resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
-    if (stepLoc.block) {
-        return { response: stepLoc.block };
+    if (args.project !== undefined) {
+        const explicit = ctx.resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+        if (explicit.block)
+            return { response: explicit.block };
+        return { targetCwd: explicit.targetCwd };
     }
-    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
+    // Short labels are resolved by the plan operation itself. They are not stable
+    // filesystem keys, so only a canonical id participates in locator routing.
+    if (!isLocatableId(planId))
+        return { targetCwd: cwd };
+    const located = locateEntity('plan', planId, cwd);
+    if (located.status === 'ambiguous') {
+        logger.warn(`ambiguous plan-step routing: ${planId} found in `
+            + located.matches.map((m) => `${m.project_name ?? '(unnamed)'} @ ${m.cwd}`).join(', '));
+        return {
+            response: createToolErrorResponse('validation_error', `Plan ${planId} exists in ${located.matches.length} projects reachable from here. `
+                + 'Refusing to guess which one you meant — call from the project that owns the plan, '
+                + 'or ask an operator to resolve the duplicate (details are in the server log).', { plan_id: planId, match_count: located.matches.length }),
+        };
+    }
+    return { targetCwd: located.location?.cwd ?? cwd };
+}
+export async function handleBclawAddStep(payload, ctx) {
+    const { args, connectionSessionId } = payload;
+    const stepPlanId = String(args.planId ?? '').trim();
+    if (!stepPlanId)
+        return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
+    const stepTarget = resolvePlanStepWriteTarget(payload, ctx, stepPlanId);
+    if (stepTarget.response)
+        return { response: stepTarget.response };
+    const stepTargetCwd = stepTarget.targetCwd;
+    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', stepTargetCwd, connectionSessionId);
     if (resolved.error) {
         return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
     }
-    const stepPlanId = String(args.planId ?? '').trim();
     const stepData = args.data && typeof args.data === 'object' && !Array.isArray(args.data)
         ? args.data
         : {};
@@ -780,11 +904,8 @@ export async function handleBclawAddStep(payload, ctx) {
     const stepAssignee = (stepData.assignee ?? args.assignee);
     const stepEstimated = (stepData.estimated_effort ?? args.estimated_effort);
     const stepActual = (stepData.actual_effort ?? args.actual_effort);
-    if (!stepPlanId)
-        return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
     if (!stepText)
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: data.text') };
-    const stepTargetCwd = stepLoc.targetCwd;
     try {
         const result = addStepOp({ planId: stepPlanId, text: stepText, assignee: stepAssignee, estimatedEffort: stepEstimated, actualEffort: stepActual }, stepTargetCwd);
         return {
@@ -805,22 +926,21 @@ export async function handleBclawAddStep(payload, ctx) {
     }
 }
 export async function handleBclawCompleteStep(payload, ctx) {
-    const { args, cwd, connectionSessionId } = payload;
-    const csLoc = ctx.resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
-    if (csLoc.block) {
-        return { response: csLoc.block };
-    }
-    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
-    if (resolved.error) {
-        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
-    }
+    const { args, connectionSessionId } = payload;
     const csPlanId = String(args.planId ?? '').trim();
     const csStepId = String(args.stepId ?? '').trim();
     if (!csPlanId)
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
     if (!csStepId)
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
-    const csTargetCwd = csLoc.targetCwd;
+    const csTarget = resolvePlanStepWriteTarget(payload, ctx, csPlanId);
+    if (csTarget.response)
+        return { response: csTarget.response };
+    const csTargetCwd = csTarget.targetCwd;
+    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', csTargetCwd, connectionSessionId);
+    if (resolved.error) {
+        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
+    }
     try {
         const result = completeStepOp({ planId: csPlanId, stepId: csStepId }, csTargetCwd);
         return {
@@ -842,15 +962,7 @@ export async function handleBclawCompleteStep(payload, ctx) {
     }
 }
 export async function handleBclawUpdateStep(payload, ctx) {
-    const { args, cwd, connectionSessionId } = payload;
-    const usLoc = ctx.resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
-    if (usLoc.block) {
-        return { response: usLoc.block };
-    }
-    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
-    if (resolved.error) {
-        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
-    }
+    const { args, connectionSessionId } = payload;
     const usPlanId = String(args.planId ?? '').trim();
     const usStepId = String(args.stepId ?? '').trim();
     if (!usPlanId)
@@ -861,7 +973,14 @@ export async function handleBclawUpdateStep(payload, ctx) {
     if (args.status && !validStatuses.includes(String(args.status))) {
         return { response: createToolErrorResponse('validation_error', `Invalid status: ${args.status}. Valid: ${validStatuses.join(', ')}`) };
     }
-    const usTargetCwd = usLoc.targetCwd;
+    const usTarget = resolvePlanStepWriteTarget(payload, ctx, usPlanId);
+    if (usTarget.response)
+        return { response: usTarget.response };
+    const usTargetCwd = usTarget.targetCwd;
+    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', usTargetCwd, connectionSessionId);
+    if (resolved.error) {
+        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
+    }
     try {
         const result = updateStepOp({
             planId: usPlanId,
@@ -902,22 +1021,21 @@ export async function handleBclawUpdateStep(payload, ctx) {
     }
 }
 export async function handleBclawDeleteStep(payload, ctx) {
-    const { args, cwd, connectionSessionId } = payload;
-    const dsLoc = ctx.resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
-    if (dsLoc.block) {
-        return { response: dsLoc.block };
-    }
-    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
-    if (resolved.error) {
-        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
-    }
+    const { args, connectionSessionId } = payload;
     const dsPlanId = String(args.planId ?? '').trim();
     const dsStepId = String(args.stepId ?? '').trim();
     if (!dsPlanId)
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
     if (!dsStepId)
         return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
-    const dsTargetCwd = dsLoc.targetCwd;
+    const dsTarget = resolvePlanStepWriteTarget(payload, ctx, dsPlanId);
+    if (dsTarget.response)
+        return { response: dsTarget.response };
+    const dsTargetCwd = dsTarget.targetCwd;
+    const resolved = ctx.ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', dsTargetCwd, connectionSessionId);
+    if (resolved.error) {
+        return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
+    }
     try {
         const result = deleteStepOp({ planId: dsPlanId, stepId: dsStepId }, dsTargetCwd);
         return {

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

@@ -13,7 +13,9 @@
  *
  * @module
  */
+import path from 'node:path';
 import { appendAuditEntry } from '../core/audit.js';
+import { isLocatableId, locateEntity } from '../core/entity-locator.js';
 import { nowISO, generateIdWithLabel } from '../core/ids.js';
 import { loadState, persistState, saveState } from '../core/state.js';
 import { ENTITY_REGISTRY } from '../core/entity-registry.js';
@@ -29,6 +31,53 @@ import { rejectCandidate } from './reject.js';
 import { applyHandoffUpdates } from './update-handoff.js';
 import { ensureTrust, resolveMutationIdentity, resolveCanonicalAuthor, renderAutoRepairWarning, scopeMetadataForTarget, scanMcpWriteText, appendSecurityWarnings, } from './mcp-write-support.js';
 import { SCHEMA_VERSION, toolResponse, createToolErrorResponse, } from './mcp-contract.js';
+/** Result shape of mcp.ts's resolveExecutionWriteTarget (structural mirror, PR3b). */
+/** Entity kinds the locator can find by id — the divergence check only applies there. */
+const LOCATABLE_FOR_DIVERGENCE = new Set(['assignment', 'claim', 'agent_run', 'plan', 'loop']);
+/**
+ * pln#649 / dec#153 T3: the ENTITY-vs-EXPLICIT-PROJECT refusal, shared by every
+ * canonical-grammar surface that receives BOTH authorities at once.
+ *
+ * IT LIVES HERE BECAUSE THERE ARE THREE CONSUMERS, NOT ONE. The first version was
+ * inline in `bclaw_transition` and its comment claimed that was "the ONLY canonical
+ * grammar surface where both authorities are supplied at once" — FALSE, found by a
+ * Fable audit: `bclaw_update` and `bclaw_remove` take the same pair and had no guard,
+ * so the misleading `not found` the guard exists to kill survived on two surfaces
+ * operators reach the same way. Copying the block a third time is how the by-id
+ * duplication earlier in this plan happened; one function, three call sites.
+ *
+ * Without it a divergence produces a misleading `not found in <B>`: the record exists,
+ * just not where the caller named, which leaves them doubting their id. dec#153 says
+ * an explicit divergence must be REFUSED and NAMED so they learn which of their two
+ * statements was wrong.
+ *
+ * DISCLOSURE RULE from the two routed surfaces: the project the caller TYPED is
+ * already theirs, so naming it back is free — but WHERE the entity actually lives is
+ * new information, so that is a COUNT, never a name.
+ *
+ * The remedy sentence is deliberately not "drop `project` to be routed by the entity",
+ * which the first version said and which is not true: dropping `project` falls back to
+ * AMBIENT resolution, not to the entity. An error message that misstates its own fix
+ * is worse than a comment that does.
+ */
+function refuseEntityProjectDivergence(entity, id, requestedProject, targetCwd, cwd) {
+    if (requestedProject === undefined || !id || !isLocatableId(id))
+        return undefined;
+    if (!LOCATABLE_FOR_DIVERGENCE.has(entity))
+        return undefined;
+    const located = locateEntity(entity, id, cwd);
+    const target = path.resolve(targetCwd);
+    // Only fires when the entity was found SOMEWHERE ELSE: a genuine not-found stays a
+    // not-found, and an agreement is never refused.
+    if (located.matches.length === 0)
+        return undefined;
+    if (located.matches.some((m) => path.resolve(m.cwd) === target))
+        return undefined;
+    return createToolErrorResponse('validation_error', `${entity} '${id}' does not live in project '${String(requestedProject)}' — it exists in `
+        + `${located.matches.length} other reachable project(s). Refusing: the entity and the project you named `
+        + 'disagree, and guessing which one you meant is how a write lands in the wrong project. '
+        + 'Call from the project that owns it, or name that project.', { entity, id, requested_project: String(requestedProject), located_elsewhere_count: located.matches.length });
+}
 export function handleBclawCreatePlan(payload, ctx) {
     const { args, cwd, connectionSessionId } = payload;
     const crossProjectError = ctx.blockCrossProjectExecution('plan', args);
@@ -462,6 +511,12 @@ export function handleBclawUpdate(payload, ctx) {
         const id = String(args.id ?? '');
         const patch = (args.patch ?? {});
         const targetCwd = resolveProjectCwd(args.project, cwd);
+        // dec#153 T3 — this surface takes both authorities too (Fable audit; #182's comment
+        // claimed transition was the only one). Refuse BEFORE updateEntity, whose
+        // `not found` would otherwise be the misleading message the guard exists to kill.
+        const updateDivergence = refuseEntityProjectDivergence(entity, id, args.project, targetCwd, cwd);
+        if (updateDivergence)
+            return { response: updateDivergence };
         const targetScope = scopeMetadataForTarget(args, targetCwd, ctx.scopeInfo);
         const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
         // S2 (pln#623): scan the patched text field on the MCP path (CLI parity).
@@ -497,6 +552,12 @@ export function handleBclawRemove(payload, ctx) {
         const id = String(args.id ?? '');
         const purge = args.purge === true;
         const targetCwd = resolveProjectCwd(args.project, cwd);
+        // dec#153 T3 — same pair of authorities, and the highest stakes of the three: a
+        // divergence here means the caller is about to remove (or purge) in a project that
+        // does not hold the entity they named.
+        const removeDivergence = refuseEntityProjectDivergence(entity, id, args.project, targetCwd, cwd);
+        if (removeDivergence)
+            return { response: removeDivergence };
         const targetScope = scopeMetadataForTarget(args, targetCwd, ctx.scopeInfo);
         const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
         const result = removeEntity(entity, id, targetCwd, purge);
@@ -572,6 +633,12 @@ export function handleBclawTransition(payload, ctx) {
         const id = String(args.id ?? '');
         const to = String(args.to ?? '');
         const reason = args.reason;
+        // pln#649 / dec#153 T3 — shared with bclaw_update and bclaw_remove, which take the
+        // same pair of authorities. `bclaw_transition` is the call trp#1327 documents as the
+        // coordinator's workaround, so operators reach it; it is not the only one.
+        const transitionDivergence = refuseEntityProjectDivergence(entity, id, args.project, targetCwd, cwd);
+        if (transitionDivergence)
+            return { response: transitionDivergence };
         const targetScope = scopeMetadataForTarget(args, targetCwd, ctx.scopeInfo);
         const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
         // trp#928 — claim transitions consume the ReleaseClaimAuth ownership

package/dist/commands/mcp.js

@@ -23,6 +23,8 @@ import { loadAllSessions } from '../core/identity.js';
 // Setup wizard / project-init / registry helpers now live in mcp-write-admin.ts (PR4).
 // Canonical entity write handlers now live in mcp-write-entities.ts (PR4).
 import { findOutermostBrainclawRoot, resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef } from '../core/store-resolution.js';
+import { isLocatableId, locateEntity } from '../core/entity-locator.js';
+import { logger } from '../core/logger.js';
 import { switchProject } from './switch.js';
 import { assessBootstrapNeed, resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { WorkRequestSchema } from '../core/facade-schema.js';
@@ -1847,8 +1849,69 @@ export async function executeMcpToolCall(payload) {
     const effective = payload.name === 'bclaw_switch'
         ? { cwd: baseCwd, active_source: 'cwd', resolved_project: undefined }
         : resolveEffectiveCwdInfo({ baseCwd, sessionId: payload.connectionSessionId });
-    const cwd = effective.cwd;
     const envClaimId = process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined;
+    // ── pln#649 F5, last surface: a WORKER's ambient mutation is routed by its CLAIM.
+    //
+    // The routed surfaces so far all take an entity id, so the entity could do the
+    // routing. This covers the other half of F5: the mutations a dispatched worker makes
+    // with NO entity to name — capturing a trap, writing a note. Those fell through the
+    // whole ambient ladder (session → cwd_child → shared global pointer) and landed
+    // wherever it pointed, which for a worker is the original field defect.
+    //
+    // The rule is NOT "refuse because nothing was named" — a worker HAS a discriminant:
+    // `BRAINCLAW_CLAIM_ID`, the one selector deliberately preserved in its env
+    // (execution-profile.ts). So the claim names the project, and the write follows it.
+    //
+    // MUTATIONS ONLY, by explicit list. dec#155 keeps READS on the ambient anchor — a
+    // worker reading shared context workspace-wide is correct — and a blanket switch
+    // across ~40 tools would be a behaviour change nobody asked for. This is the set a
+    // dispatched worker actually calls without an entity id; extending it is mechanical.
+    const WORKER_AMBIENT_MUTATIONS = new Set([
+        'bclaw_write_note', 'bclaw_quick_capture', 'bclaw_send_message', 'bclaw_create',
+    ]);
+    let cwd = effective.cwd;
+    if (envClaimId && WORKER_AMBIENT_MUTATIONS.has(payload.name) && isLocatableId(envClaimId)) {
+        let ambiguity;
+        try {
+            const owner = locateEntity('claim', envClaimId, cwd);
+            if (owner.status === 'ambiguous') {
+                // RESTRICTED REFUSAL — operator decision, 2026-08-06, settling a genuine
+                // disagreement between two reviewers on this exact branch. `ambiguous` means two
+                // reachable stores hold this claim id: the divergence is PROVEN, so dec#153's
+                // refusal applies and falling back to ambient would silently write to a store the
+                // entity does not authorise — the original field defect, in a corner.
+                //
+                // NOT_FOUND DELIBERATELY KEEPS THE AMBIENT ANSWER, which is the "restricted" half
+                // and not an oversight. A claim that cannot be found is not a divergence, it is an
+                // absence, and the benign causes dominate: the enumeration may not reach the
+                // claim's store at all (`enumeration_incomplete`), and a RELEASED or archived claim
+                // legitimately stops being findable — refusing there would break every mutation a
+                // worker makes after releasing, which no decision asks for. The strict reading
+                // (refuse on both) was the other reviewer's position and was considered.
+                ambiguity = owner.matches.length;
+            }
+            else if (owner.status === 'found' && owner.location && path.resolve(owner.location.cwd) !== path.resolve(cwd)) {
+                cwd = owner.location.cwd;
+            }
+            if (ambiguity !== undefined) {
+                // Names and store paths go to the OPERATOR's log, never to the caller: this branch
+                // runs before any trust check, so the response carries a count and an action only
+                // — the same disclosure rule the two entity-routed surfaces were reviewed into.
+                logger.warn(`ambiguous worker-claim routing: ${envClaimId} found in `
+                    + `${owner.matches.map((m) => `${m.project_name ?? '(unnamed)'} @ ${m.cwd}`).join(', ')}`);
+            }
+        }
+        catch { /* never break a tool call over routing — fall back to the ambient answer */ }
+        if (ambiguity !== undefined) {
+            return {
+                response: createToolErrorResponse('validation_error', `Your claim '${envClaimId}' exists in ${ambiguity} reachable projects, so this `
+                    + `${payload.name} cannot be routed to the project that owns your work. Refusing rather than `
+                    + 'guessing: guessing is how a write lands in another project. Ask an operator to resolve the '
+                    + 'duplicate claim id (details are in the server log).', { claim_id: envClaimId, match_count: ambiguity }),
+                toolName: payload.name,
+            };
+        }
+    }
     // ── Auto-session ────────────────────────────────────────────────────────────
     let autoSessionId;
     let effectiveConnectionSessionId = payload.connectionSessionId;