@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/accounting/usage.js

@@ -284,6 +284,12 @@ const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
 const PARTIAL_BLOCKS = ['', '\u258F', '\u258E', '\u258D', '\u258C', '\u258B', '\u258A', '\u2589'];
+// A window we EXPECTED but have no reading for \u2014 e.g. Claude's 5h "session"
+// window when the account has no usage in the current rolling window, so the
+// usage API returns five_hour.utilization = null and no session bar is written.
+// It must read as neither 0% (EMPTY '\u2591') nor 100% (FULL '\u2588') \u2014 a full block was
+// alarming and looked maxed-out \u2014 so use a dashed row that says "no data".
+const NO_DATA = '\u2504';
 /** Construct the benign no-local-log result without overloading `error`. */
 export function usageNoRecentUsageInfo() {
     return { snapshot: null, error: null, [USAGE_BENIGN_STATE]: 'no-recent-usage' };
@@ -590,7 +596,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
             : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
         const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
             if (!window) {
-                const missing = chalk.red(`${shortLabel}: ${FULL.repeat(COMPACT_BAR_LEN)} unavailable`);
+                const missing = chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
                 return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
             }
             const bar = renderCompactUsageBar(window.usedPercent);

package/dist/lib/auth-mint.d.ts

@@ -143,7 +143,17 @@ export interface MintAndSeedResult {
  */
 export declare function mintAndSeed(input: MintAndSeedInput): Promise<MintAndSeedResult>;
 export declare function resolveSyncTargets(fleet: boolean, devices: string[]): Promise<string[]>;
-/** True when a Claude setup-token is already seeded on this box (setup status). */
+/**
+ * True when a Claude setup-token is already seeded on this box (setup status).
+ *
+ * Read-only status probe (`agents setup`, `agents doctor`) — the reserved
+ * auth-bundle check below MUST NOT crash the whole command because the
+ * keychain could not be reached (e.g. the macOS Keychain helper source is
+ * unavailable — PHNX-3385); `bundleExists()`/`hasKeychainToken()` document
+ * themselves as failing loud, but that contract is for destructive-write
+ * guards, not a diagnostic. An unreachable keychain here just means "cannot
+ * confirm the reserved bundle," reported honestly rather than propagated.
+ */
 export declare function hasMintedSetupToken(): {
     ready: boolean;
     detail: string;

package/dist/lib/auth-mint.js

@@ -414,18 +414,33 @@ async function syncMintedBundles(accountName, device) {
         return { device, ok: false, message: err instanceof Error ? err.message : String(err) };
     }
 }
-/** True when a Claude setup-token is already seeded on this box (setup status). */
+/**
+ * True when a Claude setup-token is already seeded on this box (setup status).
+ *
+ * Read-only status probe (`agents setup`, `agents doctor`) — the reserved
+ * auth-bundle check below MUST NOT crash the whole command because the
+ * keychain could not be reached (e.g. the macOS Keychain helper source is
+ * unavailable — PHNX-3385); `bundleExists()`/`hasKeychainToken()` document
+ * themselves as failing loud, but that contract is for destructive-write
+ * guards, not a diagnostic. An unreachable keychain here just means "cannot
+ * confirm the reserved bundle," reported honestly rather than propagated.
+ */
 export function hasMintedSetupToken() {
     const records = Object.values(readAccountRegistry().accounts);
     const setup = records.filter((a) => a.auth === 'setup-token' && a.provider === 'anthropic');
     if (setup.length) {
         return { ready: true, detail: `${setup.length} Claude setup-token account${setup.length === 1 ? '' : 's'}` };
     }
-    if (bundleExists(AUTH_BUNDLE) && bundleBackend(AUTH_BUNDLE) === 'file') {
-        const bundle = readBundle(AUTH_BUNDLE);
-        const keys = Object.keys(bundle.vars).filter((k) => k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_'));
-        if (keys.length)
-            return { ready: true, detail: `reserved auth bundle (${keys.length} account key${keys.length === 1 ? '' : 's'})` };
+    try {
+        if (bundleExists(AUTH_BUNDLE) && bundleBackend(AUTH_BUNDLE) === 'file') {
+            const bundle = readBundle(AUTH_BUNDLE);
+            const keys = Object.keys(bundle.vars).filter((k) => k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_'));
+            if (keys.length)
+                return { ready: true, detail: `reserved auth bundle (${keys.length} account key${keys.length === 1 ? '' : 's'})` };
+        }
+    }
+    catch (err) {
+        return { ready: false, detail: `could not check the reserved auth bundle: ${err.message}` };
     }
     return { ready: false, detail: 'no Claude setup-token minted — agents accounts mint claude' };
 }

package/dist/lib/auto-pull-worker.js

@@ -10,7 +10,7 @@
  */
 import * as fs from 'fs';
 import { simpleGit } from 'simple-git';
-import { tryAutoPull, isGitRepo } from './git.js';
+import { tryAutoPullSystemRepo, isGitRepo } from './git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath, markDetachedSyncComplete, SYNC_LOCK_TTL_MS, } from './auto-pull.js';
 /**
@@ -99,7 +99,12 @@ async function processTarget(target) {
                 await notifyRepo(target);
             }
             else {
-                await tryAutoPull(target.dir);
+                // Verify origin is the EXPECTED system remote before fast-forwarding —
+                // the system repo ships hooks that run as shell, so a pull from a
+                // repointed origin is RCE. An unexpected origin is refused, not pulled
+                // (PHNX-2957). The detached worker has no terminal to warn on; the
+                // foreground `agents use` path surfaces the refusal to the operator.
+                await tryAutoPullSystemRepo(target.dir);
             }
         }
         else {

package/dist/lib/browser/ipc.d.ts

@@ -12,6 +12,14 @@ export declare function getSocketPath(): string;
 /** Is the daemon reachable? A real connect probe on every platform — a socket
  * file existing on disk is not proof a daemon is listening on it. */
 export declare function isDaemonReachable(): Promise<boolean>;
+/**
+ * Is a *reachable* daemon actually responsive, or is its event loop wedged
+ * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
+ * pause) never condemns a healthy daemon; returns true as soon as any attempt
+ * gets a reply, and false only when every attempt fails.
+ */
+export declare function isDaemonResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
 /**
  * Wait until the browser daemon is genuinely reachable, or throw.
  *

package/dist/lib/browser/ipc.js

@@ -92,6 +92,31 @@ const SOCKET_WAIT_TIMEOUT_MS = 15_000;
  * doesn't race a restart it happened to probe mid-flight.
  */
 const SOCKET_WAIT_STABLE_PROBES = 2;
+/**
+ * How long a single {@link probeDaemonResponsive} attempt waits for the daemon to
+ * answer a trivial `version` request before giving up (PHNX-3411).
+ *
+ * A unix-socket `connect` succeeds at the KERNEL level the moment the connection
+ * is queued in the listen backlog — it does NOT require the server's event loop
+ * to run. So a daemon whose event loop is blocked (e.g. a long synchronous burst
+ * on the shared loop) still passes {@link isDaemonReachable}: the socket accepts,
+ * but the request is never serviced. The live symptom on zion was exactly this —
+ * `browser.sock` accepted every connection while the daemon re-indexed sessions,
+ * then never replied, so cross-device browser drives hung or surfaced a confusing
+ * bare socket timeout. Requiring an actual reply is the only probe that tells a
+ * healthy daemon apart from a wedged one.
+ */
+const RESPONSIVENESS_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Consecutive missed {@link probeDaemonResponsive} attempts before a *reachable*
+ * daemon is declared wedged. One missed reply can be a transient GC pause on an
+ * otherwise-healthy loop, so a single failure never condemns the daemon; a daemon
+ * that cannot answer a trivial `version` request across this whole window has a
+ * genuinely blocked event loop. The added latency (attempts × timeout) is paid
+ * ONLY on the wedged path — where the alternative was an indefinite hang — while
+ * a healthy daemon answers the first attempt in ~1ms.
+ */
+const RESPONSIVENESS_PROBE_ATTEMPTS = 3;
 export class BrowserDaemonNotRunningError extends Error {
     constructor() {
         super(formatBrowserDaemonNotRunningError());
@@ -140,6 +165,57 @@ function probeDaemon(endpoint, timeoutMs = 500) {
 export async function isDaemonReachable() {
     return probeDaemon(getIpcEndpoint());
 }
+/**
+ * Can the daemon actually REPLY right now? Opens a connection and requires a
+ * parseable response to a `version` request within `timeoutMs`. Unlike
+ * {@link probeDaemon} (which resolves on the kernel-level `connect`), this only
+ * succeeds when the daemon's event loop is running and services the request — so
+ * it is the one probe that distinguishes a healthy daemon from a wedged one whose
+ * loop is blocked (PHNX-3411). Resolves false on connect error, timeout, an early
+ * close, or an unparseable reply. `version` is the right probe: its handler is
+ * trivial and synchronous (never touches the browser), so a slow reply means the
+ * loop is blocked, not that a real action is in flight.
+ */
+function probeDaemonResponsive(endpoint, timeoutMs = RESPONSIVENESS_PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const sock = net.createConnection(endpoint);
+        let buffer = '';
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; clearTimeout(timer); sock.destroy(); resolve(ok); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        sock.on('connect', () => { sock.write(JSON.stringify({ action: 'version' }) + '\n'); });
+        sock.on('data', (data) => {
+            buffer += data.toString();
+            const idx = buffer.indexOf('\n');
+            if (idx === -1)
+                return;
+            try {
+                const resp = JSON.parse(buffer.slice(0, idx));
+                finish(resp.ok === true);
+            }
+            catch {
+                finish(false);
+            }
+        });
+        sock.on('error', () => finish(false));
+        sock.on('close', () => finish(false));
+    });
+}
+/**
+ * Is a *reachable* daemon actually responsive, or is its event loop wedged
+ * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
+ * pause) never condemns a healthy daemon; returns true as soon as any attempt
+ * gets a reply, and false only when every attempt fails.
+ */
+export async function isDaemonResponsive(endpoint = getIpcEndpoint(), attempts = RESPONSIVENESS_PROBE_ATTEMPTS) {
+    for (let i = 0; i < attempts; i++) {
+        if (await probeDaemonResponsive(endpoint))
+            return true;
+    }
+    return false;
+}
 /**
  * Wait until the browser daemon is genuinely reachable, or throw.
  *
@@ -1087,6 +1163,17 @@ async function prepareIPC(action, opts) {
         }
         await new Promise((r) => setTimeout(r, 300));
     }
+    // The socket accepts connections — but a unix-socket `connect` succeeds at the
+    // kernel level even when the daemon's event loop is blocked and never services
+    // the request (PHNX-3411). Require a real reply before treating the daemon as
+    // usable, so a wedged daemon fails LOUD with an accurate, actionable error
+    // instead of the confusing bare socket timeout / indefinite hang the browser
+    // verb would otherwise hit (including inside reconcileDaemonVersion's own
+    // version probe, which has no response timeout). Skipped for callers that opt
+    // out of auto-start — they want the clean BrowserDaemonNotRunningError instead.
+    if (autoStartDaemon && !(await isDaemonResponsive(getIpcEndpoint()))) {
+        throw new Error(actionable('Browser daemon is running but unresponsive — its event loop is blocked, so it accepts the connection but never replies.', `Endpoint: ${getIpcEndpoint()}`, `Log: ${getDaemonLogPath()}`, 'Next: agents browser stop --daemon   (resets the wedged daemon; the next browser command restarts it)'));
+    }
     // Before serving a real request, make sure the daemon isn't running stale
     // code. Skips the internal `version` probe (avoids recursion) and callers
     // that opt out of auto-start. No-ops once reconciled or when versions match.

package/dist/lib/browser/service.d.ts

@@ -534,6 +534,25 @@ export declare class BrowserService {
      * tasks.json entries. Used before identity-based resolution so a daemon
      * restart does not make the caller's tasks invisible.
      */
+    /**
+     * Register a freshly-rehydrated connection, unless a concurrent rehydrate won
+     * the race and already registered one for this key. `attachRunningProfile`
+     * awaits an ssh-tunnel spawn / CDP connect, so two commands landing right
+     * after a daemon restart can each build a connection for the same key; the
+     * loser must be released instead of silently overwriting the winner (whose
+     * `cleanup` would then never run).
+     *
+     * The subtlety is the SSH tunnel: when the loser's `connectSSH` landed after
+     * the winner's tunnel had already bound the local port, `isOwnTunnel` makes it
+     * **reuse** that same OS process (`drivers/ssh.ts`) — so both connections carry
+     * the same `pid`/`port`. Calling the loser's `cleanup()` then does
+     * `tunnel.kill()` on the SHARED process and breaks the winner's live CDP. So
+     * when the loser shares the winner's tunnel we close ONLY the loser's own CDP
+     * socket and leave the tunnel to the winner; only a loser that spawned its own
+     * distinct tunnel gets the full `cleanup()` (else it would leak). Returns the
+     * winning connection to use.
+     */
+    private registerRehydratedConnection;
     private rehydrateAllFromDisk;
     /**
      * On a RAM miss, scan profile runtime dirs for a tasks.json entry matching

package/dist/lib/browser/service.js

@@ -2608,9 +2608,45 @@ export class BrowserService {
         if (port === undefined)
             return null;
         const host = parsed?.host && parsed.host !== 'localhost' ? parsed.host : 'localhost';
-        // ssh:// endpoints need a tunnel; soft rehydrate only handles local CDP.
-        if (resolved.target.startsWith('ssh:'))
-            return null;
+        // ssh:// endpoints: a daemon restart killed this box's tunnel, but the
+        // browser is still running on the FAR side — so the caller's tasks are
+        // valid, only the local hop is gone. Re-establish the tunnel and reconnect
+        // CDP (connectSSH attaches to the already-running remote browser via
+        // isOwnTunnel — it never launches one, so this stays a soft-attach), then
+        // merge the disk tasks. Without this, a remote agent driving a browser host
+        // after a restart got "Unknown browser task" for a tab that was still alive
+        // (PHNX-2663). A failure returns null exactly like the local-CDP path, so
+        // the caller falls through to disk reconcile rather than crashing.
+        if (resolved.target.startsWith('ssh:')) {
+            try {
+                const conn = await connectSSH(resolved.target, profile, key, { persistRemote: true });
+                await this.enableDomains(conn.cdp);
+                const tasks = this.loadTaskState(key);
+                for (const [k, t] of diskTasks) {
+                    if (!tasks.has(k))
+                        tasks.set(k, t);
+                }
+                return {
+                    cdp: conn.cdp,
+                    port: conn.port,
+                    pid: conn.pid,
+                    electron: profile.electron,
+                    browserType: profile.browser,
+                    targetFilter: resolved.targetFilter ?? profile.targetFilter,
+                    key,
+                    profile: bare,
+                    tasks,
+                    sessionCache: new Map(),
+                    // Carry the tunnel teardown so removing this connection kills the
+                    // ssh hop — otherwise it leaks across the next restart (see the
+                    // `cleanup` docblock on ProfileConnection).
+                    cleanup: conn.cleanup,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
         try {
             const { wsUrl, browser } = await discoverBrowserWsUrl(port, host, bare);
             verifyBrowserIdentity(browser, profile.browser, port, host);
@@ -2645,6 +2681,48 @@ export class BrowserService {
      * tasks.json entries. Used before identity-based resolution so a daemon
      * restart does not make the caller's tasks invisible.
      */
+    /**
+     * Register a freshly-rehydrated connection, unless a concurrent rehydrate won
+     * the race and already registered one for this key. `attachRunningProfile`
+     * awaits an ssh-tunnel spawn / CDP connect, so two commands landing right
+     * after a daemon restart can each build a connection for the same key; the
+     * loser must be released instead of silently overwriting the winner (whose
+     * `cleanup` would then never run).
+     *
+     * The subtlety is the SSH tunnel: when the loser's `connectSSH` landed after
+     * the winner's tunnel had already bound the local port, `isOwnTunnel` makes it
+     * **reuse** that same OS process (`drivers/ssh.ts`) — so both connections carry
+     * the same `pid`/`port`. Calling the loser's `cleanup()` then does
+     * `tunnel.kill()` on the SHARED process and breaks the winner's live CDP. So
+     * when the loser shares the winner's tunnel we close ONLY the loser's own CDP
+     * socket and leave the tunnel to the winner; only a loser that spawned its own
+     * distinct tunnel gets the full `cleanup()` (else it would leak). Returns the
+     * winning connection to use.
+     */
+    registerRehydratedConnection(key, conn) {
+        const existing = this.connections.get(key);
+        if (!existing) {
+            this.connections.set(key, conn);
+            return conn;
+        }
+        const sharesTunnel = conn.pid !== 0 && conn.pid === existing.pid && conn.port === existing.port;
+        if (conn.pid !== 0 && !sharesTunnel && conn.cleanup) {
+            // Distinct tunnel — full teardown so this loser's tunnel doesn't leak.
+            try {
+                conn.cleanup();
+            }
+            catch { /* best effort — the winner stays live */ }
+        }
+        else {
+            // Shared/borrowed tunnel (or a local connection with no tunnel): close
+            // only our own CDP client; killing the tunnel would break the winner.
+            try {
+                conn.cdp.close();
+            }
+            catch { /* best effort */ }
+        }
+        return existing;
+    }
     async rehydrateAllFromDisk() {
         const runtimeRoot = getBrowserRuntimeDir();
         let dirNames = [];
@@ -2676,7 +2754,11 @@ export class BrowserService {
             const conn = await this.attachRunningProfile(key, tasks);
             if (!conn)
                 continue;
-            this.connections.set(key, conn);
+            // A concurrent rehydrate may have registered one for this key while we
+            // awaited the attach; keep the winner and tear our loser's tunnel down.
+            const registered = this.registerRehydratedConnection(key, conn);
+            if (registered !== conn)
+                continue;
             try {
                 await this.applyDefaultDownloadBehavior(conn, key);
             }
@@ -2734,13 +2816,16 @@ export class BrowserService {
                     // CDP down — cannot rehydrate a live connection; caller will error.
                     continue;
                 }
-                conn = attached;
-                this.connections.set(key, conn);
-                try {
-                    await this.applyDefaultDownloadBehavior(conn, key);
-                }
-                catch {
-                    // Non-fatal.
+                // Keep whichever connection a concurrent rehydrate registered first and
+                // tear our loser's tunnel down instead of leaking it (see the helper).
+                conn = this.registerRehydratedConnection(key, attached);
+                if (conn === attached) {
+                    try {
+                        await this.applyDefaultDownloadBehavior(conn, key);
+                    }
+                    catch {
+                        // Non-fatal.
+                    }
                 }
             }
             const task = this.lookupTaskOnConn(conn, taskId) ?? found;

package/dist/lib/browser/sessions-list.js

@@ -21,6 +21,7 @@ import { formatBytes } from '../format.js';
 export { formatBytes };
 import * as path from 'path';
 import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
+import { listProfileCacheDirs } from './runtime-state.js';
 import { formatRelativeTime } from '../session/relative-time.js';
 import { getSessionById, listBrowserSessionRecords, pruneToolSessions } from '../session/db.js';
 import { listPidSessionEntries } from '../session/pid-registry.js';
@@ -99,7 +100,15 @@ export function listProfileArtifacts(profile) {
 export function listBrowserSessions(only) {
     let profiles;
     if (only) {
-        profiles = [only];
+        // A profile's live tasks/captures may live under a composite runtime dir
+        // (`<name>@<device>`, `<name>@endpoint-N`, forks) — NOT the bare `<name>`
+        // dir. Resolve `only` to every cache dir that belongs to it, the same rule
+        // status()/findTask use (keyBelongsToProfile), so `--profile comet-local`
+        // surfaces the real `comet-local@zion` store instead of the empty legacy
+        // dir. Keep the requested name when nothing exists on disk yet so a fresh
+        // profile still returns its (empty) entry rather than vanishing.
+        const dirs = listProfileCacheDirs(only).map((d) => path.basename(d));
+        profiles = dirs.length > 0 ? dirs : [only];
     }
     else {
         try {

package/dist/lib/cloud/rush.d.ts

@@ -5,6 +5,13 @@
  * Requires the Rush GitHub App installed on the target repo.
  */
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, ImageAttachment, SkillRef } from './types.js';
+/**
+ * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
+ * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * expires_at is treated as non-expired so tokens written without an expiry
+ * still work. Pass yamlPath to override the default path in tests.
+ */
+export declare function isRushSessionValid(yamlPath?: string): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
 export interface AccountManifestEntry {
     version: string;

package/dist/lib/cloud/rush.js

@@ -16,6 +16,29 @@ import { getAccountInfo } from '../agents.js';
 import { selectBalancedVersion } from '../accounting/rotate.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+/**
+ * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
+ * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * expires_at is treated as non-expired so tokens written without an expiry
+ * still work. Pass yamlPath to override the default path in tests.
+ */
+export function isRushSessionValid(yamlPath = USER_YAML) {
+    try {
+        if (!fs.existsSync(yamlPath))
+            return false;
+        const raw = fs.readFileSync(yamlPath, 'utf-8');
+        const data = yaml.parse(raw);
+        if (!data?.session?.access_token)
+            return false;
+        const expiresAt = data.session.expires_at;
+        if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Read the Rush session access token from ~/.rush/user.yaml. */
 function readToken() {
     if (!fs.existsSync(USER_YAML)) {
@@ -27,6 +50,11 @@ function readToken() {
     if (!token) {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
+    const expiresAt = data.session?.expires_at;
+    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
+    }
     return token;
 }
 /** Read the user's email from the Rush session config, if available. */
@@ -203,7 +231,7 @@ export class RushCloudProvider {
     name = 'Rush Cloud';
     capabilities() {
         return {
-            available: fs.existsSync(USER_YAML),
+            available: isRushSessionValid(),
             dispatch: true,
             status: true,
             list: true,

package/dist/lib/daemon/daemon.d.ts

@@ -215,6 +215,28 @@ export declare function anchorDaemonCwd(): string | null;
  * root is stable (or could not be resolved).
  */
 export declare function warnEphemeralDaemonRoot(resolveBin?: () => string): string | null;
+/**
+ * Test-home tripwire (PHNX-2545). The routines/daemon test suite spawns real
+ * `agents __daemon-run` processes against an isolated /tmp HOME. If that HOME
+ * override fails to reach the child — an `env: {...process.env}` spawn that
+ * forgot to set it, a login shell that reset HOME — the daemon resolves its
+ * state dir under the operator's REAL home and its scheduler/watchdog then tick
+ * against shared production state. That is the exact leak the ticket reports:
+ * real test daemons found alive on a fleet box, each a second live scheduler
+ * racing the legitimate one, in violation of the execution-singularity spec.
+ *
+ * A test that spawns a daemon sets AGENTS_DAEMON_TEST_HOME to the isolated home
+ * it provisioned. When that marker is present, this daemon's resolved state dir
+ * MUST sit under it; otherwise the daemon refuses to boot — failing loud before
+ * it claims an instance, writes a pid, or fires a single tick (the throw is
+ * caught in index.ts's `__daemon-run` handler, logged, and exits non-zero) —
+ * rather than running in the wrong directory against the real host. In
+ * production the marker is never set, so this is a no-op there.
+ *
+ * `daemonDir`/`testHome` are injectable so the pure guard is unit-testable
+ * without spawning a process; the defaults read the live daemon dir and env.
+ */
+export declare function assertTestDaemonHome(daemonDir?: string, testHome?: string | undefined): void;
 export declare function runDaemon(): Promise<void>;
 /**
  * Write a launchd plist or systemd unit with owner-only permissions atomically.

package/dist/lib/daemon/daemon.js

@@ -705,6 +705,40 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
         return null;
     }
 }
+/**
+ * Test-home tripwire (PHNX-2545). The routines/daemon test suite spawns real
+ * `agents __daemon-run` processes against an isolated /tmp HOME. If that HOME
+ * override fails to reach the child — an `env: {...process.env}` spawn that
+ * forgot to set it, a login shell that reset HOME — the daemon resolves its
+ * state dir under the operator's REAL home and its scheduler/watchdog then tick
+ * against shared production state. That is the exact leak the ticket reports:
+ * real test daemons found alive on a fleet box, each a second live scheduler
+ * racing the legitimate one, in violation of the execution-singularity spec.
+ *
+ * A test that spawns a daemon sets AGENTS_DAEMON_TEST_HOME to the isolated home
+ * it provisioned. When that marker is present, this daemon's resolved state dir
+ * MUST sit under it; otherwise the daemon refuses to boot — failing loud before
+ * it claims an instance, writes a pid, or fires a single tick (the throw is
+ * caught in index.ts's `__daemon-run` handler, logged, and exits non-zero) —
+ * rather than running in the wrong directory against the real host. In
+ * production the marker is never set, so this is a no-op there.
+ *
+ * `daemonDir`/`testHome` are injectable so the pure guard is unit-testable
+ * without spawning a process; the defaults read the live daemon dir and env.
+ */
+export function assertTestDaemonHome(daemonDir = getDaemonDir(), testHome = process.env.AGENTS_DAEMON_TEST_HOME) {
+    if (!testHome)
+        return;
+    const root = path.resolve(testHome);
+    const dir = path.resolve(daemonDir);
+    if (dir !== root && !dir.startsWith(root + path.sep)) {
+        const msg = `Daemon test-home tripwire (PHNX-2545): AGENTS_DAEMON_TEST_HOME is ${root}, but this ` +
+            `daemon's state dir resolved to ${dir} — the isolated HOME override did not reach this ` +
+            `__daemon-run child, so it would schedule against the real host. Refusing to start.`;
+        log('ERROR', msg);
+        throw new Error(msg);
+    }
+}
 // ---------------------------------------------------------------------------
 // Module-level periodic maintenance helpers (RUSH-2422)
 //
@@ -720,6 +754,11 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
 // below. runBrokerSelfHeal was moved into SecretsBrokerService (RUSH-3193 P2).
 // ---------------------------------------------------------------------------
 export async function runDaemon() {
+    // PHNX-2545 test-home tripwire — FIRST, before this daemon claims an instance,
+    // writes a pid, or fires any tick. A test-spawned daemon that lost its isolated
+    // HOME override must refuse to run against the operator's real state rather than
+    // schedule against the real host. No-op in production (the marker is never set).
+    assertTestDaemonHome();
     // Single-instance guard (last-wins, SING-11): a direct `agents __daemon-run`
     // (manual, or a service-manager restart racing a live predecessor) EVICTS the
     // incumbent and becomes the survivor. claimDaemonInstance returns false only

package/dist/lib/daemon/runner.d.ts

@@ -113,6 +113,8 @@ export interface RoutineLaunchPlan {
     /** False when `account` names a harness-native login rather than a durable credential. */
     forwardAccount?: boolean;
 }
+/** Claude's own local auth check; unlike account metadata it cannot mistake identity for a usable login. */
+export declare function claudeVersionIsAuthenticated(version: string): boolean;
 /**
  * Resolve the version/account chain for a routine the same way `agents run`
  * does: honor an explicit `version:` pin; otherwise use the configured run
@@ -130,6 +132,7 @@ export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string, de
     resolveCredentialAccount?: (name: string, host: AgentId) => {
         env: Record<string, string>;
     };
+    claudeVersionIsAuthenticated?: typeof claudeVersionIsAuthenticated;
 }): Promise<RoutineLaunchPlan>;
 /**
  * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.