brainclaw 1.8.0 → 1.9.0

package/dist/commands/check-security.js

@@ -2,7 +2,9 @@ import { memoryExists, memoryPath } from '../core/io.js';
 import { loadConfig } from '../core/config.js';
 import { SecurityCache } from '../core/security-cache.js';
 import { querySocketScores } from '../core/socket-client.js';
-import { evaluateBatch, worstDecision } from '../core/security-scoring.js';
+import { applyMode, decisionExitCode, evaluateBatch, worstDecision, } from '../core/security-scoring.js';
+import { parsePackageSpec } from '../core/security-packages.js';
+import { collectPackages } from '../core/security-extract.js';
 export async function runCheckSecurity(options) {
     if (!memoryExists(options.cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
@@ -15,8 +17,22 @@ export async function runCheckSecurity(options) {
         process.exit(1);
     }
     const ecosystem = options.ecosystem ?? 'npm';
-    const packageNames = options.packages.split(',').map(p => p.trim()).filter(Boolean);
-    if (packageNames.length === 0) {
+    const effectiveMode = options.mode ?? preinstall.mode ?? 'advisory';
+    let packageSpecs;
+    try {
+        packageSpecs = collectPackages({
+            packages: options.packages,
+            requirements: options.requirements,
+            lockfile: options.lockfile,
+            defaultEcosystem: ecosystem,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+    if (packageSpecs.length === 0) {
         console.error('No packages specified.');
         process.exit(1);
     }
@@ -25,28 +41,23 @@ export async function runCheckSecurity(options) {
     const cache = new SecurityCache(cachePath, preinstall.cache_ttl_hours);
     // Separate cached vs uncached
     const queries = [];
-    const cachedResults = [];
-    for (const name of packageNames) {
-        const [depname, version] = name.includes('@') && !name.startsWith('@')
-            ? name.split('@')
-            : name.startsWith('@')
-                ? [name.slice(0, name.lastIndexOf('@')) || name, name.slice(name.lastIndexOf('@') + 1) || 'latest']
-                : [name, 'latest'];
+    const cachedScores = [];
+    for (const spec of packageSpecs) {
+        const { depname, version } = parsePackageSpec(spec);
         const cached = cache.get(ecosystem, depname, version);
-        const query = { depname, ecosystem, ...(version !== 'latest' ? { version } : {}) };
         if (cached) {
-            cachedResults.push({ query, scores: cached });
+            cachedScores.push(cached);
         }
         else {
-            queries.push(query);
+            queries.push({ depname, ecosystem, ...(version !== 'latest' ? { version } : {}) });
         }
     }
     // Fetch uncached from Socket
     let fetchedScores = [];
+    let fetchError = null;
     if (queries.length > 0) {
         try {
             fetchedScores = await querySocketScores(queries, { endpoint: preinstall.socket_endpoint });
-            // Update cache
             for (const s of fetchedScores) {
                 const eco = s.purl.startsWith('pkg:pypi') ? 'pypi' : 'npm';
                 const depname = s.purl.replace(/^pkg:\w+\//, '');
@@ -55,52 +66,84 @@ export async function runCheckSecurity(options) {
             cache.flush();
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (preinstall.fallback_on_error === 'block') {
-                console.error(`Socket MCP error: ${msg} — blocking (fallback=block)`);
-                process.exit(2);
-            }
-            if (preinstall.fallback_on_error === 'warn') {
-                console.error(`Socket MCP error: ${msg} — allowing with warning (fallback=warn)`);
-            }
-            // fallback=pass: silent continue
-            if (cachedResults.length === 0) {
-                process.exit(preinstall.fallback_on_error === 'warn' ? 1 : 0);
-            }
+            fetchError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    // Decide what to do on offline / fetch failure.
+    // fallback_on_error semantics:
+    //   block — abort regardless of mode (operator opted into strictness)
+    //   warn  — surface warning, continue with whatever cache we have
+    //   pass  — silent, continue with cache (or treat as pass if no data)
+    if (fetchError && cachedScores.length === 0) {
+        const fallback = preinstall.fallback_on_error;
+        if (options.json) {
+            console.log(JSON.stringify({
+                verdicts: [],
+                decision: fallbackDecision(fallback),
+                effective_decision: applyMode(fallbackDecision(fallback), effectiveMode),
+                mode: effectiveMode,
+                fetch_error: fetchError,
+            }, null, 2));
+        }
+        else {
+            console.error(`Socket MCP error: ${fetchError}`);
+            console.error(`Fallback policy: ${fallback} — no cached results to fall back to.`);
+        }
+        process.exit(decisionExitCode(applyMode(fallbackDecision(fallback), effectiveMode)));
+    }
+    if (fetchError) {
+        // Partial failure: we have some cache, surface a warning.
+        if (!options.json) {
+            console.error(`Warning: Socket MCP error: ${fetchError} (continuing with ${cachedScores.length} cached result(s))`);
         }
     }
-    // Combine cached + fetched scores
-    const allScores = [
-        ...cachedResults.filter(c => c.scores !== null).map(c => c.scores),
-        ...fetchedScores,
-    ];
+    const allScores = [...cachedScores, ...fetchedScores];
     const verdicts = evaluateBatch(allScores, preinstall);
-    const worst = worstDecision(verdicts);
+    const intrinsic = worstDecision(verdicts);
+    const effective = applyMode(intrinsic, effectiveMode);
     if (options.json) {
-        console.log(JSON.stringify({ verdicts, decision: worst }, null, 2));
+        console.log(JSON.stringify({
+            verdicts,
+            decision: intrinsic,
+            effective_decision: effective,
+            mode: effectiveMode,
+            ...(fetchError ? { fetch_error: fetchError } : {}),
+        }, null, 2));
     }
     else {
-        printVerdicts(verdicts);
+        printVerdicts(verdicts, intrinsic, effective, effectiveMode);
     }
-    // Exit codes: 0=pass, 1=warn, 2=block
-    if (worst === 'block')
-        process.exit(2);
-    if (worst === 'warn')
-        process.exit(1);
-    process.exit(0);
+    process.exit(decisionExitCode(effective));
+}
+function fallbackDecision(fallback) {
+    if (fallback === 'block')
+        return 'block';
+    if (fallback === 'warn')
+        return 'warn';
+    return 'pass';
 }
-function printVerdicts(verdicts) {
+function printVerdicts(verdicts, intrinsic, effective, mode) {
     if (verdicts.length === 0) {
         console.log('No packages to check.');
         return;
     }
     for (const v of verdicts) {
-        const icon = v.decision === 'pass' ? '\u2705' : v.decision === 'warn' ? '\u26A0\uFE0F' : '\uD83D\uDED1';
+        const icon = v.decision === 'pass' ? '✅' : v.decision === 'warn' ? '⚠️' : '🛑';
         console.log(`${icon} ${v.ecosystem}/${v.package}@${v.version} — composite=${v.composite} [${v.decision.toUpperCase()}]`);
         console.log(`   SC=${v.scores.supplyChain} vuln=${v.scores.vulnerability} qual=${v.scores.quality} maint=${v.scores.maintenance} lic=${v.scores.license}`);
         for (const r of v.reasons) {
-            console.log(`   \u2192 ${r}`);
+            console.log(`   → ${r}`);
         }
     }
+    // Surface the mode-aware outcome so operators see what would have happened.
+    if (intrinsic !== effective) {
+        console.log('');
+        console.log(`Verdict: ${intrinsic.toUpperCase()} — downgraded to ${effective.toUpperCase()} by mode=advisory.`);
+        console.log('   Switch to enforced mode (brainclaw setup-security --mode enforced) to block on this verdict.');
+    }
+    else if (verdicts.length > 0) {
+        console.log('');
+        console.log(`Verdict: ${intrinsic.toUpperCase()} (mode=${mode})`);
+    }
 }
 //# sourceMappingURL=check-security.js.map

package/dist/commands/claim.js

@@ -42,15 +42,6 @@ export function runClaim(description, options) {
         console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
         process.exit(1);
     }
-    // Check for overlapping active claims on the same scope
-    const existing = listClaims(options.cwd).filter(c => c.status === 'active' && c.scope === options.scope);
-    if (existing.length > 0) {
-        console.warn(`⚠ Active claim(s) already exist for scope "${options.scope}":`);
-        for (const c of existing) {
-            console.warn(`  [${c.id}] by ${c.agent}: ${c.description}`);
-        }
-        console.warn('  Proceeding anyway (advisory only).');
-    }
     const state = loadState(options.cwd);
     const plan = options.plan ? state.plan_items.find((item) => item.id === options.plan) : undefined;
     if (options.plan && !plan) {
@@ -74,20 +65,30 @@ export function runClaim(description, options) {
         expires_at: options.ttl ? parseTtl(options.ttl) : undefined,
         model: resolveCurrentModel(options.cwd),
     };
-    mutate({ cwd: options.cwd }, () => {
-        if (plan) {
-            if (!plan.assignee) {
-                plan.assignee = actor.agent;
+    try {
+        mutate({ cwd: options.cwd }, () => {
+            const existing = listClaims(options.cwd).find(c => c.status === 'active' && c.scope === options.scope);
+            if (existing) {
+                throw new Error(`Active claim already exists for scope "${options.scope}": [${existing.id}] by ${existing.agent}: ${existing.description}`);
             }
-            if (plan.status === 'todo') {
-                plan.status = 'in_progress';
+            if (plan) {
+                if (!plan.assignee) {
+                    plan.assignee = actor.agent;
+                }
+                if (plan.status === 'todo') {
+                    plan.status = 'in_progress';
+                }
+                plan.updated_at = nowISO();
+                saveState(state, options.cwd);
             }
-            plan.updated_at = nowISO();
-            saveState(state, options.cwd);
-        }
-        saveClaim(claim, options.cwd);
-        rebuildProjectMd(plan ? state : loadState(options.cwd), options.cwd);
-    });
+            saveClaim(claim, options.cwd);
+            rebuildProjectMd(plan ? state : loadState(options.cwd), options.cwd);
+        });
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
     const planInfo = claim.plan_id ? ` [plan ${claim.plan_id}]` : '';
     const ttlInfo = claim.expires_at ? ` (expires ${claim.expires_at.slice(0, 16).replace('T', ' ')})` : '';
     const storeLabel = options.store && options.store !== 'local' ? ` [store:${options.store}]` : '';

package/dist/commands/confirm.js

@@ -0,0 +1,26 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+export async function confirmAction(question, yes) {
+    if (yes)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`Error: ${question} Re-run with --yes in non-interactive mode.`);
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        if (answer.trim().toLowerCase() !== 'y') {
+            console.error('Cancelled.');
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=confirm.js.map

package/dist/commands/context-diff.js

@@ -20,7 +20,7 @@ export function runContextDiff(options = {}) {
             console.error(`Error: session '${options.session}' not found in session snapshots or audit log.`);
             process.exit(1);
         }
-        console.error('Error: provide --since <ISO date> or --session <id>, or run `brainclaw context` first to seed a marker.');
+        console.error('Error: provide --since <ISO date> or --session <id>. (The per-agent "what\'s new" diff is surfaced automatically by `brainclaw context` / bclaw_work.)');
         process.exit(1);
     }
     const diff = buildContextDiff({ ...options, includeItems: true });

package/dist/commands/dispatch-watch.js

@@ -0,0 +1,142 @@
+import { execFileSync } from 'node:child_process';
+import { getDispatchStatus } from '../core/dispatch-status.js';
+/** Filesystem activity younger than this vetoes a process-gone verdict. */
+export const FS_FRESH_MS = 5 * 60_000;
+/**
+ * Pure decision core — one watch poll in, one state out.
+ * Evidence priority (strongest first): worker-written results, then git
+ * evidence, then process evidence, then administrative status. This is the
+ * inverse of trusting `assignment.status`, which expired live workers three
+ * times on 2026-06-10 (can_948acfd6).
+ */
+export function evaluateWatchTick(input) {
+    if (input.laneResultStatus === 'failed')
+        return 'failed';
+    if (input.laneResultStatus !== undefined)
+        return 'lane-result';
+    if (input.runStatus === 'completed')
+        return 'completed';
+    if (input.runStatus === 'failed' || input.runStatus === 'timed_out')
+        return 'failed';
+    // Fresh filesystem activity / a live agent child = the worker is still at
+    // work. This vetoes committed-clean (incremental commits leave the tree
+    // momentarily clean BETWEEN steps — first-run false positive, stp_a1fe2b76)
+    // AND the process-gone verdicts below (stale tracked pid after a respawn).
+    const fsFresh = input.fsActivityMs !== undefined && input.fsActivityMs < FS_FRESH_MS;
+    const workerActive = input.agentChildAlive === true || fsFresh;
+    // Git evidence beats process evidence: a worker that committed everything
+    // and went QUIESCENT is DONE for the coordinator's purposes.
+    if (input.commitsAhead > 0 && input.dirtyTracked === 0 && !workerActive) {
+        return 'committed-clean';
+    }
+    // Wrapper alive but the real agent child is gone: abrupt death — the wrapper
+    // waits forever on inherited pipe handles and never emits a sentinel.
+    // agentChildAlive === undefined means "could not observe" — never conclude
+    // death from a failed observation.
+    if (input.agentChildAlive === false && !fsFresh)
+        return 'worker-process-gone';
+    // Wrapper itself dead with nothing delivered: same recovery path.
+    if (input.pidAlive === false && input.agentChildAlive !== true && !fsFresh) {
+        return 'worker-process-gone';
+    }
+    return 'running';
+}
+const AGENT_CHILD_NAMES = ['claude', 'codex', 'copilot', 'node'];
+/**
+ * Does a real agent process live under the wrapper pid?
+ * Returns undefined when the observation itself fails (never treated as death).
+ */
+export function probeAgentChildAlive(wrapperPid) {
+    if (!wrapperPid)
+        return undefined;
+    try {
+        if (process.platform === 'win32') {
+            const out = execFileSync('powershell', [
+                '-NoProfile', '-Command',
+                // Single quotes survive Windows argv re-parsing; double quotes do not.
+                `(Get-CimInstance Win32_Process -Filter 'ParentProcessId=${Math.floor(wrapperPid)}').Name`,
+            ], { encoding: 'utf-8', timeout: 15000 });
+            const names = out.split(/\r?\n/).map((l) => l.trim().toLowerCase()).filter(Boolean);
+            return names.some((n) => AGENT_CHILD_NAMES.some((a) => n.startsWith(a)));
+        }
+        const out = execFileSync('ps', ['-o', 'comm=', '--ppid', String(wrapperPid)], {
+            encoding: 'utf-8', timeout: 15000,
+        });
+        const names = out.split('\n').map((l) => l.trim().toLowerCase()).filter(Boolean);
+        return names.some((n) => AGENT_CHILD_NAMES.some((a) => n.includes(a)));
+    }
+    catch {
+        return undefined;
+    }
+}
+const EXIT_CODES = {
+    'running': 2, // only used when the timeout fires
+    'lane-result': 0,
+    'completed': 0,
+    'committed-clean': 0,
+    'failed': 3,
+    'worker-process-gone': 4,
+};
+const NEXT_ACTION = {
+    'running': 'Watch timeout — worker still running; re-run watch or inspect with dispatch-status.',
+    'lane-result': 'Run `brainclaw harvest <assignment_id> --integrate` to ingest and converge the lane.',
+    'completed': 'Run `brainclaw harvest <assignment_id> --integrate` (or merge the lane branch).',
+    'committed-clean': 'Work is on the branch; harvest/merge it. The worker stalled only on exit formalities.',
+    'failed': 'Read the captured stderr log, then fix and re-dispatch.',
+    'worker-process-gone': 'Triage the worktree (commits? dirty files?). Recover uncommitted work by evaluate+commit-on-behalf before any re-dispatch.',
+};
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function runDispatchWatch(targetId, options = {}) {
+    const intervalMs = Math.max(5, options.intervalSeconds ?? 60) * 1000;
+    const timeoutMs = Math.max(1, options.timeoutMinutes ?? 90) * 60_000;
+    const baseRef = options.base ?? 'master';
+    const startedAt = Date.now();
+    let poll = 0;
+    let lastState = 'running';
+    let lastStatus;
+    for (;;) {
+        poll += 1;
+        let status;
+        try {
+            status = getDispatchStatus({ target_id: targetId, cwd: options.cwd, tail_log_lines: 0, base_ref: baseRef });
+        }
+        catch (err) {
+            console.error(`Error: could not resolve '${targetId}': ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 5;
+            return;
+        }
+        lastStatus = status;
+        // Git evidence is computed by getDispatchStatus (shared helper, pln#554 step 2).
+        const commitsAhead = status.runtime.commits_ahead ?? 0;
+        const dirtyTracked = status.runtime.dirty_tracked ?? 0;
+        const state = evaluateWatchTick({
+            health: status.diagnosis.health,
+            runStatus: status.agent_run?.status,
+            laneResultStatus: status.runtime.lane_result?.status,
+            pidAlive: status.runtime.pid_alive,
+            agentChildAlive: probeAgentChildAlive(status.runtime.pid),
+            commitsAhead,
+            dirtyTracked,
+            fsActivityMs: status.runtime.last_fs_activity_ms,
+        });
+        lastState = state;
+        const line = options.json
+            ? JSON.stringify({ poll, state, commits_ahead: commitsAhead, dirty_tracked: dirtyTracked, health: status.diagnosis.health })
+            : `[poll ${poll}] ${state} (commits=${commitsAhead} dirty=${dirtyTracked} health=${status.diagnosis.health})`;
+        console.log(line);
+        if (state !== 'running')
+            break;
+        if (Date.now() - startedAt + intervalMs > timeoutMs)
+            break;
+        await sleep(intervalMs);
+    }
+    const assignmentId = lastStatus?.entities.assignment_id ?? targetId;
+    if (!options.json) {
+        console.log(lastState === 'running' ? 'TIMEOUT' : 'TERMINAL');
+        console.log(`→ ${NEXT_ACTION[lastState].replace('<assignment_id>', assignmentId)}`);
+    }
+    process.exitCode = EXIT_CODES[lastState];
+}
+//# sourceMappingURL=dispatch-watch.js.map

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@ import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
 import { runSpawnCheck, renderSpawnCheckReport } from '../core/spawn-check.js';
 import { loadAgentRun } from '../core/agentruns.js';
-import { listAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
+import { listAgentIdentities, listDebrisAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
 import { listCapabilities as listRegistryCapabilities, listTools as listRegistryTools } from '../core/registries.js';
 import { buildReputationSummary } from '../core/reputation.js';
 import { buildCircuitBreakerSnapshot } from '../core/circuit-breaker.js';
@@ -24,6 +24,8 @@ import { listRuntimeNotes } from '../core/runtime.js';
 import { isTrapExpired, listOperationalTraps } from '../core/traps.js';
 import { scanText } from '../core/security.js';
 import { isTaskLifecycleRuntimeEvent, listRuntimeEvents } from '../core/events.js';
+import { verifyProjectionsAgainstJournal, verifyRegistryAgainstJournal } from '../core/events/verify.js';
+import { resolveJournalMode } from '../core/events/journal.js';
 import { resolveEventSessionId } from '../core/identity.js';
 import { detectContradictions } from '../core/contradictions.js';
 import { loadVersionedJsonFile, scanMigrationStatus } from '../core/migration.js';
@@ -582,7 +584,64 @@ export async function runDoctorSpawnCheck(options = {}) {
     if (report.exit_code !== 0)
         process.exit(report.exit_code);
 }
+/**
+ * pln#565 — `brainclaw doctor --verify-journal`: the single-command Phase-2
+ * cutover gate. Rebuilds state from the journal and diffs it against the live
+ * projections; zero drift across real multi-agent traffic is the green light
+ * to flip `store.journal.mode` to primary (pln#543 step 5). Exit 1 on drift so
+ * CI can gate on it.
+ */
+function runJournalVerification(options) {
+    if (!memoryExists(options.cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const mode = resolveJournalMode(options.cwd);
+    const t0 = Date.now();
+    // pln#568 — the gate now covers BOTH the memory families and the registry /
+    // coordination families (claim/assignment/agent_run/candidate/sequence), so
+    // sustained zero drift authorizes trusting the journal for the observer's
+    // attention inputs too, not just memory.
+    const drift = [...verifyProjectionsAgainstJournal(options.cwd), ...verifyRegistryAgainstJournal(options.cwd)];
+    const elapsed_ms = Date.now() - t0;
+    if (options.json) {
+        console.log(JSON.stringify({
+            check: 'verify-journal',
+            journal_mode: mode,
+            drift_count: drift.length,
+            drift: drift.slice(0, 100),
+            elapsed_ms,
+            gate: drift.length === 0 ? 'green' : 'drift',
+        }, null, 2));
+    }
+    else if (mode === 'off') {
+        console.log('⚠ Journal mode is "off" — nothing to verify (no dual-write running). Set store.journal.mode=dual first.');
+    }
+    else if (drift.length === 0) {
+        console.log(`✔ Journal verification GREEN (mode=${mode}, replay ${elapsed_ms}ms): journal reproduces projections exactly — zero drift.`);
+        console.log('  → Phase-2 gate criterion met for this store snapshot. Sustained zero drift across multi-agent traffic authorizes the primary cutover (pln#543 step 5).');
+    }
+    else {
+        console.error(`✗ Journal verification found ${drift.length} drift entr${drift.length === 1 ? 'y' : 'ies'} (mode=${mode}):`);
+        const byKind = {};
+        for (const d of drift)
+            byKind[d.kind] = (byKind[d.kind] ?? 0) + 1;
+        for (const [kind, n] of Object.entries(byKind))
+            console.error(`    ${kind}: ${n}`);
+        for (const d of drift.slice(0, 20))
+            console.error(`    - ${d.kind}: ${d.item_type} ${d.item_id}`);
+        if (drift.length > 20)
+            console.error(`    … and ${drift.length - 20} more`);
+        console.error('  → Gate NOT met: the journal does not yet reproduce projections. Do NOT cut over.');
+    }
+    if (drift.length > 0)
+        process.exit(1);
+}
 export function runDoctor(options = {}) {
+    if (options.verifyJournal) {
+        runJournalVerification(options);
+        return;
+    }
     if (options.dispatch) {
         const report = runDispatchHealthCheck(options);
         if (options.json) {
@@ -945,6 +1004,26 @@ export function runDoctor(options = {}) {
         }
     }
     catch { /* non-fatal */ }
+    // pln#562 step 2 — surface debris identities (test fixtures, alias leftovers).
+    // Read-only: removal goes through the guarded `register-agent <name> --remove`.
+    try {
+        const debris = listDebrisAgentIdentities(options.cwd);
+        if (debris.length > 0) {
+            const names = debris.map((d) => d.identity.agent_name).join(', ');
+            checks.push({
+                name: 'debris_agent_identities',
+                status: 'warn',
+                message: `${debris.length} debris agent identit${debris.length === 1 ? 'y' : 'ies'} registered (${names}). Remove with \`brainclaw register-agent <name> --remove\`.`,
+            });
+            if (!options.json) {
+                console.warn(`⚠ Debris agent identities: ${names} — remove with \`brainclaw register-agent <name> --remove\`.`);
+                for (const d of debris) {
+                    console.warn(`    - ${d.identity.agent_name} (${d.identity.agent_id}): ${d.reason}`);
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
     const agentTooling = buildAgentToolingContext({ cwd: options.cwd });
     if (agentTooling.agents_md_present && agentTooling.agents_rules.length === 0) {
         checks.push({
@@ -1533,7 +1612,13 @@ export function runDoctor(options = {}) {
     try {
         const pendingCandidatesForStaleness = listCandidates('pending', options.cwd);
         const runtimeNotesForStaleness = listRuntimeNotes(undefined, options.cwd);
-        const staleReport = detectStaleness(state.plan_items, state.known_traps, state.open_handoffs, pendingCandidatesForStaleness, Date.now(), runtimeNotesForStaleness);
+        const staleReport = detectStaleness(state.plan_items, state.known_traps, state.open_handoffs, pendingCandidatesForStaleness, Date.now(), runtimeNotesForStaleness, 
+        // pln#557 step 2 — flag entities whose related_paths no longer exist.
+        {
+            decisions: state.recent_decisions,
+            constraints: state.active_constraints,
+            projectRoot: options.cwd ?? process.cwd(),
+        });
         if (staleReport.warnings.length > 0) {
             const summary = staleSummary(staleReport);
             checks.push({
@@ -1736,6 +1821,32 @@ export function runDoctor(options = {}) {
         console.log(`Runtime notes: ${notes.length} total`);
         console.log(`Local traps: ${localTraps.length} visible on this host`);
     }
+    // can_b8d53d18 — runtime notes created with the legacy `run_` prefix collide
+    // with agent_run ids in prefix-based routing (dispatch_status). Surface them
+    // and offer the soft id migration via `brainclaw repair`.
+    const legacyPrefixNotes = listRuntimeNotes({ visibility: 'all', includeAllHosts: true }, options.cwd)
+        .filter((n) => n.id.startsWith('run_'));
+    if (legacyPrefixNotes.length > 0) {
+        checks.push({
+            name: 'runtime_note_id_prefix',
+            status: 'warn',
+            message: `${legacyPrefixNotes.length} runtime note(s) carry the legacy run_ id prefix (collides with agent_run ids)`,
+            details: legacyPrefixNotes.map((n) => n.id),
+        });
+        repairCandidates.push({
+            action: 'migrate_runtime_note_ids',
+            target: 'coordination/runtime',
+            description: `Rename ${legacyPrefixNotes.length} runtime note id(s) from run_* to rtn_* (file rename + id rewrite, lossless)`,
+            safe: true,
+            related_check: 'runtime_note_id_prefix',
+        });
+        if (!options.json) {
+            console.warn(`⚠ ${legacyPrefixNotes.length} runtime note(s) use the legacy run_ id prefix — run \`brainclaw repair\` to migrate them to rtn_.`);
+        }
+    }
+    else {
+        checks.push({ name: 'runtime_note_id_prefix', status: 'ok', message: 'No runtime notes with legacy run_ id prefix' });
+    }
     const marker = readContextMarker(options.cwd);
     const visibleMemoryVersion = getVisibleMemoryVersion({ cwd: options.cwd });
     if (marker?.memory_version && marker.memory_version !== visibleMemoryVersion) {