brainclaw 0.28.0 → 1.5.3

package/dist/commands/doctor.js

@@ -1,3 +1,9 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as childProcess from 'node:child_process';
+import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
+import { loadAgentRun } from '../core/agentruns.js';
 import { listAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
 import { listCapabilities as listRegistryCapabilities, listTools as listRegistryTools } from '../core/registries.js';
 import { buildReputationSummary } from '../core/reputation.js';
@@ -9,39 +15,649 @@ import { getVisibleMemoryVersion, readContextMarker } from '../core/freshness.js
 import { generateMarkdown } from '../core/markdown.js';
 import { loadProjectIdentity, projectIdentityExists } from '../core/project-registry.js';
 import { findInstructionConflicts, loadInstructions } from '../core/instructions.js';
-import { memoryExists, memoryPath, readFileSync } from '../core/io.js';
+import { memoryExists, memoryPath, readFileSync, resolveEntityDir, memoryDir, REQUIRED_ENTITY_SUBDIRS } from '../core/io.js';
 import { logger } from '../core/logger.js';
-import { listCandidates, listArchivedCandidates } from '../core/candidates.js';
-import { listClaims } from '../core/claims.js';
+import { cleanupStaleCandidates, listCandidates, listArchivedCandidates } from '../core/candidates.js';
+import { listClaims, isClaimExpired, assessClaimLiveness } from '../core/claims.js';
 import { listRuntimeNotes } from '../core/runtime.js';
 import { isTrapExpired, listOperationalTraps } from '../core/traps.js';
 import { scanText } from '../core/security.js';
-import { listRuntimeEvents } from '../core/events.js';
+import { isTaskLifecycleRuntimeEvent, listRuntimeEvents } from '../core/events.js';
 import { resolveEventSessionId } from '../core/identity.js';
 import { detectContradictions } from '../core/contradictions.js';
-import { scanMigrationStatus } from '../core/migration.js';
+import { loadVersionedJsonFile, scanMigrationStatus } from '../core/migration.js';
 import { buildAgentToolingContext } from '../core/agent-context.js';
 import { assessAgentIntegrationReadiness } from '../core/agent-integrations.js';
-import { assessBrainclawVersion } from '../core/brainclaw-version.js';
+import { assessBrainclawVersion, detectConcurrentInstallations } from '../core/brainclaw-version.js';
 import { resolveStoreChain } from '../core/store-resolution.js';
+import { listWorktrees, detectSharedCheckoutRisk } from '../core/worktree.js';
 import { resolveCrossProjectLinks, detectCrossProjectCycles } from '../core/cross-project.js';
-import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries } from '../core/agent-files.js';
+import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries, patchAllMcpConfigs } from '../core/agent-files.js';
 import { summarizeWorkspaceProjects } from '../core/workspace-projects.js';
+import { detectStaleness, staleSummary } from '../core/staleness.js';
+import { InboxMessageSchema } from '../core/schema.js';
+import { resolvePrimaryStore } from '../core/store-resolution.js';
+import { runPostMigrationHealthCheck } from '../core/upgrades/health-check.js';
 const BACKLOG_KEYWORDS = /\b(TODO|NEXT|backlog|next[\s-]step|action[\s-]item|prochaine?s?\s+étapes?|à\s+faire)\b/i;
+const NON_MESSAGE_INBOX_SUBDIRS = new Set(['accepted', 'rejected', 'cross-project']);
+export const MCP_RUNTIME_REPAIR_COMMAND = 'brainclaw doctor --repair';
+export const MCP_WORKER_RELATIVE_PATH = 'dist/commands/mcp-worker.js';
+const DIST_CLI_RELATIVE_PATH = 'dist/cli.js';
+const DIST_BUILD_MANIFEST_RELATIVE_PATH = 'dist/.brainclaw-build.json';
+const ACTIONABLE_BACKLOG_LINE_PATTERNS = [
+    { name: 'unchecked_task', re: /^\s*(?:[-*•]\s*)?\[\s*\]\s+.+$/i },
+    { name: 'todo_line', re: /^\s*(?:[-*•]\s*)?TODO\b.*$/i },
+    { name: 'backlog_line', re: /^\s*(?:[-*•]\s*)?backlog:\s*.+$/i },
+    { name: 'next_steps_line', re: /^\s*(?:[-*•]\s*)?next steps:\s*.+$/i },
+    { name: 'should_do_line', re: /^\s*(?:[-*•]\s*)?should do\b.*$/i },
+    { name: 'needs_to_be_done_line', re: /^\s*(?:[-*•]\s*)?needs to be done\b.*$/i },
+];
+const FORMAL_PLAN_REFERENCE_RE = /\bpln_[a-z0-9]+\b/i;
 function hasBacklogPatterns(text) {
     const lines = text.split(/\r?\n/);
     const bulletOrNumbered = lines.some((l) => /^\s*[-*•]\s+\w/.test(l) || /^\s*\d+\.\s+\w/.test(l));
     return bulletOrNumbered || BACKLOG_KEYWORDS.test(text) || /\[[ x]\]/.test(text);
 }
