@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/daemon.d.ts

@@ -14,6 +14,39 @@ export declare function writeDaemonPid(pid: number): void;
 export declare function removeDaemonPid(): void;
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
+/**
+ * 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 declare function claimDaemonInstance(): boolean;
+/**
+ * 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 declare function reapStrayDaemons(keepPid?: number): {
+    reaped: number;
+    details: string[];
+};
 /** Append a JSONL log entry to the daemon log file (owner-only permissions). */
 export declare function log(level: string, message: string): void;
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
@@ -28,6 +61,16 @@ export declare function runDaemon(): Promise<void>;
  * session). Never throws: a misconfigured token must not block daemon startup.
  */
 export declare function readDaemonClaudeOAuthToken(): string | null;
+/**
+ * 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 declare function writeOwnerOnlyServiceManifest(filePath: string, content: string): void;
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export declare function generateLaunchdPlist(): string;
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
@@ -37,6 +80,20 @@ export declare function startDaemon(): {
     pid: number | null;
     method: string;
 };
+/**
+ * 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 declare function ensureDaemonStarted(): {
+    pid: number | null;
+    method: string;
+} | null;
 /**
  * Environment for the detached daemon fallback. The launchd/systemd paths
  * deliver the long-lived OAuth token via the service manifest's environment;
@@ -46,6 +103,40 @@ export declare function startDaemon(): {
  * value (e.g. inherited from launchd) is left untouched.
  */
 export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
+ * exact form that works under a direct `daemon _run`.
+ *
+ * We spawn the Node runtime (`process.execPath`) with the CLI entry as an
+ * argument rather than executing the entry path directly. Executing the `.js`
+ * path relies on its shebang on POSIX, and on Windows CreateProcess can't run a
+ * `.js`/shim directly at all — it gets launched through a transient
+ * console-owning wrapper (cmd.exe / the npm shim). When that wrapper exits it
+ * closes its console, and the detached daemon sharing that console receives a
+ * console-close event that trips its shutdown handler — the daemon comes up,
+ * binds the browser IPC socket, then tears itself down ~36ms later (#556).
+ * Going through `process.execPath` means a real PE/binary is spawned with
+ * `detached: true` and no console, so nothing signals the daemon after launch.
+ *
+ * When the entry isn't a JS file (e.g. a native launcher resolved via
+ * `which agents`), run it directly — it owns its own runtime resolution.
+ */
+export declare function getDaemonLaunch(agentsBin?: string): {
+    command: string;
+    args: string[];
+};
+interface StartDetachedOptions {
+    /** CLI entry to launch (defaults to the running binary). Injectable for tests. */
+    agentsBin?: string;
+    /** Log file the daemon's stdio is redirected to (defaults to the daemon log). */
+    logPath?: string;
+    /** Environment for the child (defaults to the OAuth-augmented detached env). */
+    env?: NodeJS.ProcessEnv;
+}
+export declare function startDetached(opts?: StartDetachedOptions): {
+    pid: number | null;
+    method: string;
+};
 /** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export declare function stopDaemon(): boolean;
 /** Get current daemon status including running state, PID, and enabled job count. */
@@ -59,3 +150,4 @@ export declare function getDaemonStatus(): {
 export declare function readDaemonLog(lines?: number): string;
 /** Send SIGHUP to the daemon to trigger a job reload. */
 export declare function signalDaemonReload(): boolean;
+export {};

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 {
@@ -373,6 +475,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 +567,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 +611,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 +638,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 +650,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 +667,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();
 }
@@ -538,18 +702,58 @@ export function buildDetachedDaemonEnv(baseEnv = process.env) {
     }
     return env;
 }
-function startDetached() {
-    const agentsBin = getAgentsBinPath();
-    const logPath = getLogPath();
+/**
+ * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
+ * exact form that works under a direct `daemon _run`.
+ *
+ * We spawn the Node runtime (`process.execPath`) with the CLI entry as an
+ * argument rather than executing the entry path directly. Executing the `.js`
+ * path relies on its shebang on POSIX, and on Windows CreateProcess can't run a
+ * `.js`/shim directly at all — it gets launched through a transient
+ * console-owning wrapper (cmd.exe / the npm shim). When that wrapper exits it
+ * closes its console, and the detached daemon sharing that console receives a
+ * console-close event that trips its shutdown handler — the daemon comes up,
+ * binds the browser IPC socket, then tears itself down ~36ms later (#556).
+ * Going through `process.execPath` means a real PE/binary is spawned with
+ * `detached: true` and no console, so nothing signals the daemon after launch.
+ *
+ * When the entry isn't a JS file (e.g. a native launcher resolved via
+ * `which agents`), run it directly — it owns its own runtime resolution.
+ */
+export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
+    if (/\.(c|m)?js$/.test(agentsBin)) {
+        return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
+    }
+    return { command: agentsBin, args: ['daemon', '_run'] };
+}
+export function startDetached(opts = {}) {
+    const agentsBin = opts.agentsBin ?? getAgentsBinPath();
+    const logPath = opts.logPath ?? getLogPath();
     const logFd = fs.openSync(logPath, 'a');
-    const child = spawn(agentsBin, ['daemon', '_run'], {
+    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,
-        env: buildDetachedDaemonEnv(),
+        ...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/connect.d.ts

@@ -11,8 +11,9 @@ export declare function sshTargetFor(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
 /**

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostNameFor } from './ssh-config.js';
 /** Env var the askpass shim reads to know which bundle holds the password. */
@@ -38,15 +39,16 @@ export function sshTargetFor(device) {
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export function wrapRemoteCommand(device, cmd) {
     if (cmd.length === 0)
         return undefined;
     const joined = cmd.join(' ');
     if (device.shell === 'powershell') {
-        return `powershell -NoProfile -Command ${shellQuote(joined)}`;
+        return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(joined)}`;
     }
     return joined;
 }

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/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;