@phnx-labs/agents-cli 1.20.78 → 1.20.82

package/dist/commands/doctor.js

@@ -3,7 +3,8 @@ import { explainIsolationBoundary } from '../lib/isolation-boundary-report.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
-import { fanOutDevices } from '../lib/devices/fleet.js';
+import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { fleetDialTarget } from '../lib/devices/connect.js';
 import { compareFleetInventories } from '../lib/devices/fleet-divergence.js';
 import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
 import { resolveHost } from '../lib/hosts/registry.js';
@@ -17,7 +18,9 @@ import { formatSignInBadge } from '../lib/signin-badge.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
-import { checkSyncStatus, countOrphans } from '../lib/drift.js';
+import { checkVersionHookWiring, registerHooksToSettings } from '../lib/hooks.js';
+import { isVersionIsolated } from '../lib/versions.js';
+import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
@@ -65,6 +68,18 @@ function printWrappedLine(prefix, text) {
         console.log(chalk.gray(line));
 }
 function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers) {
+    // Triaged health banner FIRST, so a user running bare `agents doctor` sees what
+    // is unhealthy, why it matters, and the exact fix before scrolling the detail
+    // sections below. Same triage model as target mode, aggregated across versions.
+    const overviewHealth = computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers);
+    console.log(chalk.bold('Health'));
+    renderHealthBlock(overviewHealth, {
+        healthySummary: syncRows.length
+            ? `${syncRows.length} version${syncRows.length === 1 ? '' : 's'} reconciled · hooks wired · sources current`
+            : 'no installed versions to check',
+        healFix: verdictIsAutoFixable(overviewHealth) ? 'agents doctor --fix' : undefined,
+    });
+    console.log();
     console.log(chalk.bold('Agent CLIs'));
     // Show the fleet you actually run — agents that are ready in PATH, plus any
     // you MANAGE (have installed versions) whose binary isn't resolving (a real
@@ -103,20 +118,26 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBe
         for (const row of syncRows) {
             const tag = row.isDefault ? chalk.gray(' (default)') : '';
             const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}${tag}`;
-            if (row.status === 'fresh') {
+            const unwired = (row.unwiredHooks ?? 0) > 0;
+            if (row.status === 'fresh' && !unwired) {
                 console.log(`  ${chalk.green('fresh')}  ${label}`);
+                continue;
             }
-            else if (row.status === 'stale') {
-                anyOutOfSync = true;
+            anyOutOfSync = true;
+            if (row.status === 'stale') {
                 console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— sources changed since last sync')}`);
-                for (const line of row.divergence ?? []) {
-                    console.log(chalk.gray(`           ${line}`));
-                }
             }
-            else {
-                anyOutOfSync = true;
+            else if (row.status === 'never-synced') {
                 console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced')}`);
             }
+            else {
+                // Manifest-fresh but a declared hook is present-on-disk yet not wired into
+                // settings.json — it never fires (the yosemite-s1 blind spot).
+                console.log(`  ${chalk.red('unwired')} ${label}  ${chalk.gray('— hooks present but not wired into settings.json')}`);
+            }
+            for (const line of row.divergence ?? []) {
+                console.log(chalk.gray(`           ${line}`));
+            }
         }
         // Launching does NOT reconcile a version home — the shim hot path only
         // resolves a version and compiles project-scoped resources (shims.ts v15/v16).
@@ -260,7 +281,7 @@ function renderExecPolicyAdvisory() {
         console.log(chalk.gray(`           ${line}`));
     }
 }
-const AGENT_ORDER = ['claude', 'codex', 'kimi', 'grok', 'antigravity', 'opencode', 'cursor', 'gemini', 'droid'];
+const AGENT_ORDER = ['claude', 'codex', 'kimi', 'grok', 'antigravity', 'opencode', 'cursor', 'droid'];
 function shortAgentHeader(name) {
     return name.slice(0, 4).padEnd(4);
 }
@@ -619,6 +640,284 @@ function readExpectedForDiff(kind, row) {
         return null;
     return safeRead(row.sourcePath);
 }
