@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/daemon.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { getDaemonDir as getDaemonDirRoot } from './state.js';
-import { isAlive, killTree } from './platform/index.js';
+import { isAlive, killTree, backgroundSpawnOptions } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -127,6 +127,86 @@ export function isDaemonRunning() {
     removeDaemonPid();
     return false;
 }
+/**
+ * Single-instance claim for the daemon `_run` entrypoint.
+ *
+ * `agents daemon _run` is reachable directly — a manual invocation, or a
+ * service-manager restart that races a still-alive predecessor — bypassing the
+ * start lock in startDaemon(). Without this guard runDaemon() would call
+ * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
+ * run a second JobScheduler concurrently, so every cron routine fires twice.
+ *
+ * Returns true and records our PID when no other live daemon owns the pid file;
+ * returns false when a live daemon already holds it (the caller must exit
+ * without touching any further state). The read-decide-write is serialized
+ * behind the same O_EXCL start lock startDaemon() uses, so two _run processes
+ * can't both claim in the window between the liveness check and the write.
+ */
+export function claimDaemonInstance() {
+    const release = acquireStartLock();
+    try {
+        const existing = readDaemonPid();
+        if (existing !== null && existing !== process.pid && isAlive(existing)) {
+            return false; // another live daemon already owns the pid file
+        }
+        writeDaemonPid(process.pid);
+        return true;
+    }
+    finally {
+        release?.();
+    }
+}
+/**
+ * Reap stray duplicate daemon processes — a `daemon _run` of THIS install that
+ * isn't this process and isn't the pid-file owner. Mirrors the browser orphan
+ * reaper (below): a predecessor that was SIGKILLed/OOM-ed without cleaning up,
+ * or a duplicate that lost the pid-file write race, would otherwise keep a
+ * second scheduler alive and double-fire jobs even after claimDaemonInstance()
+ * hands the pid file to the survivor.
+ *
+ * Scoped to our own launch entry (process.argv[1]) so it only ever targets
+ * daemons of the same installation — a daemon from a different install / home
+ * (e.g. a side-by-side dev build, or a test fixture) is a legitimately separate
+ * instance and is left untouched. POSIX-only (uses `ps`); a no-op on Windows.
+ */
+export function reapStrayDaemons(keepPid = process.pid) {
+    const details = [];
+    let reaped = 0;
+    if (process.platform === 'win32')
+        return { reaped, details };
+    const selfEntry = process.argv[1];
+    if (!selfEntry)
+        return { reaped, details };
+    let out;
+    try {
+        out = execFileSync('ps', ['-eo', 'pid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return { reaped, details }; // no `ps` — best effort
+    }
+    const ownerPid = readDaemonPid();
+    for (const line of out.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const args = m[2];
+        if (isNaN(pid) || pid === keepPid || pid === process.pid || pid === ownerPid)
+            continue;
+        // Same install (same launch entry) AND a `daemon _run` command line.
+        if (!args.includes(selfEntry))
+            continue;
+        if (!/\bdaemon\b.*\b_run\b/.test(args))
+            continue;
+        try {
+            process.kill(pid, 'SIGTERM');
+            reaped++;
+            details.push(`reaped stray daemon pid ${pid}`);
+        }
+        catch { /* already gone */ }
+    }
+    return { reaped, details };
+}
 /** Redact values that look like tokens or credentials in a log message. */
 function redactSecrets(message) {
     let safe = message;
@@ -165,8 +245,30 @@ export function log(level, message) {
 }
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export async function runDaemon() {
-    writeDaemonPid(process.pid);
+    // Single-instance guard: a direct `agents daemon _run` (manual, or a
+    // service-manager restart racing a live predecessor) must not clobber a
+    // running daemon's pid file and start a second scheduler.
+    if (!claimDaemonInstance()) {
+        const owner = readDaemonPid();
+        log('WARN', `Another daemon already owns the pid file (PID: ${owner}); this instance (PID ${process.pid}) is exiting`);
+        // Exit cleanly (0) so a service manager treats it as an orderly no-op
+        // rather than a failure to restart-flap on.
+        process.exit(0);
+    }
     log('INFO', `Daemon started (PID: ${process.pid})`);
+    // Reap any stray duplicate daemon of this install that slipped past the start
+    // lock or was orphaned by a hard-crash — before it can double-fire jobs.
+    try {
+        const strays = reapStrayDaemons();
+        if (strays.reaped > 0) {
+            log('WARN', `Reaped ${strays.reaped} stray daemon process(es)`);
+            for (const d of strays.details)
+                log('WARN', `  ${d}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Stray daemon reaper failed: ${err.message}`);
+    }
     const scheduler = new JobScheduler(async (config) => {
         log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
         try {
@@ -241,8 +343,10 @@ export async function runDaemon() {
             return;
         syncing = true;
         try {
-            const { isSyncConfigured } = await import('./session/sync/config.js');
-            if (!isSyncConfigured())
+            const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
+            // isSyncEnabled() first: a machine the operator turned off must skip the
+            // keychain read entirely, not just the network cycle.
+            if (!isSyncEnabled() || !isSyncConfigured())
                 return;
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();
@@ -373,6 +477,23 @@ function xmlEscape(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
+/**
+ * Write a launchd plist or systemd unit with owner-only permissions atomically.
+ *
+ * `writeFileSync`'s `mode` is honored only when the file is *created*, so we
+ * unlink any pre-existing manifest first. That guarantees every write is a
+ * fresh 0600 create — closing the TOCTOU window on new files AND re-locking a
+ * stale world-readable manifest left by an older install — since these files
+ * embed long-lived credentials.
+ */
+export function writeOwnerOnlyServiceManifest(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.rmSync(filePath, { force: true });
+    fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
+}
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist() {
     const agentsBin = getAgentsBinPath();
@@ -448,6 +569,31 @@ function getAgentsBinPath() {
         return 'agents';
     }
 }
+/**
+ * Ask the service manager for the daemon's live PID. Used as a fallback when
+ * the daemon hasn't yet written its pid file but launchd/systemd already report
+ * it running — so a start never has to surface a null PID for a daemon that is
+ * in fact up. Returns null when the service isn't running or the query fails.
+ */
+function readServiceManagerPid(platform = os.platform()) {
+    try {
+        if (platform === 'linux') {
+            const out = execFileSync('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', SYSTEMD_UNIT], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            const pid = parseInt(out, 10);
+            return !isNaN(pid) && pid > 0 ? pid : null;
+        }
+        if (platform === 'darwin') {
+            const out = execFileSync('launchctl', ['list', PLIST_NAME], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+            const m = out.match(/"PID"\s*=\s*(\d+)/);
+            if (m) {
+                const pid = parseInt(m[1], 10);
+                return pid > 0 ? pid : null;
+            }
+        }
+    }
+    catch { /* not running / manager unavailable */ }
+    return null;
+}
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon() {
     if (isDaemonRunning()) {
@@ -467,6 +613,24 @@ export function startDaemon() {
         releaseLock();
     }
 }
+/**
+ * Bring the always-on daemon up as a side effect of a background-adjacent
+ * command (secrets unlock, browser start, ...), not only from `routines add`.
+ *
+ * Delegates to the single `startDaemon` entrypoint, so it honors the
+ * single-instance start lock and is a no-op when a daemon is already running
+ * (returns `already-running`). Best-effort: any failure is swallowed and null
+ * returned, so ensuring the daemon can never break the foreground command that
+ * happened to bring it up. See issue #415.
+ */
+export function ensureDaemonStarted() {
+    try {
+        return startDaemon();
+    }
+    catch {
+        return null;
+    }
+}
 function startDaemonLocked() {
     const platform = os.platform();
     if (platform === 'darwin') {
@@ -476,10 +640,9 @@ function startDaemonLocked() {
             if (!fs.existsSync(plistDir)) {
                 fs.mkdirSync(plistDir, { recursive: true });
             }
-            fs.writeFileSync(plistPath, generateLaunchdPlist(), 'utf-8');
             // The plist may embed a long-lived OAuth token in EnvironmentVariables;
-            // keep it owner-only so it isn't world/group readable on disk.
-            fs.chmodSync(plistPath, 0o600);
+            // create owner-only atomically (no world-readable window before chmod).
+            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist());
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -489,7 +652,7 @@ function startDaemonLocked() {
             // of success. If no pid materializes within the window, give up on
             // launchd and fall through to a plain detached spawn.
             execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-            const pid = waitForPid(3000);
+            const pid = waitForPid(3000) ?? readServiceManagerPid();
             if (pid)
                 return { pid, method: 'launchd' };
             // launchctl claimed success but nothing ran. Fall through.
@@ -506,18 +669,21 @@ function startDaemonLocked() {
             if (!fs.existsSync(unitDir)) {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
-            fs.writeFileSync(unitPath, generateSystemdUnit(), 'utf-8');
             // May embed a long-lived OAuth token in an Environment= line; owner-only.
-            fs.chmodSync(unitPath, 0o600);
+            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit());
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
-            const pid = waitForPid(3000);
-            return { pid, method: 'systemd' };
+            const pid = waitForPid(3000) ?? readServiceManagerPid();
+            if (pid)
+                return { pid, method: 'systemd' };
+            // systemctl returned success but no PID surfaced — fall through to a
+            // plain detached spawn rather than reporting a null PID.
         }
         catch {
-            return startDetached();
+            // start threw — fall through to detached spawn
         }
+        return startDetached();
     }
     return startDetached();
 }
@@ -567,17 +733,29 @@ export function startDetached(opts = {}) {
     const logPath = opts.logPath ?? getLogPath();
     const logFd = fs.openSync(logPath, 'a');
     const { command, args } = getDaemonLaunch(agentsBin);
+    // fdStdio: the log-file fds make windowsHide inert (libuv skips
+    // CREATE_NO_WINDOW when a stdio fd is inherited), so on Windows the daemon
+    // must DETACH to own no console — otherwise it shares the launcher's console
+    // and a console-close event tears it down when the launcher exits (#556).
     const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
-        detached: true,
-        // No console window on Windows — a hidden, consoleless process can't be
-        // torn down by a console-close event when its launcher exits (#556).
-        windowsHide: true,
+        ...backgroundSpawnOptions({ fdStdio: true }),
         env: opts.env ?? buildDetachedDaemonEnv(),
     });
+    // A failed spawn (ENOENT/EACCES) emits 'error' asynchronously; without a
+    // listener that would crash the parent as an unhandled EventEmitter error.
+    // The synchronous `!child.pid` guard below is what reports the failure loudly.
+    child.on('error', () => { });
     child.unref();
     fs.closeSync(logFd);
-    return { pid: child.pid || null, method: 'detached' };
+    // `spawn` leaves `pid` undefined only when the process could not be created.
+    // Returning null here (the old `child.pid || null`) let callers report
+    // "PID: null" as if the daemon had started — a start with no PID is a failed
+    // start, so fail loudly instead of manufacturing a phantom success.
+    if (!child.pid) {
+        throw new Error(`Failed to start daemon: spawning '${command}' produced no PID (binary missing or not executable?)`);
+    }
+    return { pid: child.pid, method: 'detached' };
 }
 function waitForPid(timeoutMs) {
     const start = Date.now();

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

@@ -58,6 +58,13 @@ export declare function shellForPlatform(platform: DevicePlatform): DeviceShell;
  * returning {} would let the next write wipe the user's device list.
  */
 export declare function loadDevices(): Promise<DeviceRegistry>;
+/**
+ * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
+ * `agents sessions --host` fan-out builds its ssh command strings synchronously
+ * and only needs the target's platform to pick POSIX vs PowerShell). Same
+ * missing-file/corruption contract as {@link loadDevices}.
+ */
+export declare function loadDevicesSync(): DeviceRegistry;
 /** Get a single device profile, or null if it is not registered. */
 export declare function getDevice(name: string): Promise<DeviceProfile | null>;
 /** Fields a caller may supply when creating or updating a device. */

package/dist/lib/devices/registry.js

@@ -117,6 +117,30 @@ export async function loadDevices() {
         throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
     }
 }
+/**
+ * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
+ * `agents sessions --host` fan-out builds its ssh command strings synchronously
+ * and only needs the target's platform to pick POSIX vs PowerShell). Same
+ * missing-file/corruption contract as {@link loadDevices}.
+ */
+export function loadDevicesSync() {
+    const p = registryPath();
+    let raw;
+    try {
+        raw = fsSync.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
 async function saveDevices(reg) {
     await atomicWriteJson(registryPath(), reg);
 }

package/dist/lib/devices/resolve-target.d.ts

@@ -0,0 +1,24 @@
+import { type DeviceRegistry } from './registry.js';
+/** A dialable peer: the ssh target, the machine id used to tag its rows, a
+ * display name, and the OS family that picks the remote shell dialect. */
+export interface ResolvedSshTarget {
+    target: string;
+    machine: string;
+    name: string;
+    os?: string;
+}
+/**
+ * Resolve one `--host`/`--device` token to a concrete ssh target through the
+ * registry. Registry hit → the device's real address + platform (so the machine
+ * id, route, and OS all match the auto-discovery sweep). Miss → a literal
+ * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
+ * undefined only when the token fails the shared ssh-target injection guard.
+ */
+export declare function resolveSshTarget(token: string, reg: DeviceRegistry): ResolvedSshTarget | undefined;
+/**
+ * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
+ * registry once. A token that fails the injection guard is skipped with a
+ * stderr note (never fatal — one bad token must not blank the fan-out). Shared
+ * by every cross-machine fan-out so they can never diverge onto two routes.
+ */
+export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;

package/dist/lib/devices/resolve-target.js

@@ -0,0 +1,80 @@
+/**
+ * The one place a `--host` / `--device` token becomes a real ssh target.
+ *
+ * A device and a host are the same thing addressed two ways, so resolution must
+ * go through the device registry — the single source of truth. A token that
+ * names a registered device dials that device's real address (its Tailscale
+ * dnsName/ip + user, via `sshTargetFor`), *identical* to the auto-discovery
+ * sweep and `agents ssh`. Before this module, the explicit `--host` fan-out
+ * instead passed the bare token straight to `ssh`, so `--host yosemite-s0`
+ * dialed whatever `~/.ssh/config`/LAN DNS resolved `yosemite-s0` to — a
+ * different route than the sweep's `yosemite-s0.<tailnet>.ts.net`. That
+ * divergence broke ControlMaster socket reuse (different target → different
+ * `%C` hash → a cold dial every time) and could read a perfectly reachable box
+ * as "unreachable" when only the non-Tailscale route was down.
+ *
+ * A raw `user@host` that matches no registered device falls back to a literal
+ * target so ad-hoc boxes still work.
+ */
+import chalk from 'chalk';
+import { assertValidSshTarget } from '../ssh-exec.js';
+import { normalizeHost } from '../machine-id.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { sshTargetFor } from './connect.js';
+import { loadDevices } from './registry.js';
+/**
+ * Resolve one `--host`/`--device` token to a concrete ssh target through the
+ * registry. Registry hit → the device's real address + platform (so the machine
+ * id, route, and OS all match the auto-discovery sweep). Miss → a literal
+ * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
+ * undefined only when the token fails the shared ssh-target injection guard.
+ */
+export function resolveSshTarget(token, reg) {
+    try {
+        assertValidSshTarget(token);
+    }
+    catch {
+        return undefined;
+    }
+    const bare = token.split('@').pop() || token;
+    // An explicit `user@host` names an exact account/target — honour it literally.
+    // A bare alias (`yosemite-s0`) resolves through the registry to the device's
+    // real address, so it never diverges from the auto-discovery sweep.
+    const device = token.includes('@')
+        ? undefined
+        : reg[token] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(bare));
+    if (device) {
+        try {
+            return { target: sshTargetFor(device), machine: normalizeHost(device.name), name: device.name, os: device.platform };
+        }
+        catch {
+            // Registered but has no address to dial — fall through to the literal token.
+        }
+    }
+    return { target: token, machine: normalizeHost(bare), name: token, os: resolveRemoteOsSync(token) };
+}
+/**
+ * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
+ * registry once. A token that fails the injection guard is skipped with a
+ * stderr note (never fatal — one bad token must not blank the fan-out). Shared
+ * by every cross-machine fan-out so they can never diverge onto two routes.
+ */
+export async function resolveExplicitTargets(hosts) {
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        reg = {};
+    }
+    const out = [];
+    for (const h of hosts) {
+        const resolved = resolveSshTarget(h, reg);
+        if (!resolved) {
+            process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
+            continue;
+        }
+        out.push(resolved);
+    }
+    return out;
+}

package/dist/lib/devices/tailscale.js

@@ -115,7 +115,7 @@ export function nodeToDeviceInput(node) {
  * error when the binary is missing or the daemon is not reachable.
  */
 export function tailscaleStatusJson() {
-    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8' });
+    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8', windowsHide: true });
     if (res.error && res.error.code === 'ENOENT') {
         throw new Error('tailscale not found on PATH. Install Tailscale, or add devices manually with `agents devices add`.');
     }

package/dist/lib/drift.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared drift-detection internals for `agents doctor` (overview mode) and
+ * `agents 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`.
+ */
+import type { AgentId } from './types.js';
+import { type VersionResourceReport } 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). */
+    divergence?: string[];
+}
+export interface OrphanRow {
+    agent: AgentId;
+    version: string;
+    commands: number;
+    skills: number;
+    hooks: number;
+}
+export declare function divergenceLines(report: VersionResourceReport): string[];
+export declare function checkSyncStatus(cwd: string): SyncStatusRow[];
+export declare function countOrphans(): OrphanRow[];
+export interface DriftSummary {
+    syncRows: SyncStatusRow[];
+    orphanRows: OrphanRow[];
+    /** Versions whose sources changed since last sync. */
+    staleCount: number;
+    /** Versions installed but never synced. */
+    neverSyncedCount: number;
+    /** Versions carrying orphan resources (informational — not a drift signal). */
+    orphanVersionCount: number;
+    /**
+     * 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).
+     */
+    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.
+ */
+export declare function computeDrift(cwd: string): DriftSummary;

package/dist/lib/drift.js

@@ -0,0 +1,112 @@
+import { ALL_AGENT_IDS } from './agents.js';
+import { getGlobalDefault, listInstalledVersions } from './versions.js';
+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';
+// 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 —
+// the system-repo plugin content that matters most). Other kinds collapse to
+// compact counts so the readout stays scannable.
+export function divergenceLines(report) {
+    const lines = [];
+    for (const p of report.kinds.plugins) {
+        if (p.status === 'missing')
+            lines.push(`plugin ${p.name} — not installed`);
+        else if (p.status === 'diff')
+            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
+    }
+    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
+        const rows = report.kinds[kind];
+        const miss = rows.filter((r) => r.status === 'missing').length;
+        const dif = rows.filter((r) => r.status === 'diff').length;
+        const bits = [];
+        if (miss)
+            bits.push(`${miss} missing`);
+        if (dif)
+            bits.push(`${dif} drifted`);
+        if (bits.length)
+            lines.push(`${kind.padEnd(11)} ${bits.join(' · ')}`);
+    }
+    return lines;
+}
+export function checkSyncStatus(cwd) {
+    const rows = [];
+    // Every installed version, not just the default — a stale NON-default version
+    // (e.g. one you launched from yesterday) is exactly the rot that silently
+    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
+    // is why that class of bug went unnoticed.
+    for (const agent of ALL_AGENT_IDS) {
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const manifest = loadManifest(agent, version);
+            const status = !manifest
+                ? 'never-synced'
+                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
+            const row = { agent, version, status, isDefault: version === def };
+            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;
+            }
+            rows.push(row);
+        }
+    }
+    return rows;
+}
+export function countOrphans() {
+    const byKey = new Map();
+    const ensure = (agent, version) => {
+        const key = `${agent}@${version}`;
+        let row = byKey.get(key);
+        if (!row) {
+            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
+            byKey.set(key, row);
+        }
+        return row;
+    };
+    for (const { agent, version } of iterCommandsCapableVersions()) {
+        const diff = diffVersionCommands(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).commands = diff.orphans.length;
+    }
+    for (const { agent, version } of iterSkillsCapableVersions()) {
+        const diff = diffVersionSkills(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).skills = diff.orphans.length;
+    }
+    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
+    // entry registers — so the registrar never wires them to an event and they
+    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
+    // which false-flags valid system-sourced registered hooks.)
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const dead = listUnmanagedHooksInVersionHome(agent, version);
+        if (dead.length > 0)
+            ensure(agent, version).hooks = dead.length;
+    }
+    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+}
+/**
+ * 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.
+ */
+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;
+    return {
+        syncRows,
+        orphanRows,
+        staleCount,
+        neverSyncedCount,
+        orphanVersionCount: orphanRows.length,
+        hasDrift: syncRows.some((r) => r.status !== 'fresh'),
+    };
+}

package/dist/lib/events.d.ts

@@ -177,4 +177,4 @@ export declare function getTimingStats(label: string, options?: {
     p50Ms: number;
     p95Ms: number;
 } | null;
-export declare const LOGS_PATH: string;
+export declare function getLogsPath(): string;