@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/devices/fleet-divergence.js

@@ -0,0 +1,188 @@
+/**
+ * Cross-device harness divergence for `agents doctor` (RUSH-2027).
+ *
+ * `agents fleet status` already fans out `agents doctor --json` per device and
+ * builds a {@link FleetHealthReport} of coarse device health (reachable, CLIs
+ * installed, agents-cli version skew, local sync drift). It deliberately does
+ * NOT compare fine-grained *resource presence* across devices — so a plugin like
+ * `swarm` installed on one box but missing on another is silent until a user
+ * types `/swarm:run` on the wrong machine and gets `Unknown command`.
+ *
+ * This module is the missing comparison. Each device self-reports its installed
+ * inventory (resource kinds, per-agent version sets, `.agents`/`.system` repo
+ * state) in its `doctor --json` payload; {@link compareFleetInventories} takes
+ * the collected per-device inventories and, treating the local machine as the
+ * baseline, flags:
+ *
+ *   1. Resource presence gaps  — a resource present on one device, missing on
+ *      another (either direction relative to the local baseline).
+ *   2. Agent version gaps      — an agent version installed on one device but
+ *      not another (e.g. `yosemite-s0 missing claude@2.1.220`).
+ *   3. `.agents`/`.system` repo drift — a device whose config-repo HEAD, branch,
+ *      or dirty state diverges from the local baseline.
+ *
+ * Pure and SSH-free: the SSH fan-out lives in the doctor command; this module
+ * only consumes the already-collected payloads, so the divergence logic is
+ * unit-tested against fixture inventories with no live fleet.
+ */
+export const FLEET_RESOURCE_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+    'plugins',
+    'promptcuts',
+    'workflows',
+];
+function sortedUnique(list) {
+    return Array.from(new Set(list)).sort();
+}
+function repoLabel(repo) {
+    return repo === 'agents' ? '.agents' : '.system';
+}
+/** Describe how a remote repo state diverges from the local baseline, or null
+ *  when they match. Compares HEAD first (the load-bearing difference), then
+ *  branch, then a dirty tree on either side (naming which side is dirty). */
+function describeRepoDrift(local, remote) {
+    if (local.head && remote.head && local.head !== remote.head) {
+        return `HEAD ${remote.head} != local ${local.head}`;
+    }
+    if (local.branch !== remote.branch) {
+        return `branch ${remote.branch ?? 'detached'} != local ${local.branch ?? 'detached'}`;
+    }
+    // Flag a dirty tree on EITHER side (symmetric with HEAD/branch above), and name
+    // the side that has the uncommitted changes — the remote, or the local baseline.
+    if (remote.dirty !== local.dirty) {
+        return remote.dirty
+            ? 'remote tree has uncommitted changes'
+            : 'local tree has uncommitted changes';
+    }
+    return null;
+}
+/**
+ * Compare a set of per-device inventories against the local baseline and emit
+ * every cross-device divergence. The baseline is the device whose name equals
+ * {@link baselineName} (the local machine); if that device has no inventory the
+ * report is empty (nothing to compare against). Devices with no inventory are
+ * recorded under `skippedDevices` and never produce false "missing" findings.
+ *
+ * Ordering is deterministic (device, then category, then name) so the human and
+ * JSON output — and the tests — are stable.
+ */
+export function compareFleetInventories(devices, baselineName) {
+    const baseline = devices.find((d) => d.name === baselineName)?.inventory ?? null;
+    const remotes = devices.filter((d) => d.name !== baselineName);
+    const comparedDevices = [];
+    const skippedDevices = [];
+    const divergences = [];
+    if (!baseline) {
+        // No local baseline to compare against — record every remote as skipped so
+        // the caller can say so, but emit no divergences (we can't know the truth).
+        for (const d of remotes)
+            skippedDevices.push(d.name);
+        return {
+            baseline: baselineName,
+            divergences: [],
+            comparedDevices: [],
+            skippedDevices: skippedDevices.sort(),
+            hasDivergence: false,
+        };
+    }
+    for (const remote of remotes) {
+        if (!remote.inventory) {
+            skippedDevices.push(remote.name);
+            continue;
+        }
+        comparedDevices.push(remote.name);
+        const inv = remote.inventory;
+        // 1) Resource presence, both directions.
+        for (const kind of FLEET_RESOURCE_KINDS) {
+            const localSet = new Set(baseline.resources[kind] ?? []);
+            const remoteSet = new Set(inv.resources[kind] ?? []);
+            for (const name of sortedUnique(baseline.resources[kind] ?? [])) {
+                if (!remoteSet.has(name)) {
+                    divergences.push({
+                        kind: 'resource-missing-remote',
+                        device: remote.name,
+                        category: kind,
+                        name,
+                        message: `${remote.name} is missing ${kind.replace(/s$/, '')} '${name}' (present on ${baselineName})`,
+                    });
+                }
+            }
+            for (const name of sortedUnique(inv.resources[kind] ?? [])) {
+                if (!localSet.has(name)) {
+                    divergences.push({
+                        kind: 'resource-missing-local',
+                        device: remote.name,
+                        category: kind,
+                        name,
+                        message: `${baselineName} is missing ${kind.replace(/s$/, '')} '${name}' (present on ${remote.name})`,
+                    });
+                }
+            }
+        }
+        // 2) Agent version parity, both directions, per agent id.
+        const agentIds = sortedUnique([
+            ...Object.keys(baseline.agentVersions),
+            ...Object.keys(inv.agentVersions),
+        ]);
+        for (const agent of agentIds) {
+            const localVers = new Set(baseline.agentVersions[agent] ?? []);
+            const remoteVers = new Set(inv.agentVersions[agent] ?? []);
+            for (const v of sortedUnique(baseline.agentVersions[agent] ?? [])) {
+                if (!remoteVers.has(v)) {
+                    divergences.push({
+                        kind: 'agent-version-missing-remote',
+                        device: remote.name,
+                        category: agent,
+                        name: v,
+                        message: `${remote.name} is missing ${agent}@${v} (installed on ${baselineName})`,
+                    });
+                }
+            }
+            for (const v of sortedUnique(inv.agentVersions[agent] ?? [])) {
+                if (!localVers.has(v)) {
+                    divergences.push({
+                        kind: 'agent-version-missing-local',
+                        device: remote.name,
+                        category: agent,
+                        name: v,
+                        message: `${baselineName} is missing ${agent}@${v} (installed on ${remote.name})`,
+                    });
+                }
+            }
+        }
+        // 3) `.agents` / `.system` repo drift vs the local baseline.
+        for (const repo of ['agents', 'system']) {
+            const localRepo = baseline.repos[repo];
+            const remoteRepo = inv.repos[repo];
+            if (!localRepo || !remoteRepo)
+                continue; // one side isn't a readable repo
+            const drift = describeRepoDrift(localRepo, remoteRepo);
+            if (drift) {
+                divergences.push({
+                    kind: 'repo-drift',
+                    device: remote.name,
+                    category: repo,
+                    name: repoLabel(repo),
+                    message: `${remote.name} ${repoLabel(repo)} repo diverged: ${drift}`,
+                });
+            }
+        }
+    }
+    divergences.sort((a, b) => a.device.localeCompare(b.device) ||
+        a.kind.localeCompare(b.kind) ||
+        a.category.localeCompare(b.category) ||
+        a.name.localeCompare(b.name));
+    return {
+        baseline: baselineName,
+        divergences,
+        comparedDevices: comparedDevices.sort(),
+        skippedDevices: skippedDevices.sort(),
+        hasDivergence: divergences.length > 0,
+    };
+}