+// Family of agents whose hooks re-wire through registerHooksToSettings into a
+// Claude-style settings.json (matches checkVersionHookWiring's supported set).
+const HOOK_WIRING_FIX_AGENTS = ['claude', 'droid'];
+/** Categories `--fix` reconciles (vs. `agents repo pull` for a behind source, or
+ *  `agents prune cleanup` for an orphan). Drives the heal footer. */
+const AUTO_FIXABLE_CATEGORIES = new Set([
+    'unwired-hook', 'settings-missing', 'settings-unparseable', 'missing', 'divergent', 'stale', 'never-synced',
+]);
+export function verdictIsAutoFixable(v) {
+    return v.issues.some((i) => AUTO_FIXABLE_CATEGORIES.has(i.category));
+}
+/**
+ * Fold a version report's divergences into a triaged verdict — one severity-tagged
+ * finding per unwired hook, missing/divergent/extra resource, and behind-origin
+ * source layer, each carrying its subject, plain-English impact, and exact fix. An
+ * UNWIRED hook or a stale source is as unhealthy as a divergent file, not a
+ * footnote. Pure so the health rollup is unit-testable without a version home.
+ */
+export function computeVerdict(report) {
+    const issues = [];
+    const idLabel = `${report.agent}@${report.version}`;
+    const fixCmd = `agents doctor ${idLabel} --fix`;
+    const syncCmd = `agents sync ${idLabel} --yes`;
+    // ── critical: settings.json / unwired hooks (silent breakage) ──
+    const w = report.hookWiring;
+    if (w?.settingsMissing) {
+        const n = w.expected ?? 0;
+        issues.push({
+            severity: 'critical', category: 'settings-missing', subject: 'settings.json',
+            impact: `not found; ${n} declared hook${n === 1 ? '' : 's'} never fire`,
+            fix: syncCmd,
+            text: `settings.json missing (${n} hook${n === 1 ? '' : 's'} unwired)`, color: 'red',
+        });
+    }
+    else if (w?.settingsUnparseable) {
+        issues.push({
+            severity: 'critical', category: 'settings-unparseable', subject: 'settings.json',
+            impact: `unparseable; hook wiring can't be verified`,
+            fix: syncCmd,
+            text: 'settings.json unparseable', color: 'red',
+        });
+    }
+    else if (w) {
+        for (const u of w.unwired) {
+            issues.push({
+                severity: 'critical', category: 'unwired-hook', subject: u.name,
+                impact: 'on disk but not wired into settings.json; the hook never fires',
+                fix: syncCmd,
+                text: `${u.name} unwired`, color: 'red',
+            });
+        }
+    }
+    // ── critical: missing resources (declared in sources, absent from home) ──
+    for (const kind of DOCTOR_ALL_KINDS) {
+        for (const r of report.kinds[kind]) {
+            if (r.status !== 'missing')
+                continue;
+            issues.push({
+                severity: 'critical', category: 'missing', subject: r.name,
+                impact: `declared in sources but absent from the version home (${kind})`,
+                fix: fixCmd,
+                text: `${r.name} missing`, color: 'red',
+            });
+        }
+    }
+    // ── warning: source layer behind origin (home reconciled against stale truth) ──
+    for (const b of report.sourceBehind ?? []) {
+        if (b.behind <= 0)
+            continue;
+        issues.push({
+            severity: 'warning', category: 'source-behind', subject: b.label,
+            impact: `${b.behind} commit${b.behind === 1 ? '' : 's'} behind ${b.branch}; you're running stale config`,
+            fix: `agents repo pull ${b.alias}`,
+            text: `source ${b.label} ${b.behind} commit${b.behind === 1 ? '' : 's'} behind ${b.branch}`, color: 'yellow',
+        });
+    }
+    // ── warning: divergent resources (drifted from source) ──
+    for (const kind of DOCTOR_ALL_KINDS) {
+        for (const r of report.kinds[kind]) {
+            if (r.status !== 'diff')
+                continue;
+            issues.push({
+                severity: 'warning', category: 'divergent', subject: r.name,
+                impact: r.detail ? collapseWhitespace(r.detail) : 'differs from source',
+                fix: fixCmd,
+                text: `${r.name} divergent`, color: 'yellow',
+            });
+        }
+    }
+    // ── info: extra / orphan resources (present in home, no source) ──
+    for (const kind of DOCTOR_ALL_KINDS) {
+        for (const r of report.kinds[kind]) {
+            if (r.status !== 'extra')
+                continue;
+            issues.push({
+                severity: 'info', category: 'extra', subject: r.name,
+                impact: `orphan in the version home with no source (${kind})`,
+                fix: 'agents prune cleanup',
+                text: `${r.name} extra`, color: 'magenta',
+            });
+        }
+    }
+    return { healthy: issues.length === 0, issues, reconciled: report.summary.ok };
+}
+// ─── triaged health block (shared by target + overview) ────────────────────────
+const SEVERITY_COLOR = {
+    critical: chalk.red,
+    warning: chalk.yellow,
+    info: chalk.magenta,
+};
+// Restrained terminal glyphs — the ✓ ✗ ⚠ set plus a subtle info dot, colored via
+// chalk to match the man-page voice. No colorful emoji.
+const SEVERITY_GLYPH = {
+    critical: '✗',
+    warning: '⚠',
+    info: '·',
+};
+function severityCounts(issues) {
+    return {
+        critical: issues.filter((i) => i.severity === 'critical').length,
+        warning: issues.filter((i) => i.severity === 'warning').length,
+        info: issues.filter((i) => i.severity === 'info').length,
+    };
+}
+/** The info tier (orphans; one identical `prune cleanup` fix, already enumerated
+ *  in the detail section) is capped with a rollup so the block stays scannable
+ *  when a version home carries dozens of orphans. Critical + warning are
+ *  actionable, each with a distinct subject/fix, so they are never capped. */
+const INFO_CAP = 5;
+/**
+ * Build the lines of a triaged health block: a single green ✓ line when healthy,
+ * otherwise a severity-counted ✗ header followed by one row per finding (icon ·
+ * severity · subject — impact, then the exact fix under it) and an optional heal
+ * footer. Pure — returns the lines so the rendered output is unit-testable. Shared
+ * by target mode and the bare overview so both read the same way.
+ */
+export function healthBlockLines(verdict, opts) {
+    if (verdict.healthy) {
+        return [`  ${chalk.green('✓')} ${chalk.green('healthy')} ${chalk.gray('— ' + opts.healthySummary)}`];
+    }
+    const lines = [];
+    const c = severityCounts(verdict.issues);
+    const bits = [];
+    if (c.critical)
+        bits.push(`${c.critical} critical`);
+    if (c.warning)
+        bits.push(`${c.warning} warning${c.warning === 1 ? '' : 's'}`);
+    if (c.info)
+        bits.push(`${c.info} info`);
+    const total = verdict.issues.length;
+    lines.push(`  ${chalk.red('✗')} ${chalk.red('unhealthy')} ${chalk.gray(`— ${total} issue${total === 1 ? '' : 's'} (${bits.join(' · ')})`)}`);
+    lines.push('');
+    const cont = ' '.repeat(14); // aligns the fix line under the subject column
+    const issueLines = (i) => {
+        const glyph = SEVERITY_COLOR[i.severity](SEVERITY_GLYPH[i.severity]);
+        const word = SEVERITY_COLOR[i.severity](i.severity.padEnd(8));
+        lines.push(`  ${glyph} ${word}  ${chalk.bold(i.subject)} ${chalk.gray('— ' + i.impact)}`);
+        lines.push(chalk.gray(`${cont}→ ${i.fix}`));
+    };
+    const actionable = verdict.issues.filter((i) => i.severity !== 'info');
+    const infoIssues = verdict.issues.filter((i) => i.severity === 'info');
+    for (const i of actionable)
+        issueLines(i);
+    for (const i of infoIssues.slice(0, INFO_CAP))
+        issueLines(i);
+    const hiddenInfo = infoIssues.length - Math.min(infoIssues.length, INFO_CAP);
+    if (hiddenInfo > 0) {
+        const glyph = SEVERITY_COLOR.info(SEVERITY_GLYPH.info);
+        const word = SEVERITY_COLOR.info('info'.padEnd(8));
+        lines.push(`  ${glyph} ${word}  ${chalk.gray(`+${hiddenInfo} more orphan${hiddenInfo === 1 ? '' : 's'}`)} ${chalk.gray('— agents prune cleanup')}`);
+    }
+    if (opts.healFix) {
+        lines.push('');
+        lines.push(`  ${chalk.gray("heal what's auto-fixable:")}  ${opts.healFix}`);
+    }
+    return lines;
+}
+function renderHealthBlock(verdict, opts) {
+    for (const line of healthBlockLines(verdict, opts))
+        console.log(line);
+}
+/**
+ * Aggregate the bare `agents doctor` overview into the same triaged verdict target
+ * mode uses — folding per-version wiring/sync drift, behind-origin source layers,
+ * and orphan resources into severity-tagged findings. Agent-agnostic: every
+ * installed version is classified the same way. Pure, so it is unit-testable.
+ */
+export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers) {
+    const issues = [];
+    const pretty = (agent, version) => `${AGENT_NAMES[agent] || agent}@${version}`;
+    // critical: unwired hooks / broken settings.json per version
+    for (const row of syncRows) {
+        const n = row.unwiredHooks ?? 0;
+        if (n <= 0)
+            continue;
+        const label = pretty(row.agent, row.version);
+        issues.push({
+            severity: 'critical', category: 'unwired-hook', subject: label,
+            impact: `${n} hook${n === 1 ? '' : 's'} present on disk but not wired into settings.json; never fire`,
+            fix: `agents sync ${row.agent}@${row.version} --yes`,
+            text: `${label} ${n} unwired`, color: 'red',
+        });
+    }
+    // warning: source layers behind origin
+    for (const m of repoBehindMarkers) {
+        if (m.behind <= 0)
+            continue;
+        const label = m.alias === 'user' ? '~/.agents' : m.alias;
+        issues.push({
+            severity: 'warning', category: 'source-behind', subject: label,
+            impact: `${m.behind} commit${m.behind === 1 ? '' : 's'} behind ${m.branch}; you're running stale config`,
+            fix: `agents repo pull ${m.alias}`,
+            text: `${label} ${m.behind} behind`, color: 'yellow',
+        });
+    }
+    // warning: stale / never-synced versions
+    for (const row of syncRows) {
+        const label = pretty(row.agent, row.version);
+        if (row.status === 'stale') {
+            issues.push({
+                severity: 'warning', category: 'stale', subject: label,
+                impact: 'sources changed since last sync',
+                fix: `agents doctor ${row.agent}@${row.version} --fix`,
+                text: `${label} stale`, color: 'yellow',
+            });
+        }
+        else if (row.status === 'never-synced') {
+            issues.push({
+                severity: 'warning', category: 'never-synced', subject: label,
+                impact: 'installed but never synced',
+                fix: `agents sync ${row.agent}@${row.version} --yes`,
+                text: `${label} never-synced`, color: 'yellow',
+            });
+        }
+    }
+    // info: orphan resources per version
+    for (const row of orphanRows) {
+        const parts = [];
+        if (row.commands)
+            parts.push(`${row.commands} command${row.commands === 1 ? '' : 's'}`);
+        if (row.skills)
+            parts.push(`${row.skills} skill${row.skills === 1 ? '' : 's'}`);
+        if (row.hooks)
+            parts.push(`${row.hooks} hook${row.hooks === 1 ? '' : 's'}`);
+        const label = pretty(row.agent, row.version);
+        issues.push({
+            severity: 'info', category: 'orphan', subject: label,
+            impact: `${parts.join(', ')} in the version home with no source`,
+            fix: 'agents prune cleanup',
+            text: `${label} orphan`, color: 'magenta',
+        });
+    }
+    const reconciled = syncRows.filter((r) => r.status === 'fresh' && (r.unwiredHooks ?? 0) === 0).length;
+    return { healthy: issues.length === 0, issues, reconciled };
+}
+/**
+ * Render the UNWIRED hook rows (and settings.json problems) inside the hooks
+ * section, in the same row style as the reconcile rows above them.
+ */
+function renderHookWiringRows(w) {
+    if (!w.supported)
+        return;
+    if (w.settingsMissing) {
+        const where = w.settingsPath ? ` at ${w.settingsPath}` : '';
+        console.log(`    ${chalk.red('UNWIRED')}  ${chalk.gray(`settings.json not found${where} — ${w.expected ?? 0} declared hook(s) never fire`)}`);
+        return;
+    }
+    if (w.settingsUnparseable) {
+        const where = w.settingsPath ? ` at ${w.settingsPath}` : '';
+        console.log(`    ${chalk.red('UNWIRED')}  ${chalk.gray(`settings.json unparseable${where} — wiring can't be verified`)}`);
+        return;
+    }
+    for (const u of w.unwired) {
+        const name = padToWidth(truncateToWidth(u.name, 28), 28);
+        const scope = u.matcher ? `event=${u.event} matcher=${u.matcher}` : `event=${u.event}`;
+        console.log(`    ${chalk.red('UNWIRED')}  ${name} ${chalk.gray(scope)}`);
+    }
+}
 function renderTargetText(report, options) {
     const label = `${AGENT_NAMES[report.agent] || report.agent}@${report.version}`;
     console.log(chalk.bold(label));
@@ -660,23 +959,22 @@ function renderTargetText(report, options) {
         if (options.requestedKinds && !options.requestedKinds.has(kind))
             continue;
         renderKindSection(kind, rows, report.layers, options);
+        // A hook file can reconcile "ok" above yet be absent from settings.json — a
+        // present-but-dead hook. Surface that right under the hooks section.
+        if (kind === 'hooks' && report.hookWiring)
+            renderHookWiringRows(report.hookWiring);
     }
     console.log();
-    const { ok, diff, missing, extra } = report.summary;
-    const verdictParts = [];
-    if (diff)
-        verdictParts.push(chalk.yellow(`${diff} divergent`));
-    if (missing)
-        verdictParts.push(chalk.red(`${missing} missing`));
-    if (extra)
-        verdictParts.push(chalk.magenta(`${extra} extra`));
-    if (verdictParts.length === 0) {
-        console.log(chalk.green(`  Verdict: ${ok} resource${ok === 1 ? '' : 's'} reconciled. Version home matches resolved sources.`));
-    }
-    else {
-        console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        printWrappedLine('  ', `Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`);
-    }
+    const verdict = computeVerdict(report);
+    // A source layer behind origin is healed by `agents repo pull`, not `--fix` —
+    // the per-issue fix already names the right command, so the heal footer only
+    // shows when something is genuinely `--fix`-able (never in the source-behind or
+    // orphan-only case, where it would mislead).
+    const hooksWired = report.hookWiring?.supported ? ' · hooks wired' : '';
+    renderHealthBlock(verdict, {
+        healthySummary: `${verdict.reconciled} resource${verdict.reconciled === 1 ? '' : 's'} reconciled${hooksWired} · sources current`,
+        healFix: verdictIsAutoFixable(verdict) ? `agents doctor ${report.agent}@${report.version} --fix` : undefined,
+    });
 }
 // ─── fix / heal mode ───────────────────────────────────────────────────────────
 function renderHealText(result) {
@@ -730,6 +1028,53 @@ function renderHealText(result) {
         console.log(chalk.green(`✓ Healed ${bits.join(', ')}.`));
     }
 }
+/**
+ * Re-wire hooks that reconcile as files but are absent from settings.json.
+ *
+ * heal() only re-syncs resources the diff flags missing/diff; a hook whose file
+ * is byte-identical to source but never referenced in settings.json is neither,
+ * so heal walks past it. registerHooksToSettings (the same call `agents sync`
+ * makes at versions.ts) regenerates the wiring, so run it for any Claude-family
+ * version this fix targets that has unwired hooks. Only claude/droid — the set
+ * checkVersionHookWiring can verify.
+ */
+function rewireUnwiredHooks(parsed) {
+    const out = [];
+    const agents = parsed?.agent
+        ? (HOOK_WIRING_FIX_AGENTS.includes(parsed.agent) ? [parsed.agent] : [])
+        : HOOK_WIRING_FIX_AGENTS;
+    for (const agent of agents) {
+        // A named version is explicit consent; a sweep excludes isolated copies,
+        // mirroring heal().
+        const versions = parsed?.agent && parsed.versionExplicit
+            ? parsed.versions
+            : listInstalledVersions(agent).filter((v) => !isVersionIsolated(agent, v));
+        for (const version of versions) {
+            const before = checkVersionHookWiring(agent, version);
+            if (!before.supported)
+                continue;
+            const need = before.unwired.length + (before.settingsMissing ? (before.expected ?? 0) : 0);
+            if (need === 0)
+                continue;
+            registerHooksToSettings(agent, getVersionHomePath(agent, version));
+            const after = checkVersionHookWiring(agent, version);
+            const remaining = after.unwired.length + (after.settingsMissing ? (after.expected ?? 0) : 0);
+            out.push({ agent, version, rewired: Math.max(0, need - remaining), remaining });
+        }
+    }
+    return out;
+}
+function renderHookRewireText(rewired) {
+    for (const r of rewired) {
+        const label = `${AGENT_NAMES[r.agent] || r.agent}@${r.version}`;
+        if (r.remaining === 0) {
+            console.log(`  ${chalk.green('rewired')} ${label}  ${chalk.gray(`${r.rewired} hook${r.rewired === 1 ? '' : 's'} wired into settings.json`)}`);
+        }
+        else {
+            console.log(`  ${chalk.yellow('hold  ')} ${label}  ${chalk.gray(`${r.remaining} hook${r.remaining === 1 ? '' : 's'} still unwired — run \`agents sync ${r.agent}@${r.version} --yes\``)}`);
+        }
+    }
+}
 async function runFix(parsed, opts) {
     // Heal targets the global install — project layer is irrelevant, so cwd is
     // left to heal's neutral default rather than process.cwd().
@@ -744,11 +1089,170 @@ async function runFix(parsed, opts) {
         agent: parsed?.agent,
         versions: parsed?.versionExplicit ? parsed.versions : undefined,
     });
+    // Re-wire hooks the diff-driven heal leaves behind (present file, not wired).
+    const rewired = rewireUnwiredHooks(parsed);
     if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(JSON.stringify({ ...result, hookRewire: rewired }, null, 2));
         return;
     }
     renderHealText(result);
+    renderHookRewireText(rewired);
+}
+function checkLabel(row) {
+    return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+}
+function runCheckGate(opts, cwd) {
+    const drift = computeDrift(cwd);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            hasDrift: drift.hasDrift,
+            stale: drift.staleCount,
+            neverSynced: drift.neverSyncedCount,
+            unwiredHookVersions: drift.unwiredHookVersions,
+            orphanVersions: drift.orphanVersionCount,
+            sourceBehind: drift.sourceBehind,
+            versions: drift.syncRows.map((r) => ({
+                agent: r.agent,
+                version: r.version,
+                status: r.status,
+                isDefault: r.isDefault,
+                unwiredHooks: r.unwiredHooks ?? 0,
+                divergence: r.divergence ?? [],
+            })),
+        }, null, 2));
+        process.exit(drift.hasDrift ? 1 : 0);
+    }
+    if (drift.syncRows.length === 0) {
+        // Nothing installed is a clean state, not a failure — CI on a fresh
+        // checkout with no versions should pass, not error.
+        console.log(chalk.gray('check: no installed versions — nothing to verify'));
+        process.exit(0);
+    }
+    if (!drift.hasDrift) {
+        const orphanNote = drift.orphanVersionCount > 0
+            ? chalk.gray(` (${drift.orphanVersionCount} version(s) carry orphans — run \`agents prune cleanup\`)`)
+            : '';
+        console.log(`${chalk.green('ok')}  ${drift.syncRows.length} version(s) in sync${orphanNote}`);
+        process.exit(0);
+    }
+    // Drift: one-line verdict always, per-version detail unless --quiet.
+    const parts = [];
+    if (drift.staleCount > 0)
+        parts.push(`${drift.staleCount} stale`);
+    if (drift.neverSyncedCount > 0)
+        parts.push(`${drift.neverSyncedCount} never-synced`);
+    if (drift.unwiredHookVersions > 0)
+        parts.push(`${drift.unwiredHookVersions} with unwired hooks`);
+    if (drift.sourceBehind.length > 0)
+        parts.push(`${drift.sourceBehind.length} source layer(s) behind origin`);
+    console.error(`${chalk.red('drift')}  ${parts.join(', ')}`);
+    if (!opts.quiet) {
+        for (const row of drift.syncRows) {
+            const unwired = (row.unwiredHooks ?? 0) > 0;
+            if (row.status === 'fresh' && !unwired)
+                continue;
+            const tag = row.status === 'stale' ? chalk.yellow('stale')
+                : row.status === 'never-synced' ? chalk.gray('cold ')
+                    : chalk.red('unwired'); // fresh but hooks not wired into settings.json
+            console.error(`  ${tag}  ${checkLabel(row)}`);
+            for (const line of row.divergence ?? []) {
+                console.error(chalk.gray(`           ${line}`));
+            }
+        }
+        for (const b of drift.sourceBehind) {
+            console.error(`  ${chalk.red('behind')} source ${b.label}  ${chalk.gray(`${b.behind} commit${b.behind === 1 ? '' : 's'} behind ${b.branch}`)}`);
+        }
+        const hints = [];
+        if (drift.staleCount > 0 || drift.neverSyncedCount > 0 || drift.unwiredHookVersions > 0) {
+            hints.push('`agents doctor --fix` (or `agents doctor <agent>@<version> --fix`)');
+        }
+        if (drift.sourceBehind.length > 0)
+            hints.push('`agents repo pull <alias>` for a source layer behind origin');
+        console.error(chalk.gray(`\nReconcile with ${hints.join('; ')}.`));
+    }
+    process.exit(1);
+}
+function checkPayload(device, drift) {
+    return {
+        device,
+        hasDrift: drift.hasDrift,
+        stale: drift.staleCount,
+        neverSynced: drift.neverSyncedCount,
+        orphanVersions: drift.orphanVersionCount,
+    };
+}
+async function probeDeviceCheck(target) {
+    const isWin = /^win/i.test((target.platform ?? '').trim());
+    const remoteCmd = buildRemoteAgentsInvocation(['doctor', '--check', '--json'], undefined, isWin ? 'windows' : undefined, isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
+    const res = await sshExecAsync(target.dialTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0 && !res.stdout.trim()) {
+        throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
+    }
+    try {
+        const parsed = JSON.parse(res.stdout);
+        return {
+            device: target.name,
+            hasDrift: Boolean(parsed.hasDrift),
+            stale: parsed.stale ?? 0,
+            neverSynced: parsed.neverSynced ?? 0,
+            orphanVersions: parsed.orphanVersions ?? 0,
+        };
+    }
+    catch (err) {
+        throw new Error(`invalid JSON (${err?.message ?? 'parse error'})`);
+    }
+}
+async function runDevicesCheck(opts, cwd) {
+    const registry = await loadDevices();
+    const self = machineId();
+    const planned = planFleetTargets(registry);
+    const local = checkPayload(self, computeDrift(cwd));
+    const remoteTargets = remoteFleetTargets(planned, self)
+        .map((t) => ({
+        name: t.device.name,
+        platform: t.device.platform,
+        skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
+    }));
+    const remote = await fanOutDevices(remoteTargets, probeDeviceCheck);
+    const devices = [local];
+    for (const result of remote) {
+        if (result.status === 'ok' && result.value) {
+            devices.push(result.value);
+        }
+        else {
+            devices.push({
+                device: result.name,
+                hasDrift: true,
+                stale: 0,
+                neverSynced: 0,
+                orphanVersions: 0,
+                error: result.error ?? String(result.reason ?? 'skipped'),
+            });
+        }
+    }
+    const hasDrift = devices.some((d) => d.hasDrift || d.error);
+    if (opts.json) {
+        console.log(JSON.stringify({ hasDrift, devices }, null, 2));
+        process.exit(hasDrift ? 1 : 0);
+    }
+    if (!hasDrift) {
+        console.log(chalk.green('ok') + chalk.gray(`  ${devices.length} device(s) in sync`));
+        process.exit(0);
+    }
+    console.error(chalk.red('drift') + chalk.gray(`  ${devices.filter((d) => d.hasDrift || d.error).length} of ${devices.length} device(s)`));
+    if (!opts.quiet) {
+        for (const d of devices) {
+            if (!d.hasDrift && !d.error)
+                continue;
+            const detail = d.error
+                ? d.error
+                : [`${d.stale} stale`, `${d.neverSynced} never-synced`].filter((p) => !p.startsWith('0 ')).join(', ');
+            console.error(`  ${chalk.yellow(d.device.padEnd(18))} ${detail || 'drift'}`);
+        }
+        console.error(chalk.gray('\nReconcile each device with `agents doctor --fix` or `agents repo pull user`.'));
+    }
+    process.exit(1);
 }
 // ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
@@ -762,7 +1266,9 @@ export function registerDoctorCommand(program) {
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
         .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted')
         .option('--devices', 'Check agent readiness AND cross-device harness divergence (missing resources/versions, repo drift) on every registered device (alias --hosts)')
-        .option('--hosts', 'Alias of --devices');
+        .option('--hosts', 'Alias of --devices')
+        .option('--check', 'CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean. Combine with --devices to gate the whole fleet.')
+        .option('-q, --quiet', 'With --check, suppress per-version lines; print only the one-line verdict');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
@@ -772,7 +1278,7 @@ export function registerDoctorCommand(program) {
       agents doctor claude@default
 
       # All installed versions of one agent
-      agents doctor gemini
+      agents doctor antigravity
 
       # Pin to a specific installed version
       agents doctor codex@0.117.0
@@ -789,10 +1295,33 @@ export function registerDoctorCommand(program) {
       # Fleet: agent readiness + cross-device divergence (missing plugins/skills,
       # agent-version gaps, .agents/.system repo drift) vs this machine
       agents doctor --devices
+
+      # CI drift gate: exit 1 if anything drifted (stale/never-synced), 0 if clean
+      agents doctor --check
+      agents doctor --check --quiet          # just the verdict line
+      agents doctor --check --json           # machine-readable, for scripting
+      agents doctor --check --devices        # gate every registered device
+      agents doctor --check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }
     `,
     });
     doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        // CI drift gate. Kept BEFORE the --devices branch so `doctor --check
+        // --devices` routes to the drift gate fan-out (runDevicesCheck), while a
+        // bare `doctor --devices` still routes to the readiness matrix below.
+        if (opts.check) {
+            if (target) {
+                console.error(chalk.red('Cannot combine --check with a target argument.'));
+                process.exit(1);
+            }
+            if (opts.devices || opts.hosts) {
+                await runDevicesCheck(opts, cwd);
+            }
+            else {
+                runCheckGate(opts, cwd);
+            }
+            return;
+        }
         if (opts.devices || opts.hosts) {
             if (target) {
                 console.error(chalk.red('Cannot combine --devices with a target argument.'));
@@ -901,6 +1430,10 @@ export function registerDoctorCommand(program) {
                     auth: summarizeHostAuth(readAuthHealthCache(), machineId()),
                     sync: syncRows,
                     orphans: orphanRows,
+                    // Triaged overview health — severity/category/subject/impact/fix per
+                    // finding, aggregated across versions. Additive; existing consumers
+                    // reading `sync`/`orphans`/`repos` are unaffected.
+                    health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers),
                     // This host's harness inventory — installed resources per kind,
                     // installed version ids per agent, and `.agents`/`.system` repo
                     // state — so `agents doctor --devices` can compare presence across
@@ -932,7 +1465,8 @@ export function registerDoctorCommand(program) {
             // Point at the interactive reconcile when anything is out of sync — the
             // report shouldn't be a dead end. `agents status` runs the unified
             // home-reading engine and offers to sync (opt-in, never auto-fires here).
-            if (syncRows.some((r) => r.status !== 'fresh')) {
+            // Unwired hooks and a behind-origin repo count as out-of-sync too.
+            if (syncRows.some((r) => r.status !== 'fresh' || (r.unwiredHooks ?? 0) > 0) || repoBehindMarkers.some((m) => m.behind > 0)) {
                 console.log(chalk.gray('\nRun `agents status` to review and sync what has drifted.'));
             }
             return;
@@ -948,8 +1482,18 @@ export function registerDoctorCommand(program) {
             process.exit(1);
         }
         const reports = parsed.versions.map((v) => diffVersionResources(parsed.agent, v, { cwd, kinds }));
+        // Source-layer staleness is global (same across versions) and needs a git
+        // probe kept out of the pure diff — compute once, attach to every report so
+        // both --json and the text verdict carry it.
+        const sourceBehind = computeSourceBehind();
+        for (const r of reports)
+            r.sourceBehind = sourceBehind;
         if (opts.json) {
-            console.log(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
+            // Carry the triaged verdict (severity/category/subject/impact/fix per
+            // issue) alongside the report — additive, so existing consumers reading
+            // `summary`/`kinds`/`hookWiring`/`sourceBehind` are unaffected.
+            const withVerdict = reports.map((r) => ({ ...r, verdict: computeVerdict(r) }));
+            console.log(JSON.stringify(withVerdict.length === 1 ? withVerdict[0] : withVerdict, null, 2));
             return;
         }
         const showDiff = !!opts.diff;