brainclaw 1.5.4 → 1.5.5

package/dist/commands/mcp.js

@@ -4887,7 +4887,7 @@ async function _executeMcpToolCallInner(payload) {
                 // dispatch analysis / review.
                 const { listAssignments: listAsgn } = await import('../core/assignments.js');
                 const predecessors = listAsgn(dispatchCwd, { claim_id: oldClaim.id })
-                    .filter((a) => a.status !== 'completed' && a.status !== 'expired' && a.status !== 'rerouted');
+                    .filter((a) => a.status !== 'completed' && a.status !== 'cancelled' && a.status !== 'expired' && a.status !== 'rerouted');
                 for (const predecessor of predecessors) {
                     try {
                         transitionAssignment(predecessor.id, 'rerouted', {
@@ -5495,7 +5495,10 @@ async function _executeMcpToolCallInner(payload) {
  * break tool execution.
  */
 export async function executeMcpToolCall(payload) {
-    const { cwd } = payload;
+    const baseCwd = payload.cwd;
+    const cwd = payload.name === 'bclaw_switch'
+        ? baseCwd
+        : resolveEffectiveCwd({ baseCwd });
     const envClaimId = process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined;
     // ── Auto-session ────────────────────────────────────────────────────────────
     let autoSessionId;
@@ -5522,7 +5525,7 @@ export async function executeMcpToolCall(payload) {
                 // no longer show session_id="unknown".
                 try {
                     const { listAssignments: listA, saveAssignment: saveA } = await import('../core/assignments.js');
-                    const active = listA(cwd, { claim_id: envClaimId }).filter((a) => !['completed', 'expired', 'rerouted'].includes(a.status));
+                    const active = listA(cwd, { claim_id: envClaimId }).filter((a) => !['completed', 'cancelled', 'expired', 'rerouted'].includes(a.status));
                     for (const a of active) {
                         if (!a.session_id) {
                             a.session_id = autoSessionId;
@@ -5545,6 +5548,7 @@ export async function executeMcpToolCall(payload) {
     // ── Delegate to inner handler ───────────────────────────────────────────────
     const outcome = await _executeMcpToolCallInner({
         ...payload,
+        cwd,
         connectionSessionId: effectiveConnectionSessionId,
     });
     // Apply legacy deprecation warning uniformly (Phase 3 slice 3g). Read tools

package/dist/commands/setup.js

@@ -305,6 +305,91 @@ export function printReloadReminder(detectedAgent) {
         console.log('  → Restart your AI coding agent to pick up the new MCP configuration.');
     }
 }
+function logDetectedAgentSurfaces(detectedName, detectedSurfaces) {
+    console.log('');
+    if (detectedName) {
+        console.log(`Detected AI agent: ${detectedName}`);
+    }
+    else {
+        console.log('No AI agent detected automatically.');
+    }
+    const visibleSurfaces = detectedSurfaces.filter((surface) => surface.status !== 'not_detected');
+    if (visibleSurfaces.length > 0) {
+        console.log('Other AI work surfaces on this machine:');
+        for (const surface of visibleSurfaces) {
+            console.log(`  - ${surface.display_name} [${surface.surface_kind}, ${surface.status}]`);
+        }
+        const usageHints = renderAiSurfaceUsageHints(visibleSurfaces);
+        if (usageHints.length > 0) {
+            console.log('');
+            console.log('Suggested uses:');
+            for (const line of usageHints) {
+                console.log(`  ${line}`);
+            }
+        }
+        console.log('');
+        console.log('These surfaces are tracked separately from coding agents and will use tailored onboarding flows.');
+    }
+}
+async function resolveSelectedAgentsForSetup(options, detectedName) {
+    console.log('Supported agents:');
+    ALL_KNOWN_AGENTS.forEach((a, i) => {
+        const tag = a === detectedName ? ' ← detected' : '';
+        console.log(`  ${i + 1}) ${a}${tag}`);
+    });
+    let agentChoice;
+    if (options.agents) {
+        agentChoice = options.agents;
+    }
+    else if (options.yes || !process.stdin.isTTY) {
+        agentChoice = detectedName ? 'detected' : 'all';
+    }
+    else {
+        const defaultChoice = detectedName ? 'detected' : 'all';
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            agentChoice = (await rl.question(`Configure agents: (d)etected, (a)ll, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const selectedAgents = parseAgentSelection(agentChoice, detectedName);
+    console.log(`Selected agents: ${selectedAgents.length === 0 ? '(none)' : selectedAgents.join(', ')}`);
+    return selectedAgents;
+}
+export async function runSetupMachine(options = {}) {
+    const env = process.env;
+    const detectedAi = detectAiAgent(env);
+    const detectedName = detectedAi?.name;
+    const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
+    const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    console.log(BRAINCLAW_ASCII);
+    console.log('Machine bootstrap only — no repositories will be scanned or initialized.');
+    logDetectedAgentSurfaces(detectedName, detectedSurfaces);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    console.log('\n→ Installing machine-level brainclaw prerequisites...');
+    const written = runGlobalInstall(selectedAgents, env);
+    if (written.length > 0) {
+        for (const filePath of written) {
+            console.log(`  ✔ ${filePath}`);
+        }
+    }
+    else {
+        console.log('  (all machine-level prerequisites already up to date)');
+    }
+    installVscodeExtension();
+    writeSetupState({
+        completed_at: new Date().toISOString(),
+        roots: [],
+        initialised_repos: [],
+        global_configs_written: selectedAgents,
+    }, env);
+    printReloadReminder(detectedName);
+    console.log('');
+    console.log('Next step: run `brainclaw init` inside the project you want to create or refresh.');
+    console.log('If the project already has .brainclaw/ and you want to register another agent explicitly, run `brainclaw enable-agent <agent-name>` there.');
+}
 // ─── Main CLI wizard ──────────────────────────────────────────────────────────
 export async function runSetup(options = {}) {
     const env = process.env;
@@ -399,54 +484,8 @@ export async function runSetup(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
-    console.log('');
-    if (detectedName) {
-        console.log(`Detected AI agent: ${detectedName}`);
-    }
-    else {
-        console.log('No AI agent detected automatically.');
-    }
-    const visibleSurfaces = detectedSurfaces.filter((surface) => surface.status !== 'not_detected');
-    if (visibleSurfaces.length > 0) {
-        console.log('Other AI work surfaces on this machine:');
-        for (const surface of visibleSurfaces) {
-            console.log(`  - ${surface.display_name} [${surface.surface_kind}, ${surface.status}]`);
-        }
-        const usageHints = renderAiSurfaceUsageHints(visibleSurfaces);
-        if (usageHints.length > 0) {
-            console.log('');
-            console.log('Suggested uses:');
-            for (const line of usageHints) {
-                console.log(`  ${line}`);
-            }
-        }
-        console.log('');
-        console.log('These surfaces are tracked separately from coding agents and will use tailored onboarding flows.');
-    }
-    console.log('Supported agents:');
-    ALL_KNOWN_AGENTS.forEach((a, i) => {
-        const tag = a === detectedName ? ' ← detected' : '';
-        console.log(`  ${i + 1}) ${a}${tag}`);
-    });
-    let agentChoice;
-    if (options.agents) {
-        agentChoice = options.agents;
-    }
-    else if (options.yes || !process.stdin.isTTY) {
-        agentChoice = detectedName ? 'detected' : 'all';
-    }
-    else {
-        const defaultChoice = detectedName ? 'detected' : 'all';
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        try {
-            agentChoice = (await rl.question(`Configure agents: (d)etected, (a)ll, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
-        }
-        finally {
-            rl.close();
-        }
-    }
-    const selectedAgents = parseAgentSelection(agentChoice, detectedName);
-    console.log(`Selected agents: ${selectedAgents.length === 0 ? '(none)' : selectedAgents.join(', ')}`);
+    logDetectedAgentSurfaces(detectedName, detectedSurfaces);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
     // Step 5: Global install
     console.log('\n→ Installing global brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);

package/dist/commands/switch.js

@@ -244,6 +244,10 @@ function listProjects(wsRoot, json) {
  * this returns the farthest one — the true multi-project workspace root.
  */
 function findOutermostWorkspaceRoot(startDir) {
+    const envWorkspace = process.env.BRAINCLAW_CWD?.trim();
+    if (envWorkspace && memoryExists(path.resolve(envWorkspace))) {
+        return path.resolve(envWorkspace);
+    }
     let dir = path.resolve(startDir);
     const root = path.parse(dir).root;
     const home = process.env.HOME || process.env.USERPROFILE || root;

package/dist/core/agentruns.js

@@ -320,6 +320,16 @@ export function syncAgentRunFromAssignmentTransition(assignment, newStatus, opti
                 artifacts: options.artifacts,
             }, cwd);
             return;
+        case 'cancelled':
+            if (!canTransitionRun(run, 'cancelled'))
+                return;
+            transitionAgentRun(run.id, 'cancelled', {
+                actor: options.actor,
+                actor_id: options.actor_id,
+                session_id: options.session_id,
+                status_reason: options.status_reason ?? 'Cancelled via assignment lifecycle',
+            }, cwd);
+            return;
         case 'failed':
             if (!canTransitionRun(run, 'failed'))
                 return;

package/dist/core/assignments.js

@@ -64,6 +64,22 @@ export function listAssignments(cwd, filter) {
         items = items.filter((a) => a.sequence_id === filter.sequence_id);
     return items;
 }
+export function deleteAssignment(id, cwd) {
+    const store = assignmentStore(cwd);
+    if (!store.exists(id)) {
+        return false;
+    }
+    mutate({ cwd }, () => {
+        const writableStore = new JsonStore({
+            dirPath: assignmentsDir(cwd, 'write'),
+            documentType: 'assignment',
+            getId: (a) => a.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        writableStore.delete(id);
+    });
+    return true;
+}
 // ── ID Generation ────────────────────────────────────────────
 export function generateAssignmentId(cwd) {
     return generateIdWithLabel('assignments', cwd);
@@ -78,15 +94,15 @@ export function generateAssignmentId(cwd) {
  * rerouted a still-unstarted lane.
  */
 const VALID_TRANSITIONS = new Map([
-    ['created', new Set(['offered', 'rerouted'])],
-    ['offered', new Set(['accepted', 'failed', 'expired', 'rerouted'])],
-    ['accepted', new Set(['started', 'timed_out', 'rerouted'])],
-    ['started', new Set(['completed', 'failed', 'blocked', 'timed_out', 'rerouted'])],
-    ['failed', new Set(['retrying', 'rerouted'])],
-    ['timed_out', new Set(['retrying', 'rerouted'])],
-    ['retrying', new Set(['offered', 'rerouted'])],
-    ['blocked', new Set(['rerouted', 'started', 'failed'])],
-    // Terminal: completed, expired, rerouted (no outgoing transitions)
+    ['created', new Set(['offered', 'rerouted', 'cancelled'])],
+    ['offered', new Set(['accepted', 'failed', 'expired', 'rerouted', 'cancelled'])],
+    ['accepted', new Set(['started', 'timed_out', 'rerouted', 'cancelled'])],
+    ['started', new Set(['completed', 'failed', 'blocked', 'timed_out', 'rerouted', 'cancelled'])],
+    ['failed', new Set(['retrying', 'rerouted', 'cancelled'])],
+    ['timed_out', new Set(['retrying', 'rerouted', 'cancelled'])],
+    ['retrying', new Set(['offered', 'rerouted', 'cancelled'])],
+    ['blocked', new Set(['rerouted', 'started', 'failed', 'cancelled'])],
+    // Terminal: completed, cancelled, expired, rerouted (no outgoing transitions)
 ]);
 export function validateTransition(from, to) {
     const allowed = VALID_TRANSITIONS.get(from);
@@ -148,6 +164,9 @@ export function transitionAssignment(id, newStatus, options, cwd) {
         case 'completed':
             assignment.completed_at = now;
             break;
+        case 'cancelled':
+            assignment.cancelled_at = now;
+            break;
         case 'failed':
             assignment.failed_at = now;
             break;
@@ -280,7 +299,7 @@ export function createAssignment(options, cwd) {
 }
 // ── Active Assignment Lookup ─────────────────────────────────
 /** Statuses that indicate a finished assignment (no longer active). */
-const TERMINAL_STATUSES = new Set(['completed', 'expired', 'rerouted']);
+const TERMINAL_STATUSES = new Set(['completed', 'cancelled', 'expired', 'rerouted']);
 /**
  * Return the most recently created non-terminal assignment for the given agent.
  * When `claimId` is provided, it is used as a fast-path lookup before falling

package/dist/core/context.js

@@ -445,7 +445,7 @@ export function buildContext(options = {}) {
     const currentSession = loadCurrentSession(contextCwd);
     if (currentAgentIdentity || agent) {
         const claimPlanIds = new Set(myClaims.map((c) => c.plan_id).filter(Boolean));
-        const activeAssignments = listAssignments(contextCwd, { agent: agentName }).filter((assignment) => !['completed', 'failed', 'expired', 'rerouted'].includes(assignment.status));
+        const activeAssignments = listAssignments(contextCwd, { agent: agentName }).filter((assignment) => !['completed', 'failed', 'cancelled', 'expired', 'rerouted'].includes(assignment.status));
         const inProgressPlans = state.plan_items.filter((p) => p.status === 'in_progress' &&
             (p.assignee === agentName || claimPlanIds.has(p.id)));
         if (myClaims.length > 0 || activeAssignments.length > 0 || inProgressPlans.length > 0) {

package/dist/core/coordination.js

@@ -88,7 +88,7 @@ export function buildCoordinationSnapshot(options = {}) {
             : filteredClaims,
         active_assignments: (agent
             ? listAssignments(options.cwd, { agent })
-            : listAssignments(options.cwd)).filter((assignment) => !['completed', 'failed', 'expired', 'rerouted'].includes(assignment.status) &&
+            : listAssignments(options.cwd)).filter((assignment) => !['completed', 'failed', 'cancelled', 'expired', 'rerouted'].includes(assignment.status) &&
             (!project || !assignment.plan_id || filteredPlans.some((plan) => plan.id === assignment.plan_id))),
         active_runs: (agent
             ? listAgentRuns(options.cwd, { agent })

package/dist/core/entity-operations.js

@@ -17,7 +17,7 @@ import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
 import { listClaims } from './claims.js';
 import { listActionRequired } from './actions.js';
-import { listAssignments } from './assignments.js';
+import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
@@ -309,6 +309,14 @@ export function updateEntity(name, id, patch, cwd) {
             saveRuntimeNote(patched, cwd);
             return { entity: name, id };
         }
+        case 'assignment': {
+            const assignment = loadAssignment(id, cwd);
+            if (!assignment)
+                throw new EntityNotFoundError(name, id);
+            const patched = { ...assignment, ...patch };
+            saveAssignment(patched, cwd);
+            return { entity: name, id };
+        }
         case 'candidate': {
             const candidate = loadCandidate(id, cwd);
             const patched = { ...candidate, ...patch };
@@ -371,6 +379,28 @@ export function removeEntity(name, id, cwd, purge = false) {
             const removed = removeCrossProjectLink(id, cwd);
             return { entity: name, id: removed.name ?? removed.path, archived: false, purged: true };
         }
+        case 'assignment': {
+            const assignment = loadAssignment(id, cwd);
+            if (!assignment)
+                throw new EntityNotFoundError(name, id);
+            if (purge) {
+                const deleted = deleteAssignment(id, cwd);
+                if (!deleted)
+                    throw new EntityNotFoundError(name, id);
+                return { entity: name, id, archived: false, purged: true };
+            }
+            if (assignment.status === 'cancelled') {
+                return { entity: name, id, archived: true, purged: false };
+            }
+            if (ENTITY_REGISTRY.assignment.terminal.includes(assignment.status)) {
+                throw new Error(`assignment '${id}' is already terminal (${assignment.status}); use purge:true to hard-delete if needed`);
+            }
+            transitionAssignment(id, 'cancelled', {
+                actor: 'brainclaw',
+                status_reason: 'Archived via bclaw_remove',
+            }, cwd);
+            return { entity: name, id, archived: true, purged: false };
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'remove');
     }
@@ -418,6 +448,13 @@ export function transitionEntity(name, id, to, cwd, _reason) {
             }
             throw new InvalidTransitionError(name, from, to);
         }
+        case 'assignment': {
+            transitionAssignment(id, to, {
+                actor: 'brainclaw',
+                status_reason: _reason,
+            }, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
     }

package/dist/core/entity-registry.js

@@ -234,24 +234,25 @@ const assignment = {
     name: 'assignment',
     shortLabelPrefix: 'asgn',
     schema: AssignmentSchema,
-    updatable: ['brief', 'tags'],
+    updatable: ['description', 'status_reason', 'tags'],
     statusField: 'status',
     transitions: {
-        created: ['offered', 'expired'],
-        offered: ['accepted', 'expired', 'rerouted'],
-        accepted: ['started', 'failed', 'timed_out'],
-        started: ['completed', 'failed', 'blocked', 'timed_out'],
-        failed: ['retrying'],
-        timed_out: ['retrying'],
-        retrying: ['offered'],
-        blocked: ['started', 'rerouted', 'failed'],
+        created: ['offered', 'expired', 'rerouted', 'cancelled'],
+        offered: ['accepted', 'expired', 'rerouted', 'failed', 'cancelled'],
+        accepted: ['started', 'failed', 'timed_out', 'rerouted', 'cancelled'],
+        started: ['completed', 'failed', 'blocked', 'timed_out', 'rerouted', 'cancelled'],
+        failed: ['retrying', 'rerouted', 'cancelled'],
+        timed_out: ['retrying', 'rerouted', 'cancelled'],
+        retrying: ['offered', 'rerouted', 'cancelled'],
+        blocked: ['started', 'rerouted', 'failed', 'cancelled'],
     },
-    terminal: ['completed', 'expired', 'rerouted'],
+    terminal: ['completed', 'cancelled', 'expired', 'rerouted'],
     sideEffects: {
         'created->offered': ['timestamp:offered_at', 'event:assignment_offered', 'audit:assignment_offered'],
         'offered->accepted': ['timestamp:accepted_at', 'event:assignment_accepted', 'sync:agent_run'],
         'accepted->started': ['timestamp:started_at', 'event:assignment_started', 'sync:agent_run'],
         'started->completed': ['timestamp:completed_at', 'event:assignment_completed', 'sync:agent_run'],
+        'started->cancelled': ['timestamp:cancelled_at', 'event:assignment_cancelled', 'sync:agent_run'],
         'started->failed': ['timestamp:failed_at', 'event:assignment_failed', 'sync:agent_run'],
     },
 };

package/dist/core/schema.js

@@ -598,6 +598,7 @@ export const AssignmentStatusSchema = z.enum([
     'accepted', // Worker acknowledged receipt
     'started', // Worker reports active work begun
     'completed', // Worker reports successful completion
+    'cancelled', // Supervisor/admin aborted the assignment explicitly
     'failed', // Worker reports failure
     'blocked', // Worker reports external blocker
     'timed_out', // Sweeper detected no heartbeat within TTL
@@ -642,6 +643,7 @@ export const AssignmentSchema = z.object({
     accepted_at: z.string().optional(),
     started_at: z.string().optional(),
     completed_at: z.string().optional(),
+    cancelled_at: z.string().optional(),
     failed_at: z.string().optional(),
     blocked_at: z.string().optional(),
     timed_out_at: z.string().optional(),
@@ -814,6 +816,7 @@ export const RuntimeEventTypeSchema = z.enum([
     'assignment_started',
     'assignment_progress',
     'assignment_completed',
+    'assignment_cancelled',
     'assignment_failed',
     'assignment_blocked',
     'assignment_timed_out',

package/dist/core/store-resolution.js

@@ -91,48 +91,53 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
  *
  * Priority:
  * 1. explicitCwd (--cwd flag)
- * 2. BRAINCLAW_CWD env var → absolute workspace path injected by MCP configs
- * 3. BRAINCLAW_PROJECT env var → resolved by name/path from workspace
- * 4. Session-scoped active project (from .current-session)
+ * 2. BRAINCLAW_CWD env var → workspace anchor injected by MCP configs
+ * 3. BRAINCLAW_PROJECT env var → resolved by name/path from workspace anchor
+ * 4. Session-scoped active project (from .current-session under the anchor)
  * 5. Global active-project.json in workspace root
- * 6. process.cwd()
+ * 6. Workspace anchor or process.cwd()
  */
 export function resolveEffectiveCwd(options = {}) {
+    const baseCwd = path.resolve(options.baseCwd ?? process.cwd());
     // 1. Explicit --cwd flag
     if (options.explicitCwd) {
         return path.resolve(options.explicitCwd);
     }
-    // 2. BRAINCLAW_CWD env var — set by MCP configs to bind to the workspace
-    //    regardless of the IDE's process.cwd() at launch time
+    // 2. BRAINCLAW_CWD env var — set by MCP configs to anchor resolution to the
+    //    workspace regardless of the IDE's process.cwd() at launch time. It is a
+    //    workspace anchor, not the final answer: session/global active project
+    //    state still overrides it.
+    let anchorCwd = baseCwd;
     const envCwd = process.env.BRAINCLAW_CWD?.trim();
-    if (envCwd && fs.existsSync(path.join(path.resolve(envCwd), MEMORY_DIR, 'config.yaml'))) {
-        return path.resolve(envCwd);
+    const hasEnvWorkspace = !!envCwd && fs.existsSync(path.join(path.resolve(envCwd), MEMORY_DIR, 'config.yaml'));
+    if (hasEnvWorkspace) {
+        anchorCwd = path.resolve(envCwd);
     }
     // 3. BRAINCLAW_PROJECT env var
     const envProject = process.env.BRAINCLAW_PROJECT;
     if (envProject) {
-        const resolved = resolveProjectRef(envProject, process.cwd(), options.storeChainOptions);
+        const resolved = resolveProjectRef(envProject, anchorCwd, options.storeChainOptions);
         if (resolved)
             return resolved;
     }
-    // 3. Session-scoped active project (per-agent, no cross-agent interference)
-    const session = loadCurrentSession(process.cwd());
+    // 4. Session-scoped active project (per-agent, no cross-agent interference)
+    const session = loadCurrentSession(anchorCwd);
     if (session?.active_project) {
         const sp = session.active_project;
         if (fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
             return sp.path;
         }
     }
-    // 4. Global active-project.json from workspace root
-    const wsRoot = resolveWorkspaceRoot(process.cwd(), options.storeChainOptions);
+    // 5. Global active-project.json from workspace root
+    const wsRoot = hasEnvWorkspace ? anchorCwd : resolveWorkspaceRoot(anchorCwd, options.storeChainOptions);
     if (wsRoot) {
         const active = loadActiveProject(wsRoot);
         if (active && fs.existsSync(path.join(active.path, MEMORY_DIR, 'config.yaml'))) {
             return active.path;
         }
     }
-    // 5. Default
-    return process.cwd();
+    // 6. Default
+    return anchorCwd;
 }
 /**
  * Find the workspace root (farthest store in the chain, or the one with
@@ -150,9 +155,14 @@ export function resolveWorkspaceRoot(cwd = process.cwd(), options = {}) {
  * Returns undefined when the reference cannot be resolved to a valid brainclaw project.
  */
 export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
+    const envWorkspace = process.env.BRAINCLAW_CWD?.trim();
+    const workspaceAnchor = envWorkspace && fs.existsSync(path.join(path.resolve(envWorkspace), MEMORY_DIR, 'config.yaml'))
+        ? path.resolve(envWorkspace)
+        : undefined;
     // Walk UP from real cwd to find the outermost .brainclaw/ — this avoids
     // circular resolution when an active project narrows the workspace view.
-    const wsRoot = findOutermostBrainclawRoot(process.cwd())
+    const wsRoot = workspaceAnchor
+        ?? findOutermostBrainclawRoot(cwd)
         ?? resolveWorkspaceRoot(cwd, storeChainOptions);
     if (!wsRoot)
         return undefined;

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.5.4 on 2026-05-10T22:45:47.168Z
+// Source: brainclaw v1.5.5 on 2026-05-13T19:24:16.549Z
 export const FACTS = {
-  "version": "1.5.4",
-  "generated_at": "2026-05-10T22:45:47.168Z",
+  "version": "1.5.5",
+  "generated_at": "2026-05-13T19:24:16.549Z",
   "tools": {
     "count": 60,
     "published_count": 59,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.5.4",
-  "generated_at": "2026-05-10T22:45:47.168Z",
+  "version": "1.5.5",
+  "generated_at": "2026-05-13T19:24:16.549Z",
   "tools": {
     "count": 60,
     "published_count": 59,