harborloop 0.3.0 → 0.4.1

package/dist/commands/doctor.js

@@ -1,937 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { ApiError, fetchLoopMetrics } from '../api.js';
-import { decodeJwtClaims, isPendingWorkspace, jwtExpiry, readAuth, } from '../auth/store.js';
-import { daemonVerdict, readDaemonHeartbeat } from '../daemon/state.js';
-import { inspectRepoDocuments, inState } from '../documents/inspect.js';
-import { DOCS_DIR } from '../documents/manifest.js';
-import { inspectEnvSkillRoots, inspectRepoSkillRoots, skillsInState, } from '../skills.js';
-import { isLocalEndpoint } from '../endpoints.js';
-import { refreshCliRelease } from '../cli-release.js';
-import { hookScriptsAreCurrent } from '../install-hooks.js';
-import { gitRoot, repoOrigin } from '../origin.js';
-import { hooksBinDir, legacyDirs, recallOutcomesFile } from '../paths.js';
-import * as claude from '../providers/claude.js';
-import * as codex from '../providers/codex.js';
-import * as cursor from '../providers/cursor.js';
-import { detectAgents } from '../providers/detect.js';
-import { AGENT_LABEL, REPO_SKILL_DIR } from '../providers/surfaces.js';
-import { CODEX_CAPABILITY_BY_EVENT, CURSOR_CAPABILITY_BY_EVENT, describePartialHooks, } from '../providers/hook-coverage.js';
-import { ratio, relativeTime } from '../render.js';
-import { measureReportBudget } from '../sync-report.js';
-import { readSyncedConfig, resolveArms } from '../state.js';
-export async function runDoctor(opts) {
-    const checks = [];
-    checks.push({
-        label: 'Endpoint',
-        state: 'ok',
-        detail: isLocalEndpoint(opts.endpoints)
-            ? `${opts.endpoints.apiUrl} (local)`
-            : opts.endpoints.apiUrl,
-    });
-    await appendMcpTargetCheck(checks, opts.cwd, opts.home ?? homedir(), opts.endpoints);
-    const auth = await readAuth();
-    if (!auth) {
-        checks.push({
-            label: 'Signed in',
-            state: 'fail',
-            detail: 'no credential on this machine',
-            fix: 'harbor init',
-        });
-    }
-    else if (auth.apiUrl !== opts.endpoints.apiUrl) {
-        checks.push({
-            label: 'Signed in',
-            state: 'fail',
-            detail: `credential is for ${auth.apiUrl}, not ${opts.endpoints.apiUrl}`,
-            fix: 'harbor init',
-        });
-    }
-    else if (isPendingWorkspace(auth)) {
-        checks.push({
-            label: 'Signed in',
-            state: 'fail',
-            detail: 'signed in, but no workspace chosen yet',
-            fix: 'harbor login',
-        });
-    }
-    else {
-        const expiry = jwtExpiry(auth.runnerToken);
-        const expired = expiry !== null && expiry.getTime() <= Date.now();
-        checks.push({
-            label: 'Signed in',
-            state: expired ? 'fail' : 'ok',
-            detail: expired
-                ? `workspace "${auth.workspaceName}" — browser sign-in expired ${relativeTime(expiry)}`
-                : `workspace "${auth.workspaceName}"`,
-            ...(expired ? { fix: 'harbor login' } : {}),
-        });
-    }
-    const [settings, claudeMcpConfig, present, codexConfig, codexHooksJson, cursorMcpJson, cursorHooksJson] = await Promise.all([
-        claude.readClaudeSettings(),
-        claude.readClaudeMcpConfig(),
-        detectAgents(),
-        codex.readCodexConfig(),
-        codex.readCodexHooksJson(),
-        cursor.readCursorMcpJson(),
-        cursor.readCursorHooksJson(),
-    ]);
-    const installedToken = claude.readInstalledToken(claudeMcpConfig) ??
-        codex.readInstalledToken(codexConfig) ??
-        cursor.readInstalledToken(cursorMcpJson);
-    if (!installedToken) {
-        const searched = [
-            '~/.claude.json',
-            ...(present.codex ? ['~/.codex/config.toml'] : []),
-            ...(present.cursor ? ['~/.cursor/mcp.json'] : []),
-        ];
-        checks.push({
-            label: 'Token',
-            state: 'fail',
-            detail: `no MCP bearer in ${searched.join(' or ')}`,
-            fix: 'harbor init',
-        });
-    }
-    else {
-        const expiry = jwtExpiry(installedToken);
-        const claims = decodeJwtClaims(installedToken);
-        const wrongWorkspace = auth !== null &&
-            typeof claims?.workspaceId === 'string' &&
-            claims.workspaceId !== auth.workspaceId;
-        if (expiry !== null && expiry.getTime() <= Date.now()) {
-            checks.push({
-                label: 'Token',
-                state: 'fail',
-                detail: `expired ${relativeTime(expiry)}`,
-                fix: 'the next prompt re-mints it; run `harbor init` if this persists',
-            });
-        }
-        else if (wrongWorkspace) {
-            checks.push({
-                label: 'Token',
-                state: 'fail',
-                detail: 'installed bearer is scoped to a different workspace',
-                fix: 'harbor init',
-            });
-        }
-        else {
-            checks.push({
-                label: 'Token',
-                state: 'ok',
-                detail: expiry ? `valid, expires ${relativeTime(expiry)}` : 'valid',
-            });
-        }
-    }
-    const agentChecks = [];
-    const hooks = claude.readInstalledHooks(settings);
-    const missingClaudeEvents = claude.MANAGED_HOOK_EVENTS.filter((event) => !hooks.events.includes(event));
-    const claudeWired = claude.readInstalledToken(claudeMcpConfig) !== null || hooks.installed;
-    if (!present.claude && !claudeWired) {
-    }
-    else if (!hooks.installed) {
-        agentChecks.push(claudeHooksMissing());
-    }
-    else {
-        const stale = hooks.commands.filter((c) => !c.startsWith(hooksBinDir()));
-        const current = await hookScriptsAreCurrent();
-        if (stale.length > 0) {
-            const dir = stale[0].replace(/\/[^/]+$/, '');
-            agentChecks.push(staleHooksCheck(dir));
-        }
-        else if (!current) {
-            agentChecks.push({
-                label: 'Hooks',
-                state: 'warn',
-                detail: 'installed scripts are older than this CLI',
-                fix: 'harbor init',
-            });
-        }
-        else if (missingClaudeEvents.length > 0) {
-            agentChecks.push({
-                label: 'Hooks',
-                state: 'warn',
-                detail: describePartialHooks(hooks.events.length, claude.MANAGED_HOOK_EVENTS.length, missingClaudeEvents),
-                fix: 'harbor init  (registers the events that are missing)',
-            });
-        }
-        else {
-            agentChecks.push({
-                label: 'Hooks',
-                state: 'ok',
-                detail: `${hooks.commands.length} installed from ${hooksBinDir()}`,
-            });
-        }
-    }
-    appendCodexChecks(agentChecks, present, codexConfig, codexHooksJson);
-    appendCursorChecks(agentChecks, present, cursorMcpJson, cursorHooksJson);
-    if (agentChecks.length === 0)
-        agentChecks.push(claudeHooksMissing());
-    checks.push(...agentChecks);
-    const config = await readSyncedConfig();
-    const origin = repoOrigin(opts.cwd);
-    const bound = origin !== '' && Boolean(config?.origins.includes(origin));
-    if (origin === '') {
-        checks.push({
-            label: 'This repo',
-            state: 'warn',
-            detail: 'not a git repo with an origin — sessions here get no scope',
-        });
-    }
-    else if (!bound) {
-        checks.push({
-            label: 'This repo',
-            state: 'fail',
-            detail: `${origin} is not in the local allowlist`,
-            fix: 'harbor bind',
-        });
-    }
-    else {
-        checks.push({ label: 'This repo', state: 'ok', detail: origin });
-    }
-    if (bound)
-        await appendDocumentChecks(checks, opts.cwd);
-    await appendSkillChecks(checks, opts.cwd, present, opts.home);
-    await appendDaemonCheck(checks);
-    await appendPayloadCheck(checks, opts.home);
-    const arms = config ? resolveArms(config.pause, origin) : null;
-    if (arms && !arms.recall) {
-        checks.push({
-            label: 'Recording',
-            state: 'paused',
-            detail: 'paused, on purpose — no context in, nothing recorded',
-            fix: 'harbor on',
-        });
-    }
-    else if (arms && !arms.capture) {
-        checks.push({
-            label: 'Recording',
-            state: 'paused',
-            detail: 'recall on, recording paused on purpose',
-            fix: 'harbor on',
-        });
-    }
-    else {
-        checks.push({ label: 'Recording', state: 'ok', detail: 'on' });
-    }
-    appendReceiptCheck(checks, config, present);
-    await appendVersionCheck(checks, opts);
-    const metrics = await appendLoopChecks(checks, opts, {
-        installedToken,
-        origin,
-        paused: arms !== null && !arms.recall,
-    });
-    await appendRecallDeliveryCheck(checks);
-    return { checks, metrics };
-}
-const RECALL_HEALTHY = new Set([
-    'delivered',
-    'delivered-delta',
-    'redelivered-after-compact',
-    'no-shift',
-    'no-query',
-    'desktop-chat',
-    'recall-off',
-    'empty-bundle',
-]);
-function shortRepoName(origin) {
-    const match = /([^/:]+\/[^/]+?)(?:\.git)?\/?$/.exec(origin);
-    return match?.[1] ?? origin;
-}
-const RECALL_FIXES = {
-    'no-auth': 'harbor init',
-    'no-config': 'harbor sync',
-    'not-allowlisted': 'harbor bind',
-};
-async function appendPayloadCheck(checks, home) {
-    const budget = await measureReportBudget(home === undefined ? {} : { home });
-    if (budget === null) {
-        checks.push({
-            label: 'Sent to harbor',
-            state: 'warn',
-            detail: 'machine facts and file digests — the skill inventory could not be measured here',
-            fix: 'harbor context',
-        });
-        return;
-    }
-    const owned = { harbor: 0, 'other-tool': 0, nobody: 0 };
-    for (const skill of budget.skills)
-        owned[skill.owner] += 1;
-    checks.push({
-        label: 'Sent to harbor',
-        state: 'ok',
-        detail: `file digests · ~${budget.tokens.toLocaleString('en-US')} tok floor · ` +
-            `${budget.skills.length} skill name${budget.skills.length === 1 ? '' : 's'} ` +
-            `(${owned.harbor} ours · ${owned['other-tool']} other tools · ${owned.nobody} unowned), ` +
-            'home only. Never file contents.',
-    });
-}
-async function appendMcpTargetCheck(checks, cwd, home, endpoints) {
-    const readEntry = async (path) => {
-        try {
-            const root = JSON.parse(await readFile(path, 'utf8'));
-            const servers = root?.mcpServers;
-            if (!servers || typeof servers !== 'object')
-                return null;
-            const entry = servers[claude.MCP_KEY];
-            return entry && typeof entry === 'object'
-                ? entry
-                : null;
-        }
-        catch {
-            return null;
-        }
-    };
-    const projectRoot = gitRoot(cwd) ?? cwd;
-    const project = await readEntry(join(projectRoot, '.mcp.json'));
-    const user = await readEntry(claude.resolveClaudePaths(home).mcpConfigPath);
-    const winner = project ?? user;
-    if (!winner) {
-        checks.push({
-            label: 'MCP target',
-            state: 'warn',
-            detail: 'no harbor MCP server registered — tool calls reach no graph',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    const url = typeof winner.url === 'string' ? winner.url : null;
-    const isStdio = typeof winner.command === 'string';
-    const source = project ? '.mcp.json (project)' : '~/.claude.json (user)';
-    if (project && isStdio && !isLocalEndpoint(endpoints)) {
-        checks.push({
-            label: 'MCP target',
-            state: 'fail',
-            detail: `SPLIT BRAIN — ${source} runs harbor as a local stdio server, but ` +
-                `recall reads ${endpoints.apiUrl}. Learnings you record go to the ` +
-                'local graph; injections come from the remote one.',
-            fix: 'rename the .mcp.json entry (e.g. "harbor-dev") so the tool name says which graph',
-        });
-        return;
-    }
-    if (url && url !== endpoints.mcpUrl) {
-        checks.push({
-            label: 'MCP target',
-            state: 'warn',
-            detail: `${url} from ${source}, but recall reads ${endpoints.apiUrl}`,
-            fix: 'harbor init',
-        });
-        return;
-    }
-    checks.push({
-        label: 'MCP target',
-        state: 'ok',
-        detail: isStdio
-            ? `local stdio server from ${source} (recall is local too)`
-            : `${url ?? endpoints.mcpUrl} — same graph recall reads`,
-    });
-}
-async function appendDaemonCheck(checks) {
-    const verdict = daemonVerdict(await readDaemonHeartbeat());
-    const state = verdict.kind === 'ok'
-        ? 'ok'
-        : verdict.kind === 'never_run' ||
-            verdict.kind === 'degraded' ||
-            verdict.kind === 'idle'
-            ? 'warn'
-            : 'fail';
-    checks.push({
-        label: 'Background sync',
-        state,
-        detail: verdict.detail,
-        ...('fix' in verdict ? { fix: verdict.fix } : {}),
-    });
-}
-async function appendRecallDeliveryCheck(checks) {
-    let text;
-    try {
-        text = await readFile(recallOutcomesFile(), 'utf8');
-    }
-    catch {
-        checks.push({
-            label: 'Recall delivery',
-            state: 'ok',
-            detail: 'no prompts recorded yet',
-        });
-        return;
-    }
-    const counts = new Map();
-    const emptyByRepo = new Map();
-    let total = 0;
-    for (const line of text.split('\n')) {
-        if (line.trim() === '')
-            continue;
-        try {
-            const row = JSON.parse(line);
-            const outcome = typeof row.outcome === 'string'
-                ? row.outcome
-                : 'unknown';
-            counts.set(outcome, (counts.get(outcome) ?? 0) + 1);
-            const origin = row.origin;
-            if (outcome === 'empty-bundle' && typeof origin === 'string' && origin !== '') {
-                emptyByRepo.set(origin, (emptyByRepo.get(origin) ?? 0) + 1);
-            }
-            total += 1;
-        }
-        catch {
-        }
-    }
-    if (total === 0) {
-        checks.push({
-            label: 'Recall delivery',
-            state: 'ok',
-            detail: 'no prompts recorded yet',
-        });
-        return;
-    }
-    const unhealthy = [...counts.entries()]
-        .filter(([outcome]) => !RECALL_HEALTHY.has(outcome))
-        .sort((a, b) => b[1] - a[1]);
-    const healthy = total - unhealthy.reduce((sum, [, n]) => sum + n, 0);
-    const restored = counts.get('redelivered-after-compact') ?? 0;
-    const lost = counts.get('context-lost') ?? 0;
-    const served = (counts.get('delivered') ?? 0) +
-        (counts.get('delivered-delta') ?? 0) +
-        restored;
-    const truncations = restored + lost;
-    const possession = truncations === 0
-        ? ''
-        : ` · ${restored} of ${truncations} restored after a compaction`;
-    const topEmpty = [...emptyByRepo.entries()].sort((a, b) => b[1] - a[1])[0];
-    const attribution = topEmpty
-        ? ` · ${counts.get('empty-bundle') ?? 0} empty bundles, most in ${shortRepoName(topEmpty[0])}×${topEmpty[1]}`
-        : '';
-    const summary = `${ratio(healthy, total)} healthy over ${total} prompts — ${served} served context${possession}${attribution}`;
-    if (unhealthy.length === 0) {
-        checks.push({ label: 'Recall delivery', state: 'ok', detail: summary });
-        return;
-    }
-    const worst = unhealthy[0];
-    const breakdown = unhealthy.map(([o, n]) => `${o}×${n}`).join(', ');
-    checks.push({
-        label: 'Recall delivery',
-        state: 'warn',
-        detail: `${summary} · ${breakdown}`,
-        ...(worst && RECALL_FIXES[worst[0]] ? { fix: RECALL_FIXES[worst[0]] } : {}),
-    });
-}
-async function appendDocumentChecks(checks, cwd) {
-    const root = gitRoot(cwd);
-    if (root === null)
-        return;
-    const docs = await inspectRepoDocuments(root);
-    if (!docs.managed || docs.documents.length === 0) {
-        checks.push({
-            label: 'Documents',
-            state: 'unknown',
-            detail: 'none in .claude/docs/ — no document is connected to this repo',
-        });
-        return;
-    }
-    const forked = inState(docs, 'forked');
-    const missing = inState(docs, 'missing');
-    const unverifiable = inState(docs, 'unverifiable');
-    const total = docs.documents.length;
-    if (forked.length > 0) {
-        const [first, ...rest] = forked;
-        const others = rest.length > 0 ? ` (and ${rest.length} more)` : '';
-        checks.push({
-            label: 'Documents',
-            state: 'warn',
-            detail: `${first}${others} has local edits — harbor will not overwrite it, ` +
-                'and it stops updating in this repo',
-            fix: `discard yours: rm ${DOCS_DIR}/${first}   (the next sync restores it)`,
-        });
-        return;
-    }
-    if (unverifiable.length > 0) {
-        checks.push({
-            label: 'Documents',
-            state: 'unknown',
-            detail: `${unverifiable.length} of ${total} synced before this CLI could check for edits — the next sync stamps them`,
-        });
-        return;
-    }
-    if (missing.length > 0) {
-        checks.push({
-            label: 'Documents',
-            state: 'warn',
-            detail: `${missing.length} of ${total} are listed but not on disk — ${missing[0]} is gone`,
-            fix: 'the next sync restores them; the desktop app must be running',
-        });
-        return;
-    }
-    checks.push({
-        label: 'Documents',
-        state: 'ok',
-        detail: `${total} synced from harbor, unedited`,
-    });
-}
-async function appendSkillChecks(checks, cwd, present, home) {
-    const root = gitRoot(cwd);
-    const report = (label, managed, emptyDetail, fixHint) => {
-        if (!managed.managed || managed.skills.length === 0) {
-            checks.push({ label, state: 'unknown', detail: emptyDetail });
-            return;
-        }
-        const forked = skillsInState(managed, 'forked');
-        const missing = skillsInState(managed, 'missing');
-        const unverifiable = skillsInState(managed, 'unverifiable');
-        const total = managed.skills.length;
-        if (forked.length > 0) {
-            const [first, ...rest] = forked;
-            const others = rest.length > 0 ? ` (and ${rest.length} more)` : '';
-            checks.push({
-                label,
-                state: 'warn',
-                detail: `${first}${others} has local edits — harbor will not overwrite it, ` +
-                    'and it stops updating here',
-                fix: `discard yours: rm -r ${fixHint}/${first}   (the next sync restores it)`,
-            });
-            return;
-        }
-        if (unverifiable.length > 0) {
-            checks.push({
-                label,
-                state: 'unknown',
-                detail: `${unverifiable.length} of ${total} synced before this CLI could check for edits — the next sync stamps them`,
-            });
-            return;
-        }
-        if (missing.length > 0) {
-            checks.push({
-                label,
-                state: 'warn',
-                detail: `${missing.length} of ${total} are listed but not on disk — ${missing[0]} is gone`,
-                fix: 'harbor sync',
-            });
-            return;
-        }
-        checks.push({ label, state: 'ok', detail: `${total} synced from harbor, unedited` });
-    };
-    if (root !== null) {
-        const repoRoots = await inspectRepoSkillRoots(root, {
-            agents: present,
-            ...(home === undefined ? {} : { home }),
-        });
-        for (const repoRoot of repoRoots) {
-            const dir = REPO_SKILL_DIR[repoRoot.agent];
-            report(repoRoot.agent === 'claude'
-                ? 'Skills'
-                : `Skills (${AGENT_LABEL[repoRoot.agent]})`, repoRoot, `none in ${dir}/ — no skill is connected to this repo`, dir);
-        }
-    }
-    const envRoots = await inspectEnvSkillRoots({
-        agents: present,
-        ...(home === undefined ? {} : { home }),
-    });
-    for (const root of envRoots) {
-        const dir = home === undefined ? root.dir.replace(homedir(), '~') : root.dir;
-        report(root.agent === 'claude'
-            ? 'Your skills'
-            : `Your skills (${AGENT_LABEL[root.agent]})`, root, `none in ${dir}/ — no skill is connected to you`, dir);
-    }
-}
-function appendReceiptCheck(checks, config, present) {
-    if (config === null)
-        return;
-    if (!config.receipt) {
-        checks.push({
-            label: 'Receipt',
-            state: 'paused',
-            detail: 'off, on purpose - rules still reach the agent, silently',
-            fix: 'harbor on --receipt',
-        });
-        return;
-    }
-    const cursorOnly = present.cursor && !present.claude && !present.codex;
-    if (cursorOnly) {
-        checks.push({
-            label: 'Receipt',
-            state: 'paused',
-            detail: 'Cursor cannot show it - its session-start hook discards the message',
-        });
-        return;
-    }
-    checks.push({
-        label: 'Receipt',
-        state: 'ok',
-        detail: present.cursor
-            ? 'on (not in Cursor - that host discards it)'
-            : 'on',
-    });
-}
-async function appendVersionCheck(checks, opts) {
-    if (opts.offline) {
-        checks.push({ label: 'Version', state: 'unknown', detail: 'not checked (--offline)' });
-        return;
-    }
-    const check = await refreshCliRelease({
-        force: true,
-        ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
-    });
-    if (check.kind === 'unreachable') {
-        checks.push({
-            label: 'Version',
-            state: 'unknown',
-            detail: 'could not reach the npm registry',
-        });
-        return;
-    }
-    if (check.kind === 'unknown-version') {
-        checks.push({
-            label: 'Version',
-            state: 'unknown',
-            detail: 'this build cannot read its own version',
-        });
-        return;
-    }
-    const { latest, current, behind, command } = check.release;
-    checks.push(behind
-        ? { label: 'Version', state: 'warn', detail: `${current} - ${latest} is available`, fix: command }
-        : { label: 'Version', state: 'ok', detail: current });
-}
-function claudeHooksMissing() {
-    return {
-        label: 'Hooks',
-        state: 'fail',
-        detail: 'not installed — nothing runs on a prompt',
-        fix: 'harbor init',
-    };
-}
-function appendCodexChecks(checks, present, config, hooksJson) {
-    const hasMcp = codex.hasMcpServer(config);
-    const hooks = codex.readInstalledHooks(hooksJson);
-    if (!present.codex && !hasMcp && !hooks.installed)
-        return;
-    if (!hasMcp && !hooks.installed) {
-        checks.push({
-            label: 'Codex',
-            state: 'warn',
-            detail: 'installed on this machine, but not configured — its sessions get nothing',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    if (!hooks.installed) {
-        checks.push({
-            label: 'Codex',
-            state: 'fail',
-            detail: 'MCP tools are configured, but no hooks — nothing runs on a prompt',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    if (!hasMcp) {
-        checks.push({
-            label: 'Codex',
-            state: 'fail',
-            detail: 'hooks are registered, but there is no MCP bearer for them to use',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    const paths = codex.resolveCodexPaths();
-    const stamps = codex.countHookTrustStamps(config, paths.hooksJsonPath);
-    if (stamps === 0) {
-        checks.push({
-            label: 'Codex',
-            state: 'fail',
-            detail: `${hooks.commands.length} hooks registered and NONE trusted — Codex will not run them`,
-            fix: 'harbor init  (stamps the trust hashes `codex` reports)',
-        });
-        return;
-    }
-    const stale = hooks.commands.filter((c) => !c.startsWith(hooksBinDir()));
-    if (stale.length > 0) {
-        const dir = stale[0].replace(/\/[^/]+$/, '');
-        checks.push(staleHooksCheck(dir, 'Codex'));
-        return;
-    }
-    const missing = codex.MANAGED_HOOK_EVENTS.filter((event) => !hooks.events.includes(event));
-    if (missing.length > 0) {
-        checks.push({
-            label: 'Codex',
-            state: 'warn',
-            detail: describePartialHooks(hooks.events.length, codex.MANAGED_HOOK_EVENTS.length, missing, CODEX_CAPABILITY_BY_EVENT),
-            fix: 'harbor init  (registers the events that are missing)',
-        });
-        return;
-    }
-    checks.push({
-        label: 'Codex',
-        state: 'ok',
-        detail: `${hooks.commands.length} hooks installed, ${stamps} trusted`,
-    });
-}
-function appendCursorChecks(checks, present, mcpJson, hooksJson) {
-    const hasMcp = cursor.hasMcpServer(mcpJson);
-    const hooks = cursor.readInstalledHooks(hooksJson);
-    if (!present.cursor && !hasMcp && !hooks.installed)
-        return;
-    if (!hasMcp && !hooks.installed) {
-        checks.push({
-            label: 'Cursor',
-            state: 'warn',
-            detail: 'installed on this machine, but not configured — its sessions get nothing',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    if (!hooks.installed) {
-        checks.push({
-            label: 'Cursor',
-            state: 'fail',
-            detail: 'MCP tools are configured, but no hooks — nothing runs on a session',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    if (!hasMcp) {
-        checks.push({
-            label: 'Cursor',
-            state: 'fail',
-            detail: 'hooks are registered, but there is no MCP bearer for them to use',
-            fix: 'harbor init',
-        });
-        return;
-    }
-    const commented = [
-        ...(cursor.stripJsonComments(mcpJson).hadComments ? ['~/.cursor/mcp.json'] : []),
-        ...(cursor.stripJsonComments(hooksJson).hadComments ? ['~/.cursor/hooks.json'] : []),
-    ];
-    if (commented.length > 0) {
-        checks.push({
-            label: 'Cursor',
-            state: 'warn',
-            detail: `${commented.join(' and ')} contains comments — Harbor will not rewrite it`,
-            fix: 'remove the comments so `harbor init` can update this file',
-        });
-        return;
-    }
-    const stale = hooks.commands.filter((c) => !c.startsWith(hooksBinDir()));
-    if (stale.length > 0) {
-        const dir = stale[0].replace(/\/[^/]+$/, '');
-        checks.push(staleHooksCheck(dir, 'Cursor'));
-        return;
-    }
-    const missing = cursor.MANAGED_HOOK_EVENTS.filter((event) => !hooks.events.includes(event));
-    if (missing.length > 0) {
-        checks.push({
-            label: 'Cursor',
-            state: 'warn',
-            detail: describePartialHooks(hooks.events.length, cursor.MANAGED_HOOK_EVENTS.length, missing, CURSOR_CAPABILITY_BY_EVENT),
-            fix: 'harbor init  (registers the events that are missing)',
-        });
-        return;
-    }
-    checks.push({
-        label: 'Cursor',
-        state: 'ok',
-        detail: `${hooks.commands.length} hooks installed — recall lands at session start, restored after a compaction (Cursor has no per-turn injection)`,
-    });
-}
-function staleHooksCheck(dir, label = 'Hooks') {
-    const legacy = legacyDirs().some((home) => dir === home || dir.startsWith(`${home}/`));
-    if (legacy) {
-        return {
-            label,
-            state: 'fail',
-            detail: `installed from ${dir} — a PREVIOUS release's home; those hooks scrape for an older sentinel, so citations and capture from this machine are lost`,
-            fix: 'harbor init  (re-points them at ~/.harbor/bin)',
-        };
-    }
-    return {
-        label,
-        state: 'warn',
-        detail: `installed from ${dir} — ${isAppBundlePath(dir)
-            ? 'a path that dies with the app'
-            : 'not where this CLI installs them'}`,
-        fix: 'harbor init  (re-points them at ~/.harbor/bin)',
-    };
-}
-function isAppBundlePath(dir) {
-    return /\.app\//i.test(dir) || /resources\/hooks/i.test(dir);
-}
-function markTokenRejected(checks) {
-    const index = checks.findIndex((check) => check.label === 'Token');
-    if (index === -1)
-        return;
-    checks[index] = {
-        label: 'Token',
-        state: 'fail',
-        detail: 'the backend rejected it — well-formed, but not accepted',
-        fix: 'the next prompt re-mints it; run `harbor init` if this persists',
-    };
-}
-async function appendLoopChecks(checks, opts, ctx) {
-    const labels = ['Recall', 'Fit', 'Attribution', 'Contributed'];
-    if (opts.offline) {
-        for (const label of labels) {
-            checks.push({ label, state: 'unknown', detail: 'not checked (--offline)' });
-        }
-        return null;
-    }
-    if (!ctx.installedToken) {
-        for (const label of labels) {
-            checks.push({
-                label,
-                state: 'unknown',
-                detail: 'no bearer to ask with',
-            });
-        }
-        return null;
-    }
-    let metrics;
-    try {
-        metrics = await fetchLoopMetrics(opts.endpoints.apiUrl, ctx.installedToken, { originUrl: ctx.origin || undefined, windowDays: opts.windowDays }, opts.fetchImpl);
-    }
-    catch (err) {
-        const skewed = err instanceof ApiError && err.kind === 'shape';
-        const unpaid = err instanceof ApiError && err.kind === 'payment_required';
-        const reason = skewed
-            ? 'the backend answered, but not in a shape this CLI can read'
-            : unpaid
-                ? 'this workspace is past due, so recall is paused'
-                : err instanceof ApiError && err.kind === 'network'
-                    ? 'the backend is unreachable'
-                    : err instanceof ApiError
-                        ? `the backend said ${err.status ?? err.kind}`
-                        : 'the measurement call failed';
-        if (err instanceof ApiError && (err.kind === 'unauthorized' || err.kind === 'forbidden')) {
-            markTokenRejected(checks);
-        }
-        checks.push({
-            label: 'Recall',
-            state: 'unknown',
-            detail: reason,
-        });
-        checks.push(skewed
-            ? {
-                label: 'Attribution',
-                state: 'fail',
-                detail: `the loop numbers are unreadable — this CLI and the backend disagree about their shape (${err.message})`,
-                fix: 'upgrade this CLI: npx harborloop@latest doctor',
-            }
-            : unpaid
-                ? {
-                    label: 'Attribution',
-                    state: 'fail',
-                    detail: err.message,
-                    fix: 'update billing in the harbor app to restore recall',
-                }
-                : {
-                    label: 'Attribution',
-                    state: 'fail',
-                    detail: "this repo's sessions are not being counted",
-                    fix: 'harbor doctor --offline shows what is reachable',
-                });
-        for (const label of ['Fit', 'Contributed', 'Corpus']) {
-            checks.push({ label, state: 'unknown', detail: reason });
-        }
-        return null;
-    }
-    const scope = metrics.projectId ? 'this project' : 'workspace-wide';
-    const window = `last ${metrics.windowDays} days, ${scope}`;
-    const { recall, fit, attribution, contributed } = metrics;
-    checks.push({
-        label: 'Recall',
-        state: recall.sessions === 0 ? 'unknown' : recall.served === 0 ? 'warn' : 'ok',
-        detail: recall.sessions === 0
-            ? `${window} — no sessions yet`
-            : `${window}   ${recall.sessions} sessions · ${ratio(recall.served, recall.sessions)} received context`,
-        ...(recall.sessions > 0 && recall.served === 0
-            ? { fix: 'nothing was served — check that this repo is bound to a project' }
-            : {}),
-    });
-    const uncited = fit.servedAtoms - fit.citedAtoms;
-    checks.push({
-        label: 'Fit',
-        state: fit.servedAtoms === 0
-            ? 'unknown'
-            : fit.citedAtoms / fit.servedAtoms < 0.5
-                ? 'warn'
-                : 'ok',
-        detail: fit.servedAtoms === 0
-            ? 'nothing served yet'
-            : `avg bundle ${fit.avgBundle?.toFixed(1) ?? '—'}   ${ratio(uncited, fit.servedAtoms)} served atoms went uncited`,
-    });
-    checks.push({
-        label: 'Attribution',
-        state: ctx.paused
-            ? 'paused'
-            : attribution.recalls === 0
-                ? 'unknown'
-                : attribution.keyed === attribution.recalls
-                    ? 'ok'
-                    : 'fail',
-        detail: ctx.paused
-            ? 'paused, on purpose — nothing to count'
-            : attribution.recalls === 0
-                ? 'no recalls to count yet'
-                : attribution.keyed === attribution.recalls
-                    ? `${attribution.keyed}/${attribution.recalls} recalls counted`
-                    : `this repo's sessions are not all being counted — ${ratio(attribution.keyed, attribution.recalls)}`,
-        ...(attribution.recalls > 0 && attribution.keyed < attribution.recalls
-            ? { fix: 'an unkeyed recall is invisible to the loop — re-run `harbor init`' }
-            : {}),
-    });
-    const byTransport = metrics.byTransport;
-    checks.push({
-        label: 'Surfaces',
-        state: !byTransport || byTransport.length === 0 ? 'unknown' : 'ok',
-        detail: !byTransport
-            ? 'this backend does not group recalls by surface yet'
-            : byTransport.length === 0
-                ? `${window} — no recalls to place`
-                : byTransport
-                    .map((row) => `${row.label} ${ratio(row.keyed, row.recalls)}` +
-                    (row.clients.length > 1 ? ` [${row.clients.join(' + ')}]` : ''))
-                    .join('   '),
-    });
-    checks.push({
-        label: 'Contributed',
-        state: contributed.total === 0 ? 'unknown' : 'ok',
-        detail: contributed.total === 0
-            ? `${window} — nothing recorded from this repo`
-            : `${contributed.total} learnings   ${contributed.approved} approved · ${contributed.pending} pending review`,
-    });
-    const corpus = metrics.corpus;
-    const topCause = corpus?.retiredByCause?.[0];
-    checks.push({
-        label: 'Corpus',
-        state: !corpus || corpus.ledgerEmpty ? 'unknown' : 'ok',
-        detail: !corpus
-            ? 'this backend does not keep a corpus ledger yet'
-            : corpus.ledgerEmpty
-                ? `${corpus.liveAtoms} live atoms — nothing added or retired has been recorded yet`
-                : `last ${metrics.windowDays} days, workspace-wide   ` +
-                    `+${corpus.admitted} / −${corpus.retired}   ` +
-                    `${corpus.liveAtoms} live` +
-                    (topCause
-                        ? `   (most retirements: ${topCause.cause} ${topCause.count})`
-                        : ''),
-    });
-    const spend = metrics.spend;
-    checks.push({
-        label: 'Cost',
-        state: !spend
-            ? 'unknown'
-            : spend.costPerCitedAtomUsd === null
-                ? 'unknown'
-                : 'ok',
-        detail: !spend
-            ? 'this backend does not price the corpus yet'
-            : spend.costPerCitedAtomUsd === null
-                ? spend.spendRows === 0
-                    ? `last ${metrics.windowDays} days, workspace-wide — no write-path calls`
-                    : `${spend.spendRows} write-path calls bought nothing anyone cited — no denominator`
-                : `last ${metrics.windowDays} days, workspace-wide   ` +
-                    `$${spend.costPerCitedAtomUsd.toFixed(4)} per cited atom   ` +
-                    `($${spend.writeSpendUsd.toFixed(4)} over ${spend.citedAtoms} atoms` +
-                    (spend.unpricedRows > 0
-                        ? `, ${spend.unpricedRows}/${spend.spendRows} calls unpriced — a floor)`
-                        : ')'),
-    });
-    return metrics;
-}