package/dist/lib/devices/fleet-inventory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build the self-reported harness inventory a device emits in `doctor --json`
+ * for cross-device divergence detection (RUSH-2027).
+ *
+ * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
+ * SSH-free comparator — because this reads the live install (resource dirs,
+ * installed version homes, config repos). One call produces the {@link
+ * FleetInventory} that both the local baseline and every remote box serialize
+ * into their doctor payload; the comparator then diffs those payloads.
+ */
+import { type FleetInventory } from './fleet-divergence.js';
+/**
+ * Collect this machine's harness inventory: installed resources per kind,
+ * installed version ids per agent, and `.agents`/`.system` repo state. Pure
+ * reads — never mutates the install. `promptcuts` (a single present/absent bit
+ * in {@link getAvailableResources}) is surfaced as a one-element list so it
+ * compares like any other named resource.
+ */
+export declare function collectLocalFleetInventory(cwd?: string): FleetInventory;

package/dist/lib/devices/fleet-inventory.js

@@ -0,0 +1,57 @@
+/**
+ * Build the self-reported harness inventory a device emits in `doctor --json`
+ * for cross-device divergence detection (RUSH-2027).
+ *
+ * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
+ * SSH-free comparator — because this reads the live install (resource dirs,
+ * installed version homes, config repos). One call produces the {@link
+ * FleetInventory} that both the local baseline and every remote box serialize
+ * into their doctor payload; the comparator then diffs those payloads.
+ */
+import { getAvailableResources, listInstalledVersions } from '../versions.js';
+import { getUserAgentsDir, getSystemAgentsDir } from '../state.js';
+import { readRepoState } from '../git.js';
+import { ALL_AGENT_IDS } from '../agents.js';
+import { FLEET_RESOURCE_KINDS } from './fleet-divergence.js';
+function toRepoState(snap) {
+    if (!snap)
+        return null;
+    return { branch: snap.branch, head: snap.head, dirty: snap.dirty };
+}
+/**
+ * Collect this machine's harness inventory: installed resources per kind,
+ * installed version ids per agent, and `.agents`/`.system` repo state. Pure
+ * reads — never mutates the install. `promptcuts` (a single present/absent bit
+ * in {@link getAvailableResources}) is surfaced as a one-element list so it
+ * compares like any other named resource.
+ */
+export function collectLocalFleetInventory(cwd = process.cwd()) {
+    const available = getAvailableResources(cwd);
+    const resources = {};
+    for (const kind of FLEET_RESOURCE_KINDS) {
+        if (kind === 'promptcuts') {
+            resources[kind] = available.promptcuts ? ['promptcuts.yaml'] : [];
+        }
+        else if (kind === 'rules') {
+            // getAvailableResources exposes top-level rules under `memory`.
+            resources[kind] = [...available.memory].sort();
+        }
+        else {
+            resources[kind] = [...(available[kind] ?? [])].sort();
+        }
+    }
+    const agentVersions = {};
+    for (const agent of ALL_AGENT_IDS) {
+        const versions = listInstalledVersions(agent);
+        if (versions.length > 0)
+            agentVersions[agent] = [...versions].sort();
+    }
+    return {
+        resources,
+        agentVersions,
+        repos: {
+            agents: toRepoState(readRepoState(getUserAgentsDir())),
+            system: toRepoState(readRepoState(getSystemAgentsDir())),
+        },
+    };
+}

