brainclaw 1.5.4 → 1.6.0

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

@@ -3,6 +3,7 @@ import { loadActiveProject, saveActiveProject, clearActiveProject } from '../cor
 import { loadCurrentSession, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
+import { resolveProjectCwd } from '../core/cross-project.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
 import { loadConfig } from '../core/config.js';
 /**
@@ -16,7 +17,22 @@ export function switchProject(projectRef, options = {}) {
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found. Run `brainclaw init` first.');
     }
-    const resolved = resolveProjectRef(projectRef, cwd);
+    // pln#515 step 4 — resolution priority:
+    // 1. resolveProjectRef: workspace store-chain children (existing path)
+    // 2. resolveProjectCwd: cross_project_links (added so bclaw_switch can
+    //    target externally-linked projects, not just store-chain children).
+    // resolveProjectCwd returns the original cwd on no-match, so we check
+    // for a real change before treating it as a resolution.
+    let resolved = resolveProjectRef(projectRef, cwd);
+    if (!resolved) {
+        try {
+            const linkResolved = resolveProjectCwd(projectRef, cwd);
+            if (linkResolved !== cwd) {
+                resolved = linkResolved;
+            }
+        }
+        catch { /* link resolution failure surfaces as the same error below */ }
+    }
     if (!resolved) {
         throw new Error(`Cannot resolve project "${projectRef}". Use bclaw_switch with list=true to see available projects.`);
     }
@@ -244,6 +260,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/agentrun-reconciler.js

@@ -50,6 +50,8 @@ export const DEFAULT_HEALTH_CHECK_GRACE_MS = 60_000;
  * declared `failed` with `silent_termination_no_evidence`. Default 30 min.
  */
 export const DEFAULT_STALE_AFTER_MS = 30 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS = 5 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_LIMIT = 50;
 const TERMINAL_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
@@ -309,6 +311,69 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         evidence, previous_status, current_status: run.status,
     };
 }
+export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {}) {
+    const run = loadAgentRun(runId, cwd);
+    if (!run) {
+        const evidence = {
+            age_ms: 0, has_post_start_commit: false, claim_released: false,
+            assignment_completed: false, process_alive: undefined,
+        };
+        return {
+            run_id: runId, action: 'no_op', reason: 'run not found', evidence,
+            previous_status: 'created', current_status: 'created',
+        };
+    }
+    const evidence = collectEvidence(run, cwd, { nowMs: options.nowMs });
+    if (run.status !== 'running') {
+        return {
+            run_id: run.id, action: 'no_op', reason: `run status is ${run.status}, not running`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    if (evidence.process_alive !== false) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: evidence.process_alive === true ? 'process alive' : 'pid liveness unknown',
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    try {
+        transitionAgentRun(run.id, 'cancelled', {
+            actor: options.actor ?? 'reconciler',
+            status_reason: 'pid_dead_at_read',
+        }, cwd);
+        return {
+            run_id: run.id, action: 'cancelled_dead_pid', reason: 'pid_dead_at_read',
+            evidence, previous_status: run.status, current_status: 'cancelled',
+        };
+    }
+    catch (err) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: `cancel transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+}
+export function sweepDeadPidRunningAgentRunsAtRead(cwd, options = {}) {
+    const now = options.nowMs ?? Date.now();
+    const minAgeMs = options.staleAfterMs ?? DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS;
+    const cutoff = now - minAgeMs;
+    const limit = options.limit ?? DEFAULT_DEAD_PID_READ_SWEEP_LIMIT;
+    const candidates = listAgentRuns(cwd, { status: 'running' })
+        .filter((run) => {
+        const lastEventAt = run.last_event_at ?? run.started_at ?? run.created_at;
+        const ts = new Date(lastEventAt).getTime();
+        return Number.isFinite(ts) && ts <= cutoff;
+    })
+        .sort((left, right) => {
+        const leftTs = new Date(left.last_event_at ?? left.started_at ?? left.created_at).getTime();
+        const rightTs = new Date(right.last_event_at ?? right.started_at ?? right.created_at).getTime();
+        return rightTs - leftTs;
+    })
+        .slice(0, limit);
+    return candidates.map((run) => reconcileDeadPidRunningAgentRunAtRead(run.id, cwd, options));
+}
 /**
  * Reconcile every non-terminal agent_run matching `filter`. Useful for
  * batch sweeps from `bclaw_assignment_events` or `brainclaw doctor --dispatch`.

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/claims.js

@@ -59,6 +59,35 @@ export function saveClaim(claim, cwd) {
         catch { /* best-effort */ }
     });
 }
+/**
+ * Atomically check for an active claim on `scope` and save a new one if absent.
+ *
+ * Atomicity is provided by running both operations inside a single mutate() call;
+ * the mutation-pipeline mutex serializes filesystem writes on the claims store.
+ */
+export function acquireClaimScope(input, cwd) {
+    return mutate({ cwd }, () => {
+        const conflictingClaim = listClaims(cwd).find((claim) => claim.status === 'active' && claim.scope === input.scope);
+        if (conflictingClaim) {
+            return { acquired: false, conflicting_claim: conflictingClaim };
+        }
+        const claim = {
+            id: generateClaimId(),
+            agent: input.agent,
+            agent_id: input.agent_id,
+            user: input.user,
+            session_id: input.session_id,
+            scope: input.scope,
+            description: input.description,
+            created_at: nowISO(),
+            status: 'active',
+            plan_id: input.plan_id,
+            model: input.model,
+        };
+        saveClaim(claim, cwd);
+        return { acquired: true, claim };
+    });
+}
 export function loadClaim(id, cwd) {
     return claimStore(cwd).load(id);
 }

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/dispatch-status.js

@@ -0,0 +1,219 @@
+/**
+ * Consolidated dispatch status (pln#503 phase 3.1).
+ *
+ * Resolves a single dispatch reference (`asgn_…`, `clm_…`, `lop_…`, `run_…`)
+ * into the full set of linked entities — assignment, claim, loop, agent_run —
+ * plus on-disk artefacts (brief-ack sentinel, stdout/stderr logs) and a
+ * pid-liveness check, then computes a health verdict + a recommended next
+ * action for the caller.
+ *
+ * The motivating use case: an agent who just called `bclaw_coordinate` and
+ * got `execution_status: "delivered_and_started"` should be able to verify
+ * the dispatch is alive without running five separate `bclaw_find` calls.
+ * The `verify_with` hint added in phase 3.3 already points callers at this
+ * tool by name.
+ *
+ * See docs/concepts/dispatch-lifecycle.md for the full entity-relationship
+ * and FSM model.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadAssignment, listAssignments } from './assignments.js';
+import { loadAgentRun, listAgentRuns } from './agentruns.js';
+import { loadClaim } from './claims.js';
+import { getLoop, listLoops } from './loops/store.js';
+import { isProcessAlive } from './agentrun-reconciler.js';
+const DEFAULT_TAIL = 20;
+const DEFAULT_STALL_MS = 5 * 60_000;
+// ── Internal helpers ──────────────────────────────────────────────────────
+function readLogTail(filePath, lines) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (lines <= 0) {
+            return { path: filePath, exists: true, size_bytes: stat.size };
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const all = content.split(/\r?\n/);
+        // Strip trailing empty line from final \n
+        if (all.length > 0 && all[all.length - 1] === '')
+            all.pop();
+        return {
+            path: filePath,
+            exists: true,
+            size_bytes: stat.size,
+            tail: all.slice(-lines),
+        };
+    }
+    catch {
+        return { path: filePath, exists: false, size_bytes: 0 };
+    }
+}
+function findLoopByAssignmentId(assignmentId, cwd) {
+    for (const loop of listLoops({}, cwd)) {
+        if (loop.slots.some((s) => s.assignment_id === assignmentId))
+            return loop;
+    }
+    return undefined;
+}
+function resolveTarget(targetId, cwd) {
+    if (targetId.startsWith('asgn_')) {
+        return { resolved_from: 'assignment_id', assignment_id: targetId };
+    }
+    if (targetId.startsWith('run_')) {
+        const run = loadAgentRun(targetId, cwd);
+        if (run)
+            return { resolved_from: 'run_id', assignment_id: run.assignment_id, agent_run: run };
+        return { resolved_from: 'unresolved' };
+    }
+    if (targetId.startsWith('clm_')) {
+        const assignments = listAssignments(cwd, { claim_id: targetId });
+        if (assignments.length > 0) {
+            // Pick the most recent assignment for this claim (latest created_at).
+            const recent = [...assignments].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+            return { resolved_from: 'claim_id', assignment_id: recent.id };
+        }
+        return { resolved_from: 'claim_id' };
+    }
+    if (targetId.startsWith('lop_')) {
+        const loop = getLoop(targetId, cwd);
+        if (loop) {
+            // Prefer the slot in the current_phase with an assignment_id; fall back
+            // to any slot's assignment_id.
+            const phaseSlot = loop.slots.find((s) => s.phase === loop.current_phase && s.assignment_id);
+            const anySlot = loop.slots.find((s) => s.assignment_id);
+            const slot = phaseSlot ?? anySlot;
+            if (slot?.assignment_id) {
+                return { resolved_from: 'loop_id', assignment_id: slot.assignment_id };
+            }
+            return { resolved_from: 'loop_id' };
+        }
+        return { resolved_from: 'unresolved' };
+    }
+    return { resolved_from: 'unresolved' };
+}
+const TERMINAL_RUN_STATUSES = new Set([
+    'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
+]);
+function computeDiagnosis(assignment, agentRun, runtime, options) {
+    if (!assignment && !agentRun) {
+        return {
+            health: 'unknown',
+            summary: 'target_id did not resolve to any assignment or agent_run',
+            recommended_next_action: 'Verify the target_id is correct (asgn_/clm_/lop_/run_). Use bclaw_find(entity="assignment") to list available assignments.',
+        };
+    }
+    if (!agentRun) {
+        return {
+            health: 'not_dispatched',
+            summary: `assignment exists (status=${assignment?.status}) but no agent_run record — the spawn never produced a process, or the assignment is still waiting to be picked up`,
+            recommended_next_action: assignment?.status === 'offered'
+                ? 'Wait for the target agent to accept, or reroute via bclaw_coordinate(intent="reroute", scope=…).'
+                : 'Re-dispatch with bclaw_coordinate or check for an earlier spawn error.',
+        };
+    }
+    if (TERMINAL_RUN_STATUSES.has(agentRun.status)) {
+        const isSuccess = agentRun.status === 'completed';
+        return {
+            health: 'terminal',
+            summary: `agent_run already terminal (status=${agentRun.status})${agentRun.status_reason ? `: ${agentRun.status_reason}` : ''}`,
+            recommended_next_action: isSuccess
+                ? 'Harvest artifacts and move on; if the assignment is still open, transition it to completed.'
+                : 'Read stderr log (path in runtime.log_files.stderr) for the failure detail; reroute or retry if appropriate.',
+        };
+    }
+    // status is running / launching / waiting_input / blocked → check liveness
+    const lastEventMs = new Date(agentRun.last_event_at ?? agentRun.started_at ?? agentRun.created_at).getTime();
+    const stallAge = options.nowMs - lastEventMs;
+    if (runtime.pid_alive === false) {
+        return {
+            health: 'silent_death',
+            summary: `agent_run.status="${agentRun.status}" but pid ${runtime.pid} is dead — worker exited without self-reporting; lazy reconciler will mark it failed after the stale window (default 30min)`,
+            recommended_next_action: 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
+        };
+    }
+    if (runtime.pid_alive === true && stallAge > options.stallMs) {
+        return {
+            health: 'stalled',
+            summary: `agent_run alive (pid=${runtime.pid}) but no activity for ${Math.round(stallAge / 1000)}s; last_event_at=${agentRun.last_event_at ?? '(never)'}`,
+            recommended_next_action: 'Tail the stdout/stderr log to see whether the worker is doing useful work; if truly hung, kill the pid and reroute.',
+        };
+    }
+    if (runtime.pid_alive === true) {
+        return {
+            health: 'healthy',
+            summary: `agent_run.status="${agentRun.status}", pid ${runtime.pid} alive, last activity ${Math.round(stallAge / 1000)}s ago`,
+            recommended_next_action: 'No action — the dispatch is alive and recent. Re-check periodically until terminal.',
+        };
+    }
+    // pid_alive undefined → cannot determine (no pid tracked, or signal failed)
+    return {
+        health: 'unknown',
+        summary: `agent_run.status="${agentRun.status}" but pid liveness could not be determined (pid=${agentRun.pid ?? '(none)'})`,
+        recommended_next_action: 'Read the stdout/stderr log for life signs; or wait for the lazy reconciler to converge based on commit / claim / assignment evidence.',
+    };
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+export function getDispatchStatus(options) {
+    const cwd = options.cwd;
+    const tailLines = options.tail_log_lines ?? DEFAULT_TAIL;
+    const stallMs = options.stall_threshold_ms ?? DEFAULT_STALL_MS;
+    const nowMs = options.nowMs ?? Date.now();
+    const resolved = resolveTarget(options.target_id, cwd);
+    const assignmentId = resolved.assignment_id;
+    const assignment = assignmentId ? loadAssignment(assignmentId, cwd) : undefined;
+    const claim = assignment?.claim_id ? loadClaim(assignment.claim_id, cwd) : undefined;
+    // Prefer the pre-resolved agent_run (when target_id was a run_…); otherwise
+    // look up by assignment_id and pick the most recent attempt.
+    let agentRun = resolved.agent_run;
+    if (!agentRun && assignmentId) {
+        const runs = listAgentRuns(cwd, { assignment_id: assignmentId });
+        agentRun = [...runs].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+    }
+    let loop;
+    if (resolved.resolved_from === 'loop_id') {
+        loop = getLoop(options.target_id, cwd);
+    }
+    else if (assignmentId) {
+        loop = findLoopByAssignmentId(assignmentId, cwd);
+    }
+    // Runtime artefacts (ack file + log files) — all under the project's
+    // coordination root. Use the cwd or the runtime cwd as the anchor; the
+    // dispatcher writes them under cwd/.brainclaw/coordination/runtime/...
+    const projectRoot = cwd ?? process.cwd();
+    const runtimeRoot = path.join(projectRoot, '.brainclaw', 'coordination', 'runtime');
+    const ackPath = assignmentId ? path.join(runtimeRoot, 'ack', `${assignmentId}.ack`) : undefined;
+    const stdoutPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stdout.log`) : undefined;
+    const stderrPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stderr.log`) : undefined;
+    const runtime = {
+        pid: agentRun?.pid,
+        pid_alive: isProcessAlive(agentRun?.pid),
+        ack_file: {
+            exists: ackPath ? fs.existsSync(ackPath) : false,
+            path: ackPath,
+        },
+        log_files: {
+            stdout: stdoutPath ? readLogTail(stdoutPath, tailLines) : undefined,
+            stderr: stderrPath ? readLogTail(stderrPath, tailLines) : undefined,
+        },
+    };
+    const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    return {
+        target_id: options.target_id,
+        resolved_from: resolved.resolved_from,
+        entities: {
+            assignment_id: assignmentId,
+            claim_id: assignment?.claim_id,
+            loop_id: loop?.id,
+            run_id: agentRun?.id,
+        },
+        assignment,
+        claim,
+        loop,
+        agent_run: agentRun,
+        runtime,
+        diagnosis,
+    };
+}
+//# sourceMappingURL=dispatch-status.js.map