+function truncateDoctorSnippet(text, maxLength = 140) {
+    const compact = text.replace(/\s+/g, ' ').trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+function hasFormalPlanLink(handoff) {
+    return Boolean(handoff.plan_id)
+        || FORMAL_PLAN_REFERENCE_RE.test(handoff.text)
+        || Boolean(handoff.contract?.linked_plans?.length);
+}
+export function extractBacklogWithoutPlanFindings(handoff) {
+    if (hasFormalPlanLink(handoff)) {
+        return [];
+    }
+    const findings = [];
+    for (const line of handoff.text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        for (const pattern of ACTIONABLE_BACKLOG_LINE_PATTERNS) {
+            if (!pattern.re.test(line)) {
+                continue;
+            }
+            findings.push({
+                handoff_id: handoff.id,
+                matched_pattern: pattern.name,
+                snippet: truncateDoctorSnippet(trimmed),
+                suggestion: 'Create a formal plan item with `brainclaw plan create "<text>"` and link the handoff to the resulting pln_xxx.',
+            });
+            break;
+        }
+    }
+    return findings;
+}
+function listJsonFilesRecursive(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        return [];
+    }
+    const files = [];
+    for (const entry of fs.readdirSync(dirPath).sort()) {
+        const fullPath = path.join(dirPath, entry);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            files.push(...listJsonFilesRecursive(fullPath));
+            continue;
+        }
+        if (entry.endsWith('.json')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function normalizeInboxAgentName(agent) {
+    return agent.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+}
+function toRelativeDoctorPath(filepath, cwd) {
+    return path.relative(cwd ?? process.cwd(), filepath).replace(/\\/g, '/');
+}
+function resolveDoctorPath(relativePath, cwd) {
+    return path.resolve(cwd ?? process.cwd(), ...relativePath.split('/'));
+}
+function listFilesForHash(rootPath, includeFile) {
+    if (!fs.existsSync(rootPath)) {
+        return [];
+    }
+    const files = [];
+    const walk = (currentPath) => {
+        const entries = fs.readdirSync(currentPath, { withFileTypes: true })
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const fullPath = path.join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            if (entry.isFile() && includeFile(fullPath)) {
+                files.push(fullPath);
+            }
+        }
+    };
+    walk(rootPath);
+    return files;
+}
+function hashFiles(rootPath, files) {
+    if (files.length === 0) {
+        return undefined;
+    }
+    const hash = crypto.createHash('sha256');
+    for (const file of files) {
+        hash.update(path.relative(rootPath, file).replace(/\\/g, '/'));
+        hash.update('\0');
+        hash.update(fs.readFileSync(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function computeSourceTreeHash(cwd) {
+    const effectiveCwd = cwd ?? process.cwd();
+    const rootFiles = [path.join(effectiveCwd, 'tsconfig.json'), path.join(effectiveCwd, 'package.json')]
+        .filter((filepath) => fs.existsSync(filepath));
+    const srcFiles = listFilesForHash(path.join(effectiveCwd, 'src'), (filepath) => filepath.endsWith('.ts'));
+    const scriptFiles = [path.join(effectiveCwd, 'scripts', 'copy-default-profiles.mjs')]
+        .filter((filepath) => fs.existsSync(filepath));
+    return hashFiles(effectiveCwd, [...rootFiles, ...srcFiles, ...scriptFiles]);
+}
+function getLatestMtimeMs(files) {
+    return files.reduce((latest, filepath) => {
+        try {
+            return Math.max(latest, fs.statSync(filepath).mtimeMs);
+        }
+        catch {
+            return latest;
+        }
+    }, 0);
+}
+function collectSourceTreeFiles(cwd) {
+    const effectiveCwd = cwd ?? process.cwd();
+    const rootFiles = [path.join(effectiveCwd, 'tsconfig.json'), path.join(effectiveCwd, 'package.json')]
+        .filter((filepath) => fs.existsSync(filepath));
+    const srcFiles = listFilesForHash(path.join(effectiveCwd, 'src'), (filepath) => filepath.endsWith('.ts'));
+    const scriptFiles = [path.join(effectiveCwd, 'scripts', 'copy-default-profiles.mjs')]
+        .filter((filepath) => fs.existsSync(filepath));
+    return [...rootFiles, ...srcFiles, ...scriptFiles];
+}
+function computeDistTreeHash(cwd) {
+    const distRoot = path.join(cwd ?? process.cwd(), 'dist');
+    const distFiles = listFilesForHash(distRoot, (filepath) => {
+        const rel = path.relative(distRoot, filepath).replace(/\\/g, '/');
+        return !rel.startsWith('.')
+            && (filepath.endsWith('.js') || filepath.endsWith('.d.ts') || filepath.endsWith('.yaml'));
+    });
+    return hashFiles(distRoot, distFiles);
+}
+function collectDistTreeFiles(cwd) {
+    const distRoot = path.join(cwd ?? process.cwd(), 'dist');
+    return listFilesForHash(distRoot, (filepath) => {
+        const rel = path.relative(distRoot, filepath).replace(/\\/g, '/');
+        return !rel.startsWith('.')
+            && (filepath.endsWith('.js') || filepath.endsWith('.d.ts') || filepath.endsWith('.yaml'));
+    });
+}
+function readDistBuildManifest(cwd) {
+    const manifestPath = resolveDoctorPath(DIST_BUILD_MANIFEST_RELATIVE_PATH, cwd);
+    if (!fs.existsSync(manifestPath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        if (parsed && parsed.schema_version === 1 && typeof parsed.src_hash === 'string' && typeof parsed.dist_hash === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // ignored — invalid manifest means stale runtime and will be rebuilt
+    }
+    return undefined;
+}
+function writeDistBuildManifest(cwd, srcHash, distHash) {
+    const manifestPath = resolveDoctorPath(DIST_BUILD_MANIFEST_RELATIVE_PATH, cwd);
+    fs.writeFileSync(manifestPath, JSON.stringify({
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        src_hash: srcHash,
+        dist_hash: distHash,
+    }, null, 2));
+}
+export function resolveMcpWorkerMissingPath(cwd) {
+    return resolveDoctorPath(MCP_WORKER_RELATIVE_PATH, cwd);
+}
+export function isBrainclawRepoCwd(cwd) {
+    // dist/ runtime checks resolve paths relative to cwd; that only makes sense
+    // when cwd is the brainclaw source/install root. For every other cwd (a
+    // user's project, a test workspace), dist/ does not and should not exist.
+    const effectiveCwd = cwd ?? process.cwd();
+    if (fs.existsSync(path.join(effectiveCwd, 'src', 'commands', 'mcp.ts'))) {
+        return true;
+    }
+    if (fs.existsSync(path.join(effectiveCwd, 'dist', 'commands', 'mcp.js'))) {
+        return true;
+    }
+    return false;
+}
+export function getMcpRuntimeHealth(cwd) {
+    const effectiveCwd = cwd ?? process.cwd();
+    const manifestPath = resolveDoctorPath(DIST_BUILD_MANIFEST_RELATIVE_PATH, effectiveCwd);
+    const cliPath = resolveDoctorPath(DIST_CLI_RELATIVE_PATH, effectiveCwd);
+    const workerPath = resolveMcpWorkerMissingPath(effectiveCwd);
+    const missingFiles = [cliPath, workerPath].filter((filepath) => !fs.existsSync(filepath));
+    const srcHash = computeSourceTreeHash(effectiveCwd);
+    const distHash = computeDistTreeHash(effectiveCwd);
+    const manifest = readDistBuildManifest(effectiveCwd);
+    const latestSourceMtime = getLatestMtimeMs(collectSourceTreeFiles(effectiveCwd));
+    const latestDistMtime = getLatestMtimeMs(collectDistTreeFiles(effectiveCwd));
+    if (missingFiles.length > 0 || !distHash) {
+        return {
+            ok: false,
+            status: 'missing',
+            message: `dist/ runtime is missing required artifacts. Run "${MCP_RUNTIME_REPAIR_COMMAND}" to rebuild dist/.`,
+            repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+            missing_path: missingFiles[0],
+            missing_files: missingFiles.map((filepath) => toRelativeDoctorPath(filepath, effectiveCwd)),
+            src_hash: srcHash,
+            dist_hash: distHash,
+            manifest_src_hash: manifest?.src_hash,
+            manifest_dist_hash: manifest?.dist_hash,
+            manifest_path: toRelativeDoctorPath(manifestPath, effectiveCwd),
+        };
+    }
+    if (!manifest) {
+        if (latestSourceMtime > latestDistMtime) {
+            return {
+                ok: false,
+                status: 'stale',
+                message: `dist/ appears older than src/. Run "${MCP_RUNTIME_REPAIR_COMMAND}" to rebuild dist/.`,
+                repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+                missing_files: [],
+                src_hash: srcHash,
+                dist_hash: distHash,
+                manifest_path: toRelativeDoctorPath(manifestPath, effectiveCwd),
+            };
+        }
+        return {
+            ok: true,
+            status: 'ok',
+            message: 'dist/ runtime is healthy (legacy build without hash manifest)',
+            repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+            missing_files: [],
+            src_hash: srcHash,
+            dist_hash: distHash,
+            manifest_path: toRelativeDoctorPath(manifestPath, effectiveCwd),
+        };
+    }
+    if (!srcHash || manifest.src_hash !== srcHash || manifest.dist_hash !== distHash) {
+        return {
+            ok: false,
+            status: 'stale',
+            message: `dist/ is stale relative to src/. Run "${MCP_RUNTIME_REPAIR_COMMAND}" to rebuild dist/.`,
+            repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+            missing_files: [],
+            src_hash: srcHash,
+            dist_hash: distHash,
+            manifest_src_hash: manifest.src_hash,
+            manifest_dist_hash: manifest.dist_hash,
+            manifest_path: toRelativeDoctorPath(manifestPath, effectiveCwd),
+        };
+    }
+    return {
+        ok: true,
+        status: 'ok',
+        message: 'dist/ runtime is healthy',
+        repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+        missing_files: [],
+        src_hash: srcHash,
+        dist_hash: distHash,
+        manifest_src_hash: manifest.src_hash,
+        manifest_dist_hash: manifest.dist_hash,
+        manifest_path: toRelativeDoctorPath(manifestPath, effectiveCwd),
+    };
+}
+function spawnRepairCommand(command, args, cwd, options) {
+    const result = childProcess.spawnSync(command, args, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: options.json ? 'pipe' : 'inherit',
+    });
+    return {
+        ok: result.status === 0,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+        status: result.status,
+        errorCode: result.error?.code,
+    };
+}
+function readLocalPackageVersion(cwd) {
+    const packageJsonPath = path.join(cwd, 'package.json');
+    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    return parsed.version ?? 'unknown';
+}
+function repairDistRuntime(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const before = getMcpRuntimeHealth(cwd);
+    if (before.ok) {
+        const manifestPath = resolveDoctorPath(DIST_BUILD_MANIFEST_RELATIVE_PATH, cwd);
+        if (!fs.existsSync(manifestPath)) {
+            const srcHash = computeSourceTreeHash(cwd);
+            const distHash = computeDistTreeHash(cwd);
+            if (srcHash && distHash) {
+                writeDistBuildManifest(cwd, srcHash, distHash);
+            }
+        }
+        const versionResult = spawnRepairCommand(process.execPath, [DIST_CLI_RELATIVE_PATH, '--version'], cwd, { json: true });
+        if (!versionResult.ok && versionResult.errorCode !== 'EPERM') {
+            throw new Error(versionResult.stderr.trim() || versionResult.stdout.trim() || 'dist/cli.js --version failed');
+        }
+        const cliVersion = versionResult.ok ? versionResult.stdout.trim() : readLocalPackageVersion(cwd);
+        return {
+            ok: true,
+            repaired: false,
+            reason: 'ok',
+            repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+            missing_path: before.missing_path,
+            missing_files: before.missing_files,
+            manifest_path: before.manifest_path,
+            cli_version: cliVersion,
+        };
+    }
+    const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    const tscResult = spawnRepairCommand(npxCommand, ['tsc'], cwd, options);
+    if (!tscResult.ok) {
+        throw new Error(tscResult.stderr.trim() || tscResult.stdout.trim() || 'npx tsc failed');
+    }
+    const copyProfilesResult = spawnRepairCommand(process.execPath, ['scripts/copy-default-profiles.mjs'], cwd, options);
+    if (!copyProfilesResult.ok) {
+        throw new Error(copyProfilesResult.stderr.trim() || copyProfilesResult.stdout.trim() || 'copy-default-profiles.mjs failed');
+    }
+    const versionResult = spawnRepairCommand(process.execPath, [DIST_CLI_RELATIVE_PATH, '--version'], cwd, { json: true });
+    if (!versionResult.ok && versionResult.errorCode !== 'EPERM') {
+        throw new Error(versionResult.stderr.trim() || versionResult.stdout.trim() || 'dist/cli.js --version failed');
+    }
+    const cliVersion = versionResult.ok ? versionResult.stdout.trim() : readLocalPackageVersion(cwd);
+    const srcHash = computeSourceTreeHash(cwd);
+    const distHash = computeDistTreeHash(cwd);
+    if (!srcHash || !distHash) {
+        throw new Error('Rebuild completed but runtime hash could not be computed');
+    }
+    writeDistBuildManifest(cwd, srcHash, distHash);
+    const after = getMcpRuntimeHealth(cwd);
+    if (!after.ok) {
+        throw new Error(after.message);
+    }
+    return {
+        ok: true,
+        repaired: true,
+        reason: before.status,
+        repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+        missing_path: before.missing_path,
+        missing_files: before.missing_files,
+        manifest_path: after.manifest_path,
+        cli_version: cliVersion,
+    };
+}
+/**
+ * Return the absolute paths of entity subdirectories that should exist under
+ * `.brainclaw/` but don't. Source of truth is REQUIRED_ENTITY_SUBDIRS in
+ * core/io.ts (pln#397 stp_b5337e30).
+ */
+function scanMissingEntitySubdirs(cwd) {
+    const root = memoryDir(cwd);
+    if (!fs.existsSync(root))
+        return [];
+    const missing = [];
+    for (const subdir of REQUIRED_ENTITY_SUBDIRS) {
+        const full = path.join(root, subdir);
+        if (!fs.existsSync(full))
+            missing.push(full);
+    }
+    return missing;
+}
+function auditInboxMessages(cwd) {
+    const effectiveCwd = cwd ?? process.cwd();
+    const inboxRoot = resolveEntityDir('inbox', effectiveCwd, 'read');
+    const result = {
+        checked: 0,
+        invalid: [],
+        orphaned: [],
+    };
+    if (!fs.existsSync(inboxRoot)) {
+        return result;
+    }
+    for (const entry of fs.readdirSync(inboxRoot).sort()) {
+        const fullPath = path.join(inboxRoot, entry);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isFile() && entry.endsWith('.json')) {
+            try {
+                loadVersionedJsonFile('message', fullPath);
+                result.orphaned.push({
+                    path: toRelativeDoctorPath(fullPath, effectiveCwd),
+                    reason: 'message file is stored at inbox root instead of an agent subdirectory',
+                });
+            }
+            catch {
+                // Pending candidate files also live at inbox root; ignore non-message documents here.
+            }
+            continue;
+        }
+        if (!stat.isDirectory() || NON_MESSAGE_INBOX_SUBDIRS.has(entry)) {
+            continue;
+        }
+        for (const filepath of listJsonFilesRecursive(fullPath)) {
+            try {
+                const parsed = loadVersionedJsonFile('message', filepath);
+                const message = InboxMessageSchema.parse(parsed.document);
+                result.checked += 1;
+                const expectedDir = normalizeInboxAgentName(message.to);
+                if (expectedDir !== entry) {
+                    result.orphaned.push({
+                        path: toRelativeDoctorPath(filepath, effectiveCwd),
+                        reason: `message targets '${message.to}' but is stored under '${entry}'`,
+                    });
+                }
+            }
+            catch (error) {
+                result.invalid.push({
+                    path: toRelativeDoctorPath(filepath, effectiveCwd),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    return result;
+}
+export function runDispatchHealthCheck(options = {}) {
+    const results = reconcileAllOpenRuns(options.cwd);
+    const inferred_completed = [];
+    const health_check_unverified = [];
+    const inferred_failed = [];
+    let no_op_open = 0;
+    for (const result of results) {
+        const run = loadAgentRun(result.run_id, options.cwd);
+        if (!run) {
+            // Run was deleted between list and load — skip.
+            continue;
+        }
+        const summary = {
+            run_id: result.run_id,
+            agent: run.agent,
+            assignment_id: run.assignment_id,
+            claim_id: run.claim_id,
+            scope: run.scope,
+            age_ms: result.evidence.age_ms,
+            reason: result.reason,
+            previous_status: result.previous_status,
+            current_status: result.current_status,
+        };
+        switch (result.action) {
+            case 'inferred_completed':
+                inferred_completed.push(summary);
+                break;
+            case 'health_check_unverified':
+                health_check_unverified.push(summary);
+                break;
+            case 'inferred_failed':
+                inferred_failed.push(summary);
+                break;
+            case 'no_op':
+                no_op_open += 1;
+                break;
+        }
+    }
+    return {
+        generated_at: new Date().toISOString(),
+        total: results.length,
+        inferred_completed,
+        health_check_unverified,
+        inferred_failed,
+        no_op_open,
+        exit_code: inferred_failed.length > 0 ? 1 : 0,
+    };
+}
+function renderDispatchHealthHumanReport(report) {
+    const lines = [];
+    lines.push(`Dispatch health — ${report.total} open agent_run(s) examined at ${report.generated_at}`);
+    lines.push('');
+    if (report.inferred_failed.length > 0) {
+        lines.push(`✗ ${report.inferred_failed.length} silent failure(s) — process dead, no completion evidence:`);
+        for (const r of report.inferred_failed) {
+            lines.push(`  - ${r.run_id} ${r.agent} (${r.scope}) — ${r.reason}`);
+        }
+        lines.push('');
+    }
+    if (report.inferred_completed.length > 0) {
+        lines.push(`⟳ ${report.inferred_completed.length} silent completion(s) recovered (run transitioned ${report.inferred_completed[0]?.previous_status ?? '?'} → completed):`);
+        for (const r of report.inferred_completed) {
+            lines.push(`  - ${r.run_id} ${r.agent} (${r.scope}) — ${r.reason}`);
+        }
+        lines.push('');
+    }
+    if (report.health_check_unverified.length > 0) {
+        lines.push(`⏳ ${report.health_check_unverified.length} unverified spawn(s) past grace window (no life-sign yet):`);
+        for (const r of report.health_check_unverified) {
+            lines.push(`  - ${r.run_id} ${r.agent} (${r.scope}) — age=${Math.round(r.age_ms / 1000)}s — ${r.reason}`);
+        }
+        lines.push('');
+    }
+    if (report.inferred_failed.length === 0 && report.inferred_completed.length === 0 && report.health_check_unverified.length === 0) {
+        lines.push(`✔ No dispatch issues detected (${report.no_op_open} open run(s) within grace window or already healthy).`);
+    }
+    else {
+        lines.push(`(${report.no_op_open} other open run(s) within grace window or already healthy.)`);
+    }
+    return lines.join('\n');
+}
 export function runDoctor(options = {}) {
+    if (options.dispatch) {
+        const report = runDispatchHealthCheck(options);
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(renderDispatchHealthHumanReport(report));
+        }
+        if (report.exit_code !== 0)
+            process.exit(report.exit_code);
+        return;
+    }
+    if (options.repair) {
+        try {
+            const result = repairDistRuntime(options);
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else if (result.repaired) {
+                console.log(`✔ Rebuilt dist/ (${result.reason})`);
+                console.log(`✔ Verified runtime: ${result.cli_version ?? 'unknown version'}`);
+                console.log(`✔ Updated hash manifest: ${result.manifest_path}`);
+            }
+            else {
+                console.log(`✔ dist/ runtime already healthy (${result.cli_version ?? 'unknown version'})`);
+            }
+            return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    repaired: false,
+                    repair_command: MCP_RUNTIME_REPAIR_COMMAND,
+                    error: message,
+                }, null, 2));
+            }
+            else {
+                console.error(`✗ Repair failed: ${message}`);
+            }
+            process.exit(1);
+        }
+    }
     if (!memoryExists(options.cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
+    if (options.afterMigration) {
+        runAfterMigrationCheck(options);
+        return;
+    }
     let hasIssues = false;
     const checks = [];
+    const repairCandidates = [];
     let migrationEntries = [];
     let agentGitHygieneFixed = [];
+    // pln#397 stp_b5337e30: scan entity-aligned subdirectories and emit safe
+    // mkdir repair candidates for any that are missing. Runs before other
+    // checks so downstream validators don't emit cascading "not found" noise.
+    const missingDirs = scanMissingEntitySubdirs(options.cwd);
+    if (missingDirs.length > 0) {
+        const rel = missingDirs.map((p) => toRelativeDoctorPath(p, options.cwd));
+        checks.push({
+            name: 'entity_subdirs',
+            status: 'warn',
+            message: `${missingDirs.length} required subdirectorie(s) missing from .brainclaw/`,
+            details: { missing: rel },
+        });
+        for (const dir of missingDirs) {
+            repairCandidates.push({
+                action: 'mkdir',
+                target: toRelativeDoctorPath(dir, options.cwd),
+                description: `Create missing entity subdirectory ${toRelativeDoctorPath(dir, options.cwd)}`,
+                safe: true,
+                related_check: 'entity_subdirs',
+            });
+        }
+        hasIssues = true;
+        if (!options.json) {
+            console.warn(`⚠ ${missingDirs.length} required subdirectorie(s) missing under .brainclaw/:`);
+            for (const p of rel) {
+                console.warn(`  - ${p}`);
+            }
+        }
+    }
+    else {
+        checks.push({ name: 'entity_subdirs', status: 'ok', message: 'all entity subdirectories present' });
+        if (!options.json) {
+            console.log('✔ all entity subdirectories present');
+        }
+    }
     // Validate config
     let config;
     try {
@@ -71,6 +687,37 @@ export function runDoctor(options = {}) {
             }
         }
     }
+    if (isBrainclawRepoCwd(options.cwd)) {
+        const mcpRuntimeHealth = getMcpRuntimeHealth(options.cwd);
+        if (mcpRuntimeHealth.ok) {
+            checks.push({
+                name: 'mcp_runtime',
+                status: 'ok',
+                message: mcpRuntimeHealth.message,
+                details: mcpRuntimeHealth,
+            });
+            if (!options.json) {
+                console.log('✔ MCP runtime: dist/ is healthy');
+            }
+        }
+        else {
+            checks.push({
+                name: 'mcp_runtime',
+                status: mcpRuntimeHealth.status === 'missing' ? 'error' : 'warn',
+                message: mcpRuntimeHealth.message,
+                details: mcpRuntimeHealth,
+            });
+            if (!options.json) {
+                const glyph = mcpRuntimeHealth.status === 'missing' ? '✗' : '⚠';
+                console.warn(`${glyph} MCP runtime: ${mcpRuntimeHealth.message}`);
+                if (mcpRuntimeHealth.missing_path) {
+                    console.warn(`  Missing path: ${toRelativeDoctorPath(mcpRuntimeHealth.missing_path, options.cwd)}`);
+                }
+                console.warn(`  Repair: ${mcpRuntimeHealth.repair_command}`);
+            }
+            hasIssues = true;
+        }
+    }
     // Validate state
     let state;
     try {
@@ -232,48 +879,29 @@ export function runDoctor(options = {}) {
     }
     try {
         const registeredAgents = listAgentIdentities(options.cwd);
-        if (config.current_agent || config.current_agent_id) {
-            const currentAgent = resolveCurrentAgentIdentity(options.cwd);
-            if (!currentAgent) {
-                checks.push({
-                    name: 'agent_identity',
-                    status: 'warn',
-                    message: `Current agent is configured (${config.current_agent ?? 'unknown'} / ${config.current_agent_id ?? 'unknown'}) but no matching registry entry was found.`,
-                });
-                if (!options.json) {
-                    console.warn(`⚠ Current agent is configured (${config.current_agent ?? 'unknown'} / ${config.current_agent_id ?? 'unknown'}) but no matching registry entry was found.`);
-                }
-                hasIssues = true;
-            }
-            else if ((config.current_agent && config.current_agent !== currentAgent.agent_name)
-                || (config.current_agent_id && config.current_agent_id !== currentAgent.agent_id)) {
-                checks.push({
-                    name: 'agent_identity',
-                    status: 'warn',
-                    message: `Current agent config does not match registry entry (${currentAgent.agent_name} / ${currentAgent.agent_id}).`,
-                });
-                if (!options.json) {
-                    console.warn(`⚠ Current agent config does not match registry entry (${currentAgent.agent_name} / ${currentAgent.agent_id}).`);
-                }
-                hasIssues = true;
-            }
-            else {
-                checks.push({
-                    name: 'agent_identity',
-                    status: 'ok',
-                    message: `current_agent=${currentAgent.agent_name}, agent_id=${currentAgent.agent_id}, registered_agents=${registeredAgents.length}`,
-                });
-                if (!options.json) {
-                    console.log(`✔ current agent: ${currentAgent.agent_name} (${currentAgent.agent_id})`);
-                }
+        // Agent identity check: verify the detected agent is registered (env vars + detectAiAgent).
+        // config.current_agent is NOT checked — it's a legacy singleton, not an identity source.
+        const detectedAgent = resolveCurrentAgentIdentity(options.cwd);
+        if (detectedAgent) {
+            checks.push({
+                name: 'agent_identity',
+                status: 'ok',
+                message: `detected_agent=${detectedAgent.agent_name}, agent_id=${detectedAgent.agent_id}, registered_agents=${registeredAgents.length}`,
+            });
+            if (!options.json) {
+                console.log(`✔ detected agent: ${detectedAgent.agent_name} (${detectedAgent.agent_id})`);
             }
         }
         else {
             checks.push({
                 name: 'agent_identity',
-                status: 'ok',
-                message: `No current agent configured (${registeredAgents.length} registered agent(s))`,
+                status: 'warn',
+                message: `No agent detected from environment (${registeredAgents.length} registered agent(s)). Set BRAINCLAW_AGENT or run from an agent terminal.`,
             });
+            if (!options.json) {
+                console.warn(`⚠ No agent detected from environment (${registeredAgents.length} registered). Set BRAINCLAW_AGENT or run from an agent terminal.`);
+            }
+            hasIssues = true;
         }
     }
     catch (e) {
@@ -361,15 +989,41 @@ export function runDoctor(options = {}) {
     }
     const integrationReadiness = assessAgentIntegrationReadiness(config, options.cwd ?? process.cwd());
     const missingIntegrations = integrationReadiness.filter((entry) => !entry.ready);
+    if (options.fix && missingIntegrations.some(m => m.missing_surfaces.some(s => s.kind === 'mcp') || m.drifting_surfaces.length > 0)) {
+        const results = patchAllMcpConfigs(options.cwd ?? process.cwd());
+        // Re-evaluate readiness
+        const refreshedReadiness = assessAgentIntegrationReadiness(config, options.cwd ?? process.cwd());
+        const fixedAgents = missingIntegrations.filter(initial => {
+            const current = refreshedReadiness.find(r => r.agent_name === initial.agent_name);
+            return current?.ready;
+        }).map(r => r.agent_name);
+        if (!options.json) {
+            console.log(`\n✔ Applied --fix: Patched ${results.length} MCP config(s) automatically.`);
+            if (fixedAgents.length > 0) {
+                console.log(`✔ Successfully restored: ${fixedAgents.join(', ')}`);
+            }
+        }
+        missingIntegrations.length = 0;
+        missingIntegrations.push(...refreshedReadiness.filter((entry) => !entry.ready));
+    }
     if (missingIntegrations.length > 0) {
         checks.push({
             name: 'agent_integrations',
             status: 'warn',
-            message: `${missingIntegrations.length} declared agent integration(s) are not fully activated on this machine/workspace.`,
+            message: `${missingIntegrations.length} declared agent integration(s) are not fully activated or are drifting.`,
             details: missingIntegrations,
         });
         if (!options.json) {
-            console.warn(`⚠ ${missingIntegrations.length} declared agent integration(s) are not fully activated on this machine/workspace.`);
+            console.warn(`⚠ ${missingIntegrations.length} declared agent integration(s) are not fully activated or are drifting.`);
+            for (const m of missingIntegrations) {
+                console.warn(`  - ${m.agent_name} -> Effective Tier: ${m.effective_tier}`);
+                for (const drift of m.drifting_surfaces) {
+                    console.warn(`    ↳ Drift: ${drift.drift_message}`);
+                }
+                for (const g of m.self_healing_guidance) {
+                    console.warn(`    ↳ ${g}`);
+                }
+            }
         }
         hasIssues = true;
     }
@@ -379,6 +1033,11 @@ export function runDoctor(options = {}) {
             status: 'ok',
             message: `${integrationReadiness.length} declared agent integration(s) are fully activated`,
         });
+        if (!options.json) {
+            for (const r of integrationReadiness) {
+                console.info(`✓ ${r.agent_name} is active -> Effective Tier: ${r.effective_tier}`);
+            }
+        }
     }
     const agentGitHygiene = auditLocalAgentWorkspaceFiles(options.cwd ?? process.cwd());
     if (!agentGitHygiene.isGitRepo) {
@@ -483,6 +1142,40 @@ export function runDoctor(options = {}) {
             console.log(`✔ ${brainclawVersion.message}`);
         }
     }
+    // Check for concurrent brainclaw installations in PATH
+    try {
+        const installations = detectConcurrentInstallations();
+        const uniqueVersions = new Set(installations.map(i => i.version));
+        if (installations.length > 1 && uniqueVersions.size > 1) {
+            const details = installations.map(i => `${i.path} (${i.version}${i.isCurrent ? ', active' : ''})`).join(', ');
+            checks.push({
+                name: 'brainclaw_path_conflicts',
+                status: 'warn',
+                message: `Multiple brainclaw versions in PATH: ${details}. The first in PATH will be used by CLI; MCP uses absolute path.`,
+                details: { installations },
+            });
+            if (!options.json) {
+                console.warn(`⚠ Multiple brainclaw versions in PATH:`);
+                for (const inst of installations) {
+                    console.warn(`  ${inst.isCurrent ? '→' : ' '} ${inst.path} (${inst.version})`);
+                }
+            }
+            hasIssues = true;
+        }
+        else {
+            checks.push({
+                name: 'brainclaw_path_conflicts',
+                status: 'ok',
+                message: installations.length > 0
+                    ? `Single brainclaw in PATH: ${installations[0].path} (${installations[0].version})`
+                    : 'No brainclaw found in PATH (using direct invocation)',
+            });
+        }
+    }
+    catch {
+        // Non-fatal — PATH scan failure should not block doctor
+        checks.push({ name: 'brainclaw_path_conflicts', status: 'ok', message: 'PATH scan skipped' });
+    }
     // Check project.md consistency
     try {
         const currentMd = readFileSync(memoryPath('project.md', options.cwd));
@@ -602,7 +1295,7 @@ export function runDoctor(options = {}) {
         });
     }
     // --- Reflective memory checks ---
-    const pending = listCandidates('pending', options.cwd);
+    let pending = listCandidates('pending', options.cwd);
     const accepted = listArchivedCandidates('accepted', options.cwd);
     const rejected = listArchivedCandidates('rejected', options.cwd);
     if (!options.json) {
@@ -624,8 +1317,8 @@ export function runDoctor(options = {}) {
     const promotionStarsThreshold = config.reflective_memory?.promotion_stars_threshold ?? 3;
     const promotionUsesThreshold = config.reflective_memory?.promotion_uses_threshold ?? 2;
     const reviewSlaHours = config.governance?.review_sla_hours ?? 24;
-    const promotionReady = pending.filter((c) => (c.star_count ?? 0) >= promotionStarsThreshold || (c.usage_count ?? 0) >= promotionUsesThreshold);
-    const pendingOverdue = pending.filter((c) => {
+    let promotionReady = pending.filter((c) => (c.star_count ?? 0) >= promotionStarsThreshold || (c.usage_count ?? 0) >= promotionUsesThreshold);
+    let pendingOverdue = pending.filter((c) => {
         const ageHours = Math.floor((Date.now() - Date.parse(c.created_at)) / (1000 * 60 * 60));
         return ageHours > reviewSlaHours;
     });
@@ -643,6 +1336,57 @@ export function runDoctor(options = {}) {
         console.log(`Governance review KPI: pending_overdue=${pendingOverdue.length}, avg_review_hours=${avgReviewHours.toFixed(1)}, review_sla_hours=${reviewSlaHours}`);
         console.log(`Promotion signal: ${promotionReady.length} candidate(s) reached ${promotionStarsThreshold} star(s) or ${promotionUsesThreshold} use(s)`);
     }
+    const staleAutoCandidates = cleanupStaleCandidates({
+        cwd: options.cwd,
+        source: 'auto',
+        maxAgeDays: 30,
+        dryRun: !options.fix,
+    });
+    if (staleAutoCandidates.matched > 0) {
+        const actionMessage = options.fix
+            ? `Removed ${staleAutoCandidates.deleted} stale auto-generated candidate(s) older than 30 days.`
+            : `${staleAutoCandidates.matched} stale auto-generated candidate(s) older than 30 days. Run \`brainclaw cleanup-candidates --max-age 30\` or \`brainclaw doctor --fix\`.`;
+        checks.push({
+            name: 'stale_auto_candidates',
+            status: options.fix ? 'ok' : 'warn',
+            message: actionMessage,
+            details: staleAutoCandidates.candidates.map((candidate) => ({
+                id: candidate.id,
+                type: candidate.type,
+                created_at: candidate.created_at,
+                text: truncateDoctorSnippet(candidate.text),
+            })),
+        });
+        if (!options.json) {
+            if (options.fix) {
+                console.log(`✔ ${actionMessage}`);
+            }
+            else {
+                console.warn(`⚠ ${actionMessage}`);
+            }
+        }
+        if (!options.fix) {
+            hasIssues = true;
+        }
+    }
+    else {
+        checks.push({
+            name: 'stale_auto_candidates',
+            status: 'ok',
+            message: 'No stale auto-generated candidates found',
+        });
+        if (!options.json) {
+            console.log('✔ No stale auto-generated candidates found');
+        }
+    }
+    if (options.fix && staleAutoCandidates.deleted > 0) {
+        pending = listCandidates('pending', options.cwd);
+        promotionReady = pending.filter((c) => (c.star_count ?? 0) >= promotionStarsThreshold || (c.usage_count ?? 0) >= promotionUsesThreshold);
+        pendingOverdue = pending.filter((c) => {
+            const ageHours = Math.floor((Date.now() - Date.parse(c.created_at)) / (1000 * 60 * 60));
+            return ageHours > reviewSlaHours;
+        });
+    }
     if (promotionReady.length > 0) {
         checks.push({
             name: 'promotion_signals',
@@ -768,6 +1512,105 @@ export function runDoctor(options = {}) {
     else {
         checks.push({ name: 'expired_items', status: 'ok', message: 'No expired items found' });
     }
+    // --- Stale memory check: age-based heuristics for plans, handoffs, candidates, runtime_notes ---
+    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);
+        if (staleReport.warnings.length > 0) {
+            const summary = staleSummary(staleReport);
+            checks.push({
+                name: 'stale_memory',
+                status: 'warn',
+                message: `${staleReport.warnings.length} stale item(s) detected: ${summary}`,
+                details: staleReport.warnings.map((w) => ({
+                    id: w.id,
+                    entity: w.entity,
+                    age_days: w.age_days,
+                    reason: w.reason,
+                    suggested_action: w.suggested_action,
+                })),
+            });
+            if (!options.json) {
+                console.warn(`⚠ Stale memory: ${summary}`);
+                for (const w of staleReport.warnings.slice(0, 5)) {
+                    console.warn(`  [${w.entity}] ${w.text} — ${w.reason}`);
+                    console.warn(`  → ${w.suggested_action}`);
+                }
+                if (staleReport.warnings.length > 5) {
+                    console.warn(`  … and ${staleReport.warnings.length - 5} more. Run \`brainclaw doctor --json\` for the full list.`);
+                }
+            }
+            hasIssues = true;
+        }
+        else {
+            checks.push({ name: 'stale_memory', status: 'ok', message: 'No stale items detected' });
+            if (!options.json) {
+                console.log('✔ No stale items detected');
+            }
+        }
+    }
+    catch { /* non-fatal — staleness check should not block doctor */ }
+    // --- Inbox message layout checks ---
+    const inboxAudit = auditInboxMessages(options.cwd);
+    const inboxIssueCount = inboxAudit.invalid.length + inboxAudit.orphaned.length;
+    if (inboxIssueCount > 0) {
+        const status = inboxAudit.invalid.length > 0 ? 'error' : 'warn';
+        checks.push({
+            name: 'inbox_messages',
+            status,
+            message: `${inboxIssueCount} inbox message issue(s): ${inboxAudit.invalid.length} invalid, ${inboxAudit.orphaned.length} orphaned.`,
+            details: {
+                checked: inboxAudit.checked,
+                invalid: inboxAudit.invalid.slice(0, 10),
+                orphaned: inboxAudit.orphaned.slice(0, 10),
+            },
+        });
+        // pln#397 stp_b5337e30: orphaned messages (wrong-dir placement) can be
+        // moved safely. Invalid JSON requires manual inspection — surface as
+        // unsafe so the repair flow prompts.
+        for (const orphaned of inboxAudit.orphaned) {
+            repairCandidates.push({
+                action: 'move_inbox_message',
+                target: orphaned.path,
+                description: `Move orphaned inbox message to the correct agent subdirectory (${orphaned.reason})`,
+                safe: true,
+                related_check: 'inbox_messages',
+            });
+        }
+        for (const invalid of inboxAudit.invalid) {
+            repairCandidates.push({
+                action: 'quarantine_inbox_message',
+                target: invalid.path,
+                description: `Move malformed inbox message to inbox/.quarantine for later inspection (${invalid.error})`,
+                safe: false,
+                related_check: 'inbox_messages',
+            });
+        }
+        if (!options.json) {
+            console.warn(`⚠ Inbox messages: ${inboxAudit.invalid.length} invalid, ${inboxAudit.orphaned.length} orphaned.`);
+            for (const invalid of inboxAudit.invalid.slice(0, 10)) {
+                console.warn(`  - invalid: ${invalid.path} (${invalid.error})`);
+            }
+            for (const orphaned of inboxAudit.orphaned.slice(0, 10)) {
+                console.warn(`  - orphaned: ${orphaned.path} (${orphaned.reason})`);
+            }
+        }
+        hasIssues = true;
+    }
+    else {
+        checks.push({
+            name: 'inbox_messages',
+            status: 'ok',
+            message: inboxAudit.checked > 0
+                ? `Inbox messages look valid (${inboxAudit.checked} agent message file(s) checked)`
+                : 'No inbox message files to check',
+            details: { checked: inboxAudit.checked },
+        });
+        if (!options.json && inboxAudit.checked > 0) {
+            console.log(`✔ Inbox messages: ${inboxAudit.checked} agent message file(s) checked`);
+        }
+    }
     // --- Claims checks ---
     const claims = listClaims(options.cwd);
     const activeClaims = claims.filter(c => c.status === 'active');
@@ -816,6 +1659,59 @@ export function runDoctor(options = {}) {
     else {
         checks.push({ name: 'claim_plan_link', status: 'ok', message: 'No active claims to check' });
     }
+    // Stale claims check — session-aware: a claim with a live session is never considered stale
+    const staleThresholdHours = config?.claims?.auto_release_after_hours ?? 24;
+    const livenessById = new Map(activeClaims.map(c => [c.id, assessClaimLiveness(c, { thresholdHours: staleThresholdHours, cwd: options.cwd })]));
+    const staleClaims = activeClaims.filter(c => {
+        const s = livenessById.get(c.id).status;
+        return s === 'stale' || s === 'never-adopted';
+    });
+    const orphanedClaims = activeClaims.filter(c => livenessById.get(c.id).status === 'orphaned');
+    if (staleClaims.length > 0) {
+        hasIssues = true;
+        const details = staleClaims.map(c => `${c.agent} → ${c.scope}`).join(', ');
+        checks.push({ name: 'claims_stale', status: 'warn', message: `${staleClaims.length} stale claim(s) (no live session, >${staleThresholdHours}h): ${details}` });
+        if (!options.json)
+            console.warn(`⚠ ${staleClaims.length} stale claim(s) (no live session, >${staleThresholdHours}h): ${details}`);
+    }
+    else {
+        checks.push({ name: 'claims_stale', status: 'ok', message: `No stale claims (threshold: ${staleThresholdHours}h)` });
+    }
+    if (orphanedClaims.length > 0) {
+        hasIssues = true;
+        const details = orphanedClaims.map(c => `${c.agent} → ${c.scope}`).join(', ');
+        checks.push({ name: 'claims_orphaned', status: 'warn', message: `${orphanedClaims.length} orphaned claim(s) (session crashed): ${details}. Run 'brainclaw prune' or 'brainclaw claim release' to clean up.` });
+        if (!options.json)
+            console.warn(`⚠ ${orphanedClaims.length} orphaned claim(s) — session was adopted but died (crash recovery): ${details}`);
+    }
+    else if (activeClaims.some(c => c.adopted_at)) {
+        checks.push({ name: 'claims_orphaned', status: 'ok', message: 'No orphaned claims' });
+    }
+    // Expired-but-still-active claims (TTL passed but prune not run)
+    const expiredActive = activeClaims.filter((c) => isClaimExpired(c));
+    if (expiredActive.length > 0) {
+        hasIssues = true;
+        const ids = expiredActive.map((c) => c.id).join(', ');
+        checks.push({
+            name: 'claim_ttl_expired',
+            status: 'warn',
+            message: `${expiredActive.length} active claim(s) past their TTL: ${ids}. Run 'brainclaw prune' to release them automatically.`,
+        });
+        if (!options.json) {
+            console.warn(`⚠ ${expiredActive.length} active claim(s) have expired (TTL passed — run 'brainclaw prune')`);
+            for (const c of expiredActive) {
+                console.warn(`  - [${c.id}] ${c.scope}: expires_at ${c.expires_at}`);
+            }
+        }
+    }
+    else if (activeClaims.some((c) => c.expires_at)) {
+        checks.push({ name: 'claim_ttl_expired', status: 'ok', message: 'All TTL-bounded claims are within their expiry window' });
+        if (!options.json)
+            console.log('✔ Claim TTLs: all within bounds');
+    }
+    else {
+        checks.push({ name: 'claim_ttl_expired', status: 'ok', message: 'No TTL-bounded claims' });
+    }
     // --- Runtime notes checks ---
     const notes = listRuntimeNotes(undefined, options.cwd);
     const localTraps = listOperationalTraps({}, options.cwd);
@@ -850,7 +1746,7 @@ export function runDoctor(options = {}) {
     const events = listRuntimeEvents(options.cwd);
     if (events.length > 0) {
         const sessions = new Map();
-        for (const event of events) {
+        for (const event of events.filter(isTaskLifecycleRuntimeEvent)) {
             const sessionValue = resolveEventSessionId(event);
             if (!sessionValue)
                 continue;
@@ -893,6 +1789,8 @@ export function runDoctor(options = {}) {
         active_plan_items: activePlans.length,
         blocked_plan_items: blockedPlans.length,
         promotion_ready_candidates: promotionReady.length,
+        stale_auto_candidates: staleAutoCandidates.matched,
+        stale_auto_candidates_deleted: staleAutoCandidates.deleted,
         pending_candidates: pending.length,
         accepted_candidates: accepted.length,
         rejected_candidates: rejected.length,
@@ -1037,6 +1935,33 @@ export function runDoctor(options = {}) {
     // --- Backlog patterns in open handoffs ---
     try {
         const openHandoffs = state.open_handoffs.filter((h) => h.status === 'open');
+        const backlogWithoutPlans = openHandoffs.flatMap((handoff) => extractBacklogWithoutPlanFindings(handoff));
+        if (backlogWithoutPlans.length > 0) {
+            const ids = [...new Set(backlogWithoutPlans.map((finding) => finding.handoff_id))].join(', ');
+            checks.push({
+                name: 'backlog_without_plans',
+                status: 'warn',
+                message: `${backlogWithoutPlans.length} actionable backlog item(s) in open handoff(s) lack a formal plan: ${ids}. Create a pln_xxx plan and link it.`,
+                details: backlogWithoutPlans,
+            });
+            if (!options.json) {
+                console.warn(`⚠ ${backlogWithoutPlans.length} actionable backlog item(s) in open handoff(s) lack a formal plan: ${ids}`);
+                for (const finding of backlogWithoutPlans.slice(0, 10)) {
+                    console.warn(`  - [${finding.handoff_id}] ${finding.snippet}`);
+                    console.warn(`    ${finding.suggestion}`);
+                }
+            }
+            hasIssues = true;
+        }
+        else {
+            checks.push({
+                name: 'backlog_without_plans',
+                status: 'ok',
+                message: openHandoffs.length > 0
+                    ? `${openHandoffs.length} open handoff(s) checked — no actionable backlog without plans detected`
+                    : 'No open handoffs to check',
+            });
+        }
         const handoffsWithBacklog = openHandoffs.filter((h) => !h.plan_id && hasBacklogPatterns(h.text));
         if (handoffsWithBacklog.length > 0) {
             const ids = handoffsWithBacklog.map((h) => h.id).join(', ');
@@ -1303,10 +2228,132 @@ export function runDoctor(options = {}) {
         catch { /* non-fatal */ }
     }
     catch { /* non-fatal */ }
+    // Worktree stale-session and shared-checkout checks
+    try {
+        const activeClaims = listClaims(options.cwd);
+        const worktrees = listWorktrees(options.cwd ?? process.cwd());
+        const claimWorktrees = new Set(activeClaims.filter((c) => c.worktree_path && c.status === 'active').map((c) => c.worktree_path));
+        const orphanWorktrees = worktrees.filter((wt) => !wt.is_main && wt.session_id && !claimWorktrees.has(wt.path));
+        if (orphanWorktrees.length > 0) {
+            hasIssues = true;
+            checks.push({
+                name: 'worktree_orphans',
+                status: 'warn',
+                message: `${orphanWorktrees.length} worktree(s) have no active claim: ${orphanWorktrees.map((w) => w.path).join(', ')}. Run 'brainclaw worktree prune' or remove them.`,
+            });
+            if (!options.json) {
+                console.warn(`⚠ ${orphanWorktrees.length} orphan worktree(s) with no active claim`);
+                for (const wt of orphanWorktrees) {
+                    console.warn(`  - ${wt.path} (branch: ${wt.branch}, session: ${wt.session_id ?? 'unknown'})`);
+                }
+            }
+        }
+        else {
+            checks.push({ name: 'worktree_orphans', status: 'ok', message: 'No orphan worktrees detected' });
+            if (!options.json)
+                console.log('✔ Worktrees: no orphans');
+        }
+        // Shared-checkout risk: multiple brainclaw sessions in the same working tree
+        const risk = detectSharedCheckoutRisk(options.cwd ?? process.cwd());
+        if (risk.has_conflict) {
+            hasIssues = true;
+            checks.push({
+                name: 'worktree_shared_checkout',
+                status: 'warn',
+                message: `Shared-checkout risk: ${risk.conflicting_paths.length} worktree(s) have multiple active sessions. Each session should use a dedicated worktree.`,
+            });
+            if (!options.json) {
+                console.warn('⚠ Shared-checkout risk detected — multiple sessions share a worktree');
+                for (const p of risk.conflicting_paths) {
+                    console.warn(`  - ${p}`);
+                }
+            }
+        }
+        else {
+            checks.push({ name: 'worktree_shared_checkout', status: 'ok', message: 'No shared-checkout conflicts' });
+            if (!options.json)
+                console.log('✔ Worktrees: no shared-checkout conflicts');
+        }
+    }
+    catch { /* non-fatal — git may not be available or no worktrees */ }
+    // --- Documentation drift check ---
+    try {
+        const { execSync } = childProcess;
+        const effectiveCwd = options.cwd ?? process.cwd();
+        const srcCommitDate = execSync('git log -1 --format=%aI -- src/commands src/core', { encoding: 'utf-8', cwd: effectiveCwd }).trim();
+        const docsCommitDate = execSync('git log -1 --format=%aI -- docs/', { encoding: 'utf-8', cwd: effectiveCwd }).trim();
+        if (srcCommitDate && docsCommitDate && srcCommitDate > docsCommitDate) {
+            checks.push({ name: 'doc_drift', status: 'warn', message: `Documentation may be outdated: src/ last changed ${srcCommitDate.slice(0, 10)}, docs/ last changed ${docsCommitDate.slice(0, 10)}` });
+            if (!options.json) {
+                console.warn(`⚠ Documentation drift: src/ updated ${srcCommitDate.slice(0, 10)} but docs/ last updated ${docsCommitDate.slice(0, 10)}`);
+            }
+        }
+        else if (srcCommitDate && !docsCommitDate) {
+            checks.push({ name: 'doc_drift', status: 'warn', message: 'No docs/ directory found in git history' });
+            if (!options.json) {
+                console.warn('⚠ No docs/ directory found in git history');
+            }
+        }
+        else {
+            checks.push({ name: 'doc_drift', status: 'ok', message: 'Documentation is up to date with source' });
+            if (!options.json)
+                console.log('✔ Documentation is up to date with source');
+        }
+    }
+    catch { /* non-fatal — git may not be available */ }
+    // --- Security preinstall gate check ---
+    if (config.security?.preinstall?.enabled) {
+        checks.push({ name: 'security_preinstall', status: 'ok', message: `Security preinstall gate is enabled (mode: ${config.security.preinstall.mode})` });
+        if (!options.json)
+            console.log(`✔ Security preinstall gate is enabled (mode: ${config.security.preinstall.mode})`);
+        // Check if guard scripts exist
+        try {
+            const guardDir = path.join(memoryPath('security/bin', options.cwd), '.');
+            const guardExists = fs.existsSync(path.dirname(guardDir));
+            if (guardExists) {
+                checks.push({ name: 'security_guard_scripts', status: 'ok', message: 'Guard wrapper scripts are generated' });
+                if (!options.json)
+                    console.log('✔ Guard wrapper scripts are generated');
+            }
+            else {
+                checks.push({ name: 'security_guard_scripts', status: 'warn', message: 'Guard wrapper scripts not found — run brainclaw setup-security' });
+                if (!options.json)
+                    console.warn('⚠ Guard wrapper scripts not found — run brainclaw setup-security');
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    else {
+        checks.push({ name: 'security_preinstall', status: 'ok', message: 'Security preinstall gate is not enabled (optional)' });
+        if (!options.json)
+            console.log('ℹ Security preinstall gate is not enabled (optional — run brainclaw setup-security to activate)');
+    }
+    // VS Code extension check
+    try {
+        const codeResult = childProcess.spawnSync('code', ['--list-extensions'], { stdio: 'pipe', timeout: 5000 });
+        if (codeResult.status === 0) {
+            const extensions = codeResult.stdout.toString().split('\n').map(e => e.trim().toLowerCase());
+            if (extensions.includes('brainclaw.brainclaw-vscode')) {
+                checks.push({ name: 'vscode_extension', status: 'ok', message: 'Brainclaw VS Code extension is installed' });
+                if (!options.json)
+                    console.log('✔ Brainclaw VS Code extension is installed');
+            }
+            else {
+                checks.push({ name: 'vscode_extension', status: 'warn', message: 'VS Code detected but Brainclaw extension is not installed. Run `brainclaw setup` to install it.' });
+                if (!options.json)
+                    console.log('⚠ VS Code detected but Brainclaw extension is not installed. Run `brainclaw setup` to install it.');
+            }
+        }
+        // If `code` is not available, skip silently — VS Code not installed
+    }
+    catch {
+        // Non-fatal
+    }
     if (options.json) {
         console.log(JSON.stringify({
             ok: !hasIssues,
             checks,
+            repair_candidates: repairCandidates,
             metrics: {
                 ...metrics,
                 migration_outdated_documents: migrationEntries.filter((entry) => entry.status === 'outdated').length,
@@ -1319,6 +2366,8 @@ export function runDoctor(options = {}) {
                 circuit_breaker_threshold: circuitSnapshot.threshold,
                 circuit_breaker_window_days: circuitSnapshot.window_days,
                 agent_git_hygiene_fixed: agentGitHygieneFixed.length,
+                repair_candidates_safe: repairCandidates.filter((c) => c.safe).length,
+                repair_candidates_unsafe: repairCandidates.filter((c) => !c.safe).length,
             },
             migration: options.migrationCheck
                 ? {
@@ -1335,4 +2384,28 @@ export function runDoctor(options = {}) {
         console.log('All checks passed.');
     }
 }
+function runAfterMigrationCheck(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const store = resolvePrimaryStore(cwd);
+    if (!store) {
+        console.error(`Error: no .brainclaw/ store resolved from ${cwd}`);
+        process.exit(1);
+    }
+    const report = runPostMigrationHealthCheck({ storePath: store.storePath });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(`Post-migration health check on ${report.store_path}`);
+        for (const finding of report.findings) {
+            const glyph = finding.status === 'ok' ? '✔' : finding.status === 'warn' ? '⚠' : '✗';
+            console.log(`  ${glyph} [${finding.check}] ${finding.message}`);
+        }
+        console.log('');
+        console.log(report.ok ? '✔ All post-migration invariants hold.' : '✗ Post-migration invariants failed. Inspect the findings above.');
+    }
+    if (!report.ok) {
+        process.exit(1);
+    }
+}
 //# sourceMappingURL=doctor.js.map