package/dist/lib/devices/fleet.d.ts

@@ -48,7 +48,7 @@ export interface FanOutDeviceResult<T> {
 export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
 /**
  * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `check --devices`): every planned device except this machine and control-only
+ * `doctor --check --devices`): every planned device except this machine and control-only
  * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
  * drops it via `isControlDevice`), so counting it as unreachable/drift would make
  * the CI gate fail on every run for a fleet that merely has a cockpit registered.

package/dist/lib/devices/fleet.js

@@ -44,7 +44,7 @@ export function planFleetTargets(reg) {
 }
 /**
  * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `check --devices`): every planned device except this machine and control-only
+ * `doctor --check --devices`): every planned device except this machine and control-only
  * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
  * drops it via `isControlDevice`), so counting it as unreachable/drift would make
  * the CI gate fail on every run for a fleet that merely has a cockpit registered.

package/dist/lib/devices/health-report.d.ts

@@ -1,6 +1,7 @@
 import { type DeviceStats } from './health.js';
 import { type HostAuthSummary } from '../auth-health.js';
 import type { OnlineState } from './reachability.js';
+import { type FleetInventory } from './fleet-divergence.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -40,9 +41,14 @@ export interface FleetHealthRow {
      *  an offline row. Sourced from the registry's tailscale snapshot / reachability
      *  verdict. Undefined when never recorded. */
     lastSeen?: string;
+    /** This host's self-reported harness inventory (resources / agent versions /
+     *  repo state) from its `doctor --json` `fleet` field, for cross-device
+     *  divergence detection (RUSH-2027). Undefined for an unreachable box or an
+     *  older CLI that doesn't emit it. */
+    inventory?: FleetInventory;
 }
 export interface FleetWarning {
-    kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
+    kind: 'unreachable' | 'drift' | 'cli' | 'version-skew' | 'divergence';
     devices: string[];
     message: string;
 }
@@ -53,7 +59,9 @@ export interface FleetHealthReport {
     hasWarnings: boolean;
     hasDrift: boolean;
 }
-export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date): FleetHealthReport;
+export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date, opts?: {
+    self?: string;
+}): FleetHealthReport;
 export declare function renderFleetWarnings(report: FleetHealthReport): string[];
 export declare function renderFleetMatrix(report: FleetHealthReport): string[];
 /**

package/dist/lib/devices/health-report.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../session/width.js';
 import { fmtBytes, headroom } from './health.js';
 import { formatCheckedAge } from '../auth-health.js';
+import { compareFleetInventories } from './fleet-divergence.js';
 function driftRows(row) {
     return row.sync.filter((s) => s.status !== 'fresh');
 }
@@ -12,7 +13,7 @@ function installedCliCount(row) {
         total: statuses.length,
     };
 }
-export function buildFleetHealthReport(rows, now = new Date()) {
+export function buildFleetHealthReport(rows, now = new Date(), opts = {}) {
     const warnings = [];
     const unreachable = rows
         .filter((r) => r.error || r.skipped)
@@ -60,6 +61,25 @@ export function buildFleetHealthReport(rows, now = new Date()) {
             message: `agents-cli version skew: ${Array.from(versions.keys()).sort().join(', ')}`,
         });
     }
+    // Cross-device harness divergence (RUSH-2027): compare every device's
+    // self-reported inventory against the local baseline and roll the findings up
+    // into one warning per affected device. Only runs when a baseline (`self`) is
+    // named and at least one device carries an inventory — an older-CLI fleet with
+    // no `fleet` field simply produces no divergence warning.
+    if (opts.self && rows.some((r) => r.inventory)) {
+        const divergence = compareFleetInventories(rows.map((r) => ({ name: r.name, inventory: r.inventory ?? null })), opts.self);
+        const byDevice = new Map();
+        for (const d of divergence.divergences)
+            byDevice.set(d.device, (byDevice.get(d.device) ?? 0) + 1);
+        for (const device of Array.from(byDevice.keys()).sort()) {
+            const n = byDevice.get(device);
+            warnings.push({
+                kind: 'divergence',
+                devices: [device],
+                message: `${device} diverges from ${opts.self} (${n} resource/version/repo gap${n === 1 ? '' : 's'})`,
+            });
+        }
+    }
     return {
         generatedAt: now.toISOString(),
         devices: rows,
@@ -326,6 +346,17 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
             .join(' · ');
         items.push({ glyph: 'warn', subject: 'version skew', detail: summary, fix: 'agents upgrade --fleet' });
     }
+    // 4) Cross-device harness divergence — one item per diverged box (RUSH-2027).
+    for (const w of report.warnings) {
+        if (w.kind !== 'divergence')
+            continue;
+        items.push({
+            glyph: 'warn',
+            subject: w.devices[0] ?? 'fleet',
+            detail: w.message.replace(`${w.devices[0]} `, ''),
+            fix: `agents apply ${w.devices[0] ?? ''}`.trim(),
+        });
+    }
     return items;
 }
 /** Right-aligned `<content>` on the same line as `left`, clamped so it never

package/dist/lib/doctor-diff.d.ts

@@ -21,6 +21,7 @@
  */
 import type { AgentId } from './types.js';
 import type { DiscoveredPlugin } from './types.js';
+import { type HookWiringReport } from './hooks.js';
 export type DoctorKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'promptcuts';
 export type DiffStatus = 'ok' | 'diff' | 'missing' | 'extra';
 export type SourceLayer = 'project' | 'user' | 'system' | 'extra';
@@ -37,6 +38,19 @@ export interface ResourceDiff {
      *  "0.6.1→0.7.0, missing skills: ship, learn". Currently set for plugins. */
     detail?: string;
 }
+/** A source layer (user / system / an extra repo) that is behind its upstream —
+ *  reconciled against stale truth. Attached to the report by the doctor command
+ *  (needs a git probe, kept out of the pure per-version diff). */
+export interface SourceLayerBehind {
+    layer: 'user' | 'system' | 'extra';
+    /** Human label for the layer's on-disk root (e.g. `~/.agents`). */
+    label: string;
+    /** `agents repo pull` alias for the remediation hint. */
+    alias: string;
+    behind: number;
+    /** Upstream ref the layer trails (e.g. `origin/main`). */
+    branch: string;
+}
 export interface VersionResourceReport {
     agent: AgentId;
     version: string;
@@ -58,6 +72,12 @@ export interface VersionResourceReport {
         missing: number;
         extra: number;
     };
+    /** Wiring inspection for the version's native settings.json (claude/droid).
+     *  Populated only when the `hooks` kind is in scope. */
+    hookWiring?: HookWiringReport;
+    /** Source layers behind their upstream. Filled by the doctor command (a git
+     *  probe), not the pure diff — undefined when uncomputed. */
+    sourceBehind?: SourceLayerBehind[];
 }
 /**
  * Describe how a version's marketplace MIRROR of a plugin diverges from its

package/dist/lib/doctor-diff.js

@@ -33,7 +33,7 @@ import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } fr
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
-import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
+import { listHooksInVersionHome, listHookEntriesFromDir, checkVersionHookWiring } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
 const ALL_KINDS = [
     'commands',
@@ -611,6 +611,10 @@ export function diffVersionResources(agent, version, options = {}) {
         empty.skills = diffSkills(agent, version, cwd, excludeProject);
     if (requested.has('hooks'))
         empty.hooks = diffHooks(agent, version, cwd);
+    // Wiring check: a hook FILE can be present and byte-identical to source (ok
+    // above) yet never referenced in settings.json, so it never fires. Only
+    // meaningful when hooks are in scope.
+    const hookWiring = requested.has('hooks') ? checkVersionHookWiring(agent, version) : undefined;
     if (requested.has('rules'))
         empty.rules = diffRules(agent, version, cwd, excludeProject);
     if (requested.has('mcp'))
@@ -649,6 +653,7 @@ export function diffVersionResources(agent, version, options = {}) {
         },
         kinds: empty,
         summary: { ok, diff, missing, extra },
+        ...(hookWiring ? { hookWiring } : {}),
     };
 }
 export const DOCTOR_ALL_KINDS = ALL_KINDS;

package/dist/lib/drift.d.ts

@@ -1,21 +1,27 @@
 /**
  * Shared drift-detection internals for `agents doctor` (overview mode) and
- * `agents check` (the scriptable, CI-friendly gate).
+ * `agents doctor --check` (the scriptable, CI-friendly gate).
  *
  * This is the single source of truth for "is the install out of sync?": the
  * per-version sync status (fresh / stale / never-synced) and the orphan census.
- * `agents doctor` renders it as a human report; `agents check` reduces it to an
- * exit code. Neither reimplements the diagnostic — both call `computeDrift`.
+ * `agents doctor` renders it as a human report; `agents doctor --check` reduces it
+ * to an exit code. Neither reimplements the diagnostic — both call `computeDrift`.
  */
 import type { AgentId } from './types.js';
-import { type VersionResourceReport } from './doctor-diff.js';
+import { type VersionResourceReport, type SourceLayerBehind } from './doctor-diff.js';
 export interface SyncStatusRow {
     agent: AgentId;
     version: string;
     status: 'fresh' | 'stale' | 'never-synced';
     isDefault: boolean;
-    /** For stale rows: prioritized lines naming exactly what diverged (plugins first). */
+    /** For stale rows: prioritized lines naming exactly what diverged (plugins first).
+     *  Also carries hook-wiring divergence for a version whose hooks are present but
+     *  not wired into settings.json — independent of manifest staleness. */
     divergence?: string[];
+    /** Count of hooks present on disk but NOT wired into the version's settings.json
+     *  (claude/droid). A non-zero value makes the version out-of-sync even when the
+     *  manifest reads fresh — the yosemite-s1 blind spot the CI gate must catch. */
+    unwiredHooks?: number;
 }
 export interface OrphanRow {
     agent: AgentId;
@@ -27,6 +33,14 @@ export interface OrphanRow {
 export declare function divergenceLines(report: VersionResourceReport): string[];
 export declare function checkSyncStatus(cwd: string): SyncStatusRow[];
 export declare function countOrphans(): OrphanRow[];
+/**
+ * Probe each source layer (user, system, enabled extras) for how far it trails
+ * its upstream, from the LAST-FETCHED remote-tracking ref (no network). A layer
+ * behind origin means every version home is reconciled against stale truth — a
+ * drift signal `agents doctor --check` must fail on, not a buried preamble. Returns
+ * only the behind layers. Canonical home for both `agents doctor` and `agents doctor --check`.
+ */
+export declare function computeSourceBehind(): SourceLayerBehind[];
 export interface DriftSummary {
     syncRows: SyncStatusRow[];
     orphanRows: OrphanRow[];
@@ -36,17 +50,23 @@ export interface DriftSummary {
     neverSyncedCount: number;
     /** Versions carrying orphan resources (informational — not a drift signal). */
     orphanVersionCount: number;
+    /** Versions with hooks present on disk but not wired into settings.json. */
+    unwiredHookVersions: number;
+    /** Source layers behind their upstream (reconciled against stale truth). */
+    sourceBehind: SourceLayerBehind[];
     /**
-     * True when any installed version is stale or never-synced — the exact signal
-     * `agents doctor` surfaces as "run `agents status` to review what has drifted".
-     * Orphans are a `prune` concern, not sync drift, so they do NOT set this flag
-     * (mirrors the sync-status engine: an orphan alone never flags needsSync).
+     * True when the install is out of sync: any installed version is stale,
+     * never-synced, or carries unwired hooks, OR a source layer is behind origin.
+     * `agents doctor` surfaces it as "run `agents status`"; `agents doctor --check`
+     * maps it to a non-zero exit. Orphans are a `prune` concern, not sync drift, so they do
+     * NOT set this flag (mirrors the sync-status engine: an orphan alone never
+     * flags needsSync).
      */
     hasDrift: boolean;
 }
 /**
  * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
- * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
- * to an exit code; the readout `agents doctor` renders in full.
+ * to a summary with a single `hasDrift` boolean. The gate `agents doctor --check`
+ * maps to an exit code; the readout `agents doctor` renders in full.
  */
 export declare function computeDrift(cwd: string): DriftSummary;

package/dist/lib/drift.js

@@ -4,7 +4,9 @@ import { loadManifest, isStale } from './staleness/index.js';
 import { diffVersionResources } from './doctor-diff.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from './commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from './skills.js';
-import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from './hooks.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome, checkVersionHookWiring } from './hooks.js';
+import { commitsBehindUpstream } from './git.js';
+import { getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos } from './state.js';
 // Lines naming exactly what's out of sync for a version, plugins prioritized:
 // each divergent plugin gets its own line with specifics (stale mirror version,
 // invalid manifest, or the bundled skills/commands missing from the mirror —
@@ -46,14 +48,37 @@ export function checkSyncStatus(cwd) {
                 ? 'never-synced'
                 : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
             const row = { agent, version, status, isDefault: version === def };
+            const divergence = [];
             if (status === 'stale') {
                 // Resolve the specifics against non-project layers (the global home is
                 // never reconciled against per-cwd project resources).
                 const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
-                const lines = divergenceLines(report);
-                if (lines.length)
-                    row.divergence = lines;
+                divergence.push(...divergenceLines(report));
             }
+            // Hook WIRING is independent of manifest staleness: a hook file can be
+            // byte-identical to source (fresh) yet absent from settings.json, so it
+            // never fires. Surface that for every version, fresh or stale, so overview
+            // AND `agents doctor --check` flag it (claude/droid; other agents report unsupported).
+            const wiring = checkVersionHookWiring(agent, version);
+            if (wiring.supported) {
+                const expected = wiring.expected ?? 0;
+                if (wiring.settingsMissing && expected > 0) {
+                    row.unwiredHooks = expected;
+                    divergence.push(`hooks       settings.json missing — ${expected} declared hook(s) never fire`);
+                }
+                else if (wiring.settingsUnparseable) {
+                    row.unwiredHooks = Math.max(1, expected);
+                    divergence.push(`hooks       settings.json unparseable — wiring cannot be verified`);
+                }
+                else if (wiring.unwired.length > 0) {
+                    row.unwiredHooks = wiring.unwired.length;
+                    const names = wiring.unwired.map((u) => u.name);
+                    const shown = names.slice(0, 3).join(', ');
+                    divergence.push(`hooks       ${wiring.unwired.length} unwired (${shown}${names.length > 3 ? ', …' : ''})`);
+                }
+            }
+            if (divergence.length)
+                row.divergence = divergence;
             rows.push(row);
         }
     }
@@ -91,22 +116,48 @@ export function countOrphans() {
     }
     return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
 }
+/**
+ * Probe each source layer (user, system, enabled extras) for how far it trails
+ * its upstream, from the LAST-FETCHED remote-tracking ref (no network). A layer
+ * behind origin means every version home is reconciled against stale truth — a
+ * drift signal `agents doctor --check` must fail on, not a buried preamble. Returns
+ * only the behind layers. Canonical home for both `agents doctor` and `agents doctor --check`.
+ */
+export function computeSourceBehind() {
+    const out = [];
+    const probe = (layer, dir, label, alias) => {
+        const r = commitsBehindUpstream(dir);
+        if (r && r.behind > 0)
+            out.push({ layer, label, alias, behind: r.behind, branch: r.branch });
+    };
+    probe('user', getUserAgentsDir(), '~/.agents', 'user');
+    probe('system', getSystemAgentsDir(), '~/.agents/.system', 'system');
+    for (const e of getEnabledExtraRepos())
+        probe('extra', e.dir, e.alias, e.alias);
+    return out;
+}
 /**
  * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
- * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
- * to an exit code; the readout `agents doctor` renders in full.
+ * to a summary with a single `hasDrift` boolean. The gate `agents doctor --check`
+ * maps to an exit code; the readout `agents doctor` renders in full.
  */
 export function computeDrift(cwd) {
     const syncRows = checkSyncStatus(cwd);
     const orphanRows = countOrphans();
     const staleCount = syncRows.filter((r) => r.status === 'stale').length;
     const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
+    const unwiredHookVersions = syncRows.filter((r) => (r.unwiredHooks ?? 0) > 0).length;
+    const sourceBehind = computeSourceBehind();
     return {
         syncRows,
         orphanRows,
         staleCount,
         neverSyncedCount,
         orphanVersionCount: orphanRows.length,
-        hasDrift: syncRows.some((r) => r.status !== 'fresh'),
+        unwiredHookVersions,
+        sourceBehind,
+        hasDrift: syncRows.some((r) => r.status !== 'fresh') ||
+            unwiredHookVersions > 0 ||
+            sourceBehind.length > 0,
     };
 }