@phnx-labs/agents-cli 1.22.68 → 1.22.69

package/dist/lib/accounting/usage.js

@@ -1900,6 +1900,17 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
 }
 /** Convert a live UsageSnapshot to its JSON-serializable cached form. */
 function serializeClaudeUsageSnapshot(snapshot) {
+    // Persist the union of fresh `windows` and last-known `staleWindows`.
+    // `deserializeClaudeUsageSnapshot` re-runs the freshness gate on read and
+    // re-partitions the serialized windows into fresh vs. stale, so what matters
+    // is that every last-known reading reaches disk. Claude's collector returns
+    // raw windows (no `staleWindows`) and relies on that read-side partition. But
+    // Grok's collector pre-partitions in the fetch, moving an ended-period reading
+    // onto `staleWindows` — serializing only `windows` dropped it, so the very
+    // number a daemon `--refresh` just captured was gone from the next cached
+    // `agents view grok`, which rendered the plan alone (no bar). Include the
+    // stale windows here so the round-trip preserves them for any collector.
+    const persistedWindows = [...snapshot.windows, ...(snapshot.staleWindows ?? [])];
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
@@ -1910,7 +1921,7 @@ function serializeClaudeUsageSnapshot(snapshot) {
                 resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
             }
             : undefined,
-        windows: snapshot.windows.map((window) => ({
+        windows: persistedWindows.map((window) => ({
             key: window.key,
             label: window.label,
             shortLabel: window.shortLabel,
@@ -2400,17 +2411,131 @@ function safeStatSync(filePath) {
         return null;
     }
 }
+/**
+ * Resolve the Grok billing log to read usage from.
+ *
+ * `agents view grok` reads usage per INSTALLED VERSION, passing each version's
+ * isolated home (`~/.agents/.history/versions/grok/<ver>`). Grok writes
+ * `unified.jsonl` only to the shared real home `~/.grok/logs/unified.jsonl`
+ * even though GROK_HOME isolates auth/config/models per version. A per-version
+ * log, if one ever appears, still wins; otherwise we return the shared path
+ * marked `shared: true` so the caller can attribute it to at most one identity.
+ * Grok accounts are version-scoped (`NATIVE_ACCOUNT_CAPABILITIES.grok.scope ===
+ * 'version'`) — the shared file has no owner, so it must not be stamped onto
+ * every version home.
+ */
+function resolveGrokBillingLogPath(home) {
+    const rel = ['.grok', 'logs', 'unified.jsonl'];
+    const perVersion = path.join(home || os.homedir(), ...rel);
+    try {
+        if (fs.existsSync(perVersion))
+            return { logPath: perVersion, shared: false };
+    }
+    catch { /* unreadable */ }
+    // `AGENTS_REAL_HOME` is the seam every version-home consumer honors: a
+    // daemon/service-manager child's HOME can be baked to something other than
+    // the account's real home, so os.homedir() alone is not a reliable stand-in.
+    const shared = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...rel);
+    if (shared !== perVersion) {
+        try {
+            if (fs.existsSync(shared))
+                return { logPath: shared, shared: true };
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
+/** This home's own `.grok/auth.json` only — never the shared-home fallback. */
+function readGrokAuthIdentity(home) {
+    const authPath = path.join(home, '.grok', 'auth.json');
+    try {
+        if (!fs.existsSync(authPath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
+        const records = (data && typeof data === 'object' ? [data, ...Object.values(data)] : [])
+            .filter((r) => !!r && typeof r === 'object' && !Array.isArray(r));
+        const account = records
+            .filter((r) => typeof r.refresh_token === 'string' || typeof r.email === 'string' || typeof r.user_id === 'string')
+            .sort((a, b) => String(b.create_time || '').localeCompare(String(a.create_time || '')))[0];
+        if (!account)
+            return null;
+        const userRaw = account.user_id ?? account.principal_id;
+        const userId = typeof userRaw === 'string' && userRaw.trim() ? userRaw.trim() : null;
+        const email = typeof account.email === 'string' && account.email.trim()
+            ? account.email.trim().toLowerCase()
+            : null;
+        if (!userId && !email)
+            return null;
+        return { userId, email };
+    }
+    catch {
+        return null;
+    }
+}
+function grokIdentitiesMatch(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.userId && b.userId)
+        return a.userId === b.userId;
+    if (a.email && b.email)
+        return a.email === b.email;
+    return false;
+}
+function grokIdentityFromBillingPayload(parsed) {
+    const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+        ? parsed.ctx
+        : null;
+    const config = ctx?.config && typeof ctx.config === 'object' && !Array.isArray(ctx.config)
+        ? ctx.config
+        : null;
+    const pick = (...cands) => {
+        for (const c of cands) {
+            if (typeof c === 'string' && c.trim())
+                return c.trim();
+        }
+        return null;
+    };
+    const userId = pick(ctx?.user_id, ctx?.userId, ctx?.principal_id, config?.user_id, parsed.user_id);
+    const emailRaw = pick(ctx?.email, config?.email, parsed.email);
+    if (!userId && !emailRaw)
+        return null;
+    return { userId, email: emailRaw ? emailRaw.toLowerCase() : null };
+}
+function sameHomePath(a, b) {
+    return (safeRealpathSync(a) ?? path.resolve(a)) === (safeRealpathSync(b) ?? path.resolve(b));
+}
+/**
+ * Whether the shared `~/.grok` billing log may be attached to this home.
+ * Grok logins are per version home; the shared last line is one account's
+ * meter. Fail loud: never copy it onto every installed identity.
+ */
+function sharedGrokLogAppliesToHome(home, match) {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const requestedHome = home || os.homedir();
+    const thisId = readGrokAuthIdentity(requestedHome);
+    if (match.identity) {
+        return grokIdentitiesMatch(match.identity, thisId);
+    }
+    // No identity on the line (the live Grok shape). Attribute the reading to
+    // exactly one canonical identity: the real home itself, or the version home
+    // whose own auth.json matches the shared `~/.grok/auth.json`.
+    if (sameHomePath(requestedHome, realHome))
+        return true;
+    return grokIdentitiesMatch(thisId, readGrokAuthIdentity(realHome));
+}
 /** Parse the latest billing info from Grok's unified log. */
 async function getGrokUsageInfo(options) {
     try {
-        const base = options?.home || os.homedir();
-        const logPath = path.join(base, '.grok', 'logs', 'unified.jsonl');
+        const resolved = resolveGrokBillingLogPath(options?.home);
         // No log yet: a benign "nothing recorded here", not a failure (RUSH-3040).
-        if (!fs.existsSync(logPath))
+        if (!resolved)
             return usageNoRecentUsageInfo();
-        const match = await readLatestGrokBilling(logPath);
+        const match = await readLatestGrokBilling(resolved.logPath);
         if (!match)
             return usageNoRecentUsageInfo();
+        if (resolved.shared && !sharedGrokLogAppliesToHome(options?.home, match)) {
+            return usageNoRecentUsageInfo();
+        }
         // Grok has no live usage API (`network: false`) — bars are last-seen from
         // this machine's unified.jsonl only. Drop windows whose billing period has
         // already ended so a stale 100% does not paint "rate-limited" after reset,
@@ -2703,10 +2828,16 @@ async function readLatestGrokBilling(filePath) {
                 return;
             try {
                 const parsed = JSON.parse(line);
-                if (parsed.msg === 'billing: fetched credits config' && parsed.ctx?.config) {
-                    const config = parsed.ctx.config;
+                const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+                    ? parsed.ctx
+                    : null;
+                if (parsed.msg === 'billing: fetched credits config' && ctx?.config) {
+                    const config = ctx.config;
                     const windows = [];
-                    if (config.currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
+                    const currentPeriod = config.currentPeriod && typeof config.currentPeriod === 'object'
+                        ? config.currentPeriod
+                        : null;
+                    if (currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
                         // `creditUsagePercent` is Grok's weekly credit consumption (0-100);
                         // the billing period's `end` is when that window resets.
                         // Do NOT coerce a missing percent to 0 — a new period often lands a
@@ -2718,14 +2849,15 @@ async function readLatestGrokBilling(filePath) {
                             label: 'Current week',
                             shortLabel: 'W',
                             usedPercent: Math.max(0, Math.min(100, rawPercent)),
-                            resetsAt: parseDateValue(config.currentPeriod.end),
+                            resetsAt: parseDateValue(currentPeriod.end),
                             windowMinutes: inferWindowMinutes('week'),
                         });
                     }
                     latest = {
                         capturedAt: parseDateValue(parsed.ts),
-                        subscriptionTier: parsed.ctx.subscriptionTier || null,
+                        subscriptionTier: typeof ctx.subscriptionTier === 'string' ? ctx.subscriptionTier : null,
                         windows,
+                        identity: grokIdentityFromBillingPayload(parsed),
                     };
                 }
             }

package/dist/lib/boot-profile.d.ts

@@ -0,0 +1,14 @@
+/** True when `AGENTS_PROFILE_BOOT` is set — callers can skip building label strings. */
+export declare function bootProfileEnabled(): boolean;
+/**
+ * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
+ * this is free to call unconditionally on the launch path.
+ */
+export declare function bootMark(label: string): void;
+/**
+ * Print the collected timeline to stderr, once. Called right before the harness
+ * child is spawned (the end of the pre-exec window) and again as an
+ * `process.on('exit')` backstop for launch paths that error out before spawn.
+ * `reason` labels the final boundary (e.g. `spawn`, `exit`).
+ */
+export declare function flushBootProfile(reason: string): void;

package/dist/lib/boot-profile.js

@@ -0,0 +1,66 @@
+/**
+ * Boot-time profiler for the `agents run` pre-exec phase (PHNX-3585).
+ *
+ * The AGI EXT "New Claude" boot spends the whole `agents run` wrapper cost
+ * BEFORE the harness prints anything — version resolution, account rotation,
+ * config sync, login preflight. This module makes that window measurable
+ * without a debugger: gate it on `AGENTS_PROFILE_BOOT=1` and the run path
+ * stamps named marks, then flushes a per-stage timeline to stderr the instant
+ * before the child is spawned (the moment the wrapper's work ends).
+ *
+ * All marks are `performance.now()` values, which Node measures from
+ * `performance.timeOrigin` ≈ process start — so a mark's absolute value is
+ * "ms since the `agents` process began", and consecutive marks give the cost
+ * of each stage. When the env flag is off, every function here is a couple of
+ * cheap branches and pushes nothing, so it is safe to leave wired on the hot
+ * path (the committed `scripts/bench-boot.sh` benchmark drives it).
+ */
+import { performance } from 'node:perf_hooks';
+const ENABLED = process.env.AGENTS_PROFILE_BOOT === '1' || process.env.AGENTS_PROFILE_BOOT === 'true';
+const marks = [];
+let flushed = false;
+/** True when `AGENTS_PROFILE_BOOT` is set — callers can skip building label strings. */
+export function bootProfileEnabled() {
+    return ENABLED;
+}
+/**
+ * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
+ * this is free to call unconditionally on the launch path.
+ */
+export function bootMark(label) {
+    if (!ENABLED)
+        return;
+    marks.push({ label, at: performance.now() });
+}
+/**
+ * Print the collected timeline to stderr, once. Called right before the harness
+ * child is spawned (the end of the pre-exec window) and again as an
+ * `process.on('exit')` backstop for launch paths that error out before spawn.
+ * `reason` labels the final boundary (e.g. `spawn`, `exit`).
+ */
+export function flushBootProfile(reason) {
+    if (!ENABLED || flushed)
+        return;
+    flushed = true;
+    bootMark(reason);
+    if (marks.length === 0)
+        return;
+    const start = 0; // process start
+    const end = marks[marks.length - 1].at;
+    const width = Math.max(...marks.map((m) => m.label.length));
+    const lines = [];
+    lines.push(`[boot-profile] pre-exec timeline (total ${(end - start).toFixed(1)}ms since process start)`);
+    let prev = start;
+    for (const m of marks) {
+        const delta = m.at - prev;
+        prev = m.at;
+        lines.push(`  ${m.label.padEnd(width)}  +${delta.toFixed(1).padStart(7)}ms   @${m.at.toFixed(1).padStart(8)}ms`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+}
+// Backstop: a run that exits before reaching the spawn (a login dead-end, a
+// missing install) still emits whatever stages it reached, so the profile is
+// never silently empty.
+if (ENABLED) {
+    process.on('exit', () => flushBootProfile('exit'));
+}

package/dist/lib/channels/providers/desktop.d.ts

@@ -2,10 +2,11 @@ import type { ChannelProvider } from '../registry.js';
 /**
  * Split one message into the notification's title and body.
  *
- * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
- * with any link on a second line — so honouring the newline puts the human
- * sentence in the title and the URL underneath, which is how the existing
- * daemon notifications already read.
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — a title line, a
+ * blank line, then the body (and a `Sent from …` footer) — so honouring the first
+ * newline puts the scannable head in the title and the rest in the body, which is
+ * how the existing daemon notifications already read. (Desktop is a plain sink, so
+ * the message carries no URLs to split off.)
  *
  * Notification banners show roughly two lines before an ellipsis, so a long
  * single-line message is split at the title boundary rather than truncated away:

package/dist/lib/channels/providers/desktop.js

@@ -28,10 +28,11 @@ const TITLE_MAX = 64;
 /**
  * Split one message into the notification's title and body.
  *
- * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
- * with any link on a second line — so honouring the newline puts the human
- * sentence in the title and the URL underneath, which is how the existing
- * daemon notifications already read.
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — a title line, a
+ * blank line, then the body (and a `Sent from …` footer) — so honouring the first
+ * newline puts the scannable head in the title and the rest in the body, which is
+ * how the existing daemon notifications already read. (Desktop is a plain sink, so
+ * the message carries no URLs to split off.)
  *
  * Notification banners show roughly two lines before an ellipsis, so a long
  * single-line message is split at the title boundary rather than truncated away:

package/dist/lib/claude-account-token.js

@@ -79,11 +79,100 @@ export function resolveClaudeSetupToken(home) {
     // Require a known account (email) up front: without it we cannot key a
     // per-account token, and we must NOT fall back to a bare shared key that
     // would misapply one account's setup-token to another.
-    const email = readClaudeAccountEmail(home);
+    const email = readClaudeAccountEmail(home)
+        // Self-heal (PHNX-3660): a home provisioned before seed-on-attach carries an
+        // `.oauth_token` but no identity. Recover the email from the bundle and
+        // write it back, so the home converges instead of needing a re-attach.
+        // Explicit-home only: with no home the probe targets the operator's real
+        // ~/.claude.json, which a library read must never rewrite.
+        ?? (home ? discoverClaudeAccountEmailFromOauthToken(home) : null);
     if (!email)
         return null;
     return resolveClaudeSetupTokenForEmail(email, home ?? os.homedir());
 }
+/** Negative/positive discovery cache, keyed by home + .oauth_token fingerprint (SHOULD-2). */
+const discoveryCache = new Map();
+/**
+ * Recover a home's account email from its `.claude/.oauth_token` by matching
+ * the token VALUE against the `auth` bundle (the slug encodes the email, and
+ * the re-encode check makes the decode lossless or fail). On a match the
+ * identity is written back via {@link seedClaudeWorkerHomeIdentity}, so this
+ * runs at most once per home. Returns null — and writes nothing — when the
+ * file is missing, malformed, or matches no bundle key: a token that no longer
+ * exists in the bundle must not resurrect an account mapping. A no-match
+ * result is cached against the token file's fingerprint so a rotated-out home
+ * does not re-decrypt the bundle on every probe.
+ */
+function discoverClaudeAccountEmailFromOauthToken(home) {
+    try {
+        const tokenPath = path.join(home, '.claude', '.oauth_token');
+        const fingerprint = credentialFingerprint(tokenPath);
+        if (fingerprint === 'missing')
+            return null;
+        const cached = discoveryCache.get(home);
+        if (cached && cached.fingerprint === fingerprint)
+            return cached.email;
+        const email = discoverEmailUncached(home, tokenPath);
+        discoveryCache.set(home, { fingerprint, email });
+        return email;
+    }
+    catch (err) {
+        if (err instanceof ReservedBundleWrongBackendError)
+            throw err;
+        return null;
+    }
+}
+function discoverEmailUncached(home, tokenPath) {
+    let token;
+    try {
+        token = fs.readFileSync(tokenPath, 'utf-8').trim();
+    }
+    catch {
+        return null;
+    }
+    if (!isValidClaudeSetupToken(token))
+        return null;
+    if (!bundleExists(AUTH_BUNDLE))
+        return null;
+    if (bundleBackend(AUTH_BUNDLE) !== 'file') {
+        throw new ReservedBundleWrongBackendError(AUTH_BUNDLE, bundleBackend(AUTH_BUNDLE));
+    }
+    const { env } = readAndResolveBundleEnv(AUTH_BUNDLE, { caller: 'usage', agentOnly: true });
+    for (const [key, value] of Object.entries(env)) {
+        if (value.trim() !== token)
+            continue;
+        const email = emailFromTokenKey(key);
+        if (!email)
+            continue;
+        seedClaudeWorkerHomeIdentity(home, email);
+        return email;
+    }
+    return null;
+}
+/**
+ * Decode the email a `CLAUDE_CODE_OAUTH_TOKEN_<slug>` key encodes — or null
+ * when the decode is ambiguous. The mapping collapses every non-alphanumeric
+ * to `_`, so a `_` surviving in the decoded address cannot be told apart from
+ * a folded `.`/`+`/etc. (`FIRST_DOT_LAST_AT_GMAIL_DOT_COM` decodes to
+ * `first_dot_last@gmail.com`, which round-trips — wrongly — under the bare
+ * re-encode check; review BLOCKER 1). Only a fully unambiguous decode — local
+ * and domain pure `[a-z0-9]`, dots in the domain only — is trusted.
+ */
+function emailFromTokenKey(key) {
+    const prefix = 'CLAUDE_CODE_OAUTH_TOKEN_';
+    if (!key.startsWith(prefix))
+        return null;
+    const slug = key.slice(prefix.length);
+    const [local, domain, ...rest] = slug.split('_AT_');
+    if (!local || !domain || rest.length > 0)
+        return null;
+    const email = `${local}@${domain.replace(/_DOT_/g, '.')}`.toLowerCase();
+    if (!/^[a-z0-9]+@[a-z0-9.]+$/.test(email))
+        return null;
+    if (claudeAccountTokenKey(email) !== key)
+        return null;
+    return email;
+}
 /**
  * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
  * any version home's `.claude.json`. This is what lets `agents accounts attach`
@@ -167,14 +256,29 @@ export function seedClaudeWorkerHomeIdentity(versionHome, email) {
         try {
             doc = JSON.parse(fs.readFileSync(p, 'utf-8'));
         }
-        catch {
-            // Missing or unreadable at this location — write a fresh minimal document.
+        catch (err) {
+            // Missing file → write a fresh minimal document. A file that EXISTS but
+            // does not parse is being concurrently rewritten by Claude Code itself —
+            // skip it rather than overwrite a live config with the minimal doc.
+            if (err.code !== 'ENOENT')
+                continue;
         }
         const existing = (doc.oauthAccount && typeof doc.oauthAccount === 'object'
             ? doc.oauthAccount
             : {});
         doc.oauthAccount = { ...existing, emailAddress: trimmed };
         fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, JSON.stringify(doc));
+        // Temp-write + rename: a reader mid-write never sees a truncated doc.
+        const tmp = `${p}.agents-${process.pid}.tmp`;
+        try {
+            fs.writeFileSync(tmp, JSON.stringify(doc));
+            fs.renameSync(tmp, p);
+        }
+        catch {
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch { /* best effort */ }
+        }
     }
 }

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

@@ -12,9 +12,37 @@
  * separate copy on purpose: the CLI does not import across packages.
  */
 import type { DeviceProfile } from './registry.js';
-/** Default per-device probe budget. Short enough that the list never hangs on a
- * wedged box, long enough for a cold relayed SSH handshake. */
+/** Default per-device probe budget, for a device reachable over a DIRECT
+ * Tailscale path. Short enough that the list never hangs on a wedged box. */
 export declare const PROBE_TIMEOUT_MS = 2500;
+/**
+ * Probe budget for a device whose last handshake was DERP-relayed
+ * ({@link DeviceTailscale.direct} === false).
+ *
+ * This constant used to not exist: 2.5s was applied to every device and its
+ * docstring claimed to be "long enough for a cold relayed SSH handshake". That
+ * was false, and on a fleet with no direct paths it broke `--device auto`
+ * outright (PHNX-3682). Measured on a 9-box relayed fleet, probed in parallel
+ * with cold paths: 1686/1805/1914/2688/2706/2749/3082/5586/6588 ms — six of nine
+ * over budget, every one of them healthy (rc=0 within 10s). Warm, the same
+ * probes take 512-872ms, which is what made the failure intermittent.
+ *
+ * A relayed hop pays DERP path setup on top of the TCP+SSH handshake, so it
+ * gets the same budget the readiness probe already allows
+ * (`READY_PROBE_TIMEOUT_MS`) rather than the direct-path one.
+ */
+export declare const RELAYED_PROBE_TIMEOUT_MS = 8000;
+/**
+ * The probe budget for one device. A relayed peer gets
+ * {@link RELAYED_PROBE_TIMEOUT_MS}; a direct (or unknown-path) peer keeps the
+ * tight {@link PROBE_TIMEOUT_MS}. Windows keeps its own larger budget, which
+ * already exceeds both.
+ *
+ * `direct` is only meaningful when a tailscale snapshot exists — a
+ * `via:"manual"` device never gets a peer entry, so absence is "unknown path",
+ * not "relayed", and must not silently widen every manual device's budget.
+ */
+export declare function probeBudgetMs(device: DeviceProfile): number;
 /** Windows probe budget. The first CIM query of a PowerShell session pays a
  * "Preparing modules for first use" cost on top of PowerShell startup, which
  * routinely blows the 2.5s POSIX budget on a relayed connection. */
@@ -35,6 +63,14 @@ export declare function localProbeInvocation(platform: NodeJS.Platform): {
 export interface DeviceStats {
     host: string;
     reachable: boolean;
+    /**
+     * The probe exceeded its budget rather than being refused or unresolvable.
+     * Only meaningful when `reachable` is false — it separates "this box did not
+     * answer in time" from "this box actively could not be reached", so callers
+     * report a slow link honestly instead of calling a healthy device offline
+     * (PHNX-3682).
+     */
+    timedOut?: boolean;
     loadAvg1?: number;
     ncpu?: number;
     /** Load normalized to core count (the "has room" number): loadAvg1 / ncpu *

package/dist/lib/devices/health.js

@@ -13,9 +13,43 @@
  */
 import { execFile } from 'child_process';
 import { buildSshInvocation, writeAskpassShim } from './connect.js';
-/** Default per-device probe budget. Short enough that the list never hangs on a
- * wedged box, long enough for a cold relayed SSH handshake. */
+/** Default per-device probe budget, for a device reachable over a DIRECT
+ * Tailscale path. Short enough that the list never hangs on a wedged box. */
 export const PROBE_TIMEOUT_MS = 2_500;
+/**
+ * Probe budget for a device whose last handshake was DERP-relayed
+ * ({@link DeviceTailscale.direct} === false).
+ *
+ * This constant used to not exist: 2.5s was applied to every device and its
+ * docstring claimed to be "long enough for a cold relayed SSH handshake". That
+ * was false, and on a fleet with no direct paths it broke `--device auto`
+ * outright (PHNX-3682). Measured on a 9-box relayed fleet, probed in parallel
+ * with cold paths: 1686/1805/1914/2688/2706/2749/3082/5586/6588 ms — six of nine
+ * over budget, every one of them healthy (rc=0 within 10s). Warm, the same
+ * probes take 512-872ms, which is what made the failure intermittent.
+ *
+ * A relayed hop pays DERP path setup on top of the TCP+SSH handshake, so it
+ * gets the same budget the readiness probe already allows
+ * (`READY_PROBE_TIMEOUT_MS`) rather than the direct-path one.
+ */
+export const RELAYED_PROBE_TIMEOUT_MS = 8_000;
+/**
+ * The probe budget for one device. A relayed peer gets
+ * {@link RELAYED_PROBE_TIMEOUT_MS}; a direct (or unknown-path) peer keeps the
+ * tight {@link PROBE_TIMEOUT_MS}. Windows keeps its own larger budget, which
+ * already exceeds both.
+ *
+ * `direct` is only meaningful when a tailscale snapshot exists — a
+ * `via:"manual"` device never gets a peer entry, so absence is "unknown path",
+ * not "relayed", and must not silently widen every manual device's budget.
+ */
+export function probeBudgetMs(device) {
+    if (device.shell === 'powershell')
+        return WIN_PROBE_TIMEOUT_MS;
+    return device.tailscale && device.tailscale.direct === false
+        ? RELAYED_PROBE_TIMEOUT_MS
+        : PROBE_TIMEOUT_MS;
+}
 /** Windows probe budget. The first CIM query of a PowerShell session pays a
  * "Preparing modules for first use" cost on top of PowerShell startup, which
  * routinely blows the 2.5s POSIX budget on a relayed connection. */
@@ -227,10 +261,14 @@ export function probeDeviceStats(device, opts = {}) {
         execFile('ssh', args, {
             encoding: 'utf-8',
             env: { ...process.env, ...env },
-            timeout: opts.timeoutMs ?? (isWin ? WIN_PROBE_TIMEOUT_MS : PROBE_TIMEOUT_MS),
+            timeout: opts.timeoutMs ?? probeBudgetMs(device),
         }, (err, stdout) => {
-            if (err || !stdout)
-                return resolve({ host, reachable: false, fetchedAt });
+            // execFile kills an over-budget child with a signal; that is a slow link,
+            // not an unreachable box, and the two must not read the same downstream.
+            if (err || !stdout) {
+                const timedOut = Boolean(err && err.killed);
+                return resolve(timedOut ? { host, reachable: false, timedOut, fetchedAt } : { host, reachable: false, fetchedAt });
+            }
             resolve(isWin ? parseWinProbeOutput(host, stdout, fetchedAt) : parseProbeOutput(host, stdout, fetchedAt));
         });
     });

package/dist/lib/devices/worker-pick.d.ts

@@ -2,7 +2,7 @@ import { type DevicePlacementSignal } from '../teams/scheduler.js';
 /** Why a candidate was dropped, for the fail-loud error message. */
 export interface WorkerExclusion {
     device: string;
-    reason: 'unreachable' | 'overloaded' | 'wrong-platform' | 'interactive';
+    reason: 'unreachable' | 'probe timed out' | 'overloaded' | 'wrong-platform' | 'interactive';
 }
 export interface WorkerPickPlan {
     /** The chosen device name. Never the local box unless it is an auto-pool member. */

package/dist/lib/devices/worker-pick.js

@@ -79,7 +79,10 @@ export async function resolveWorkerDevice(opts = {}) {
     const eligible = onPlatform.filter((device) => {
         const signal = signals.get(device);
         if (signal?.reachable !== true) {
-            excluded.push({ device, reason: 'unreachable' });
+            // A probe killed for exceeding its budget says nothing about whether the
+            // box is up — on a relayed fleet it usually is. Report the two apart so
+            // the message points at the link, not at a fleet outage (PHNX-3682).
+            excluded.push({ device, reason: signal?.timedOut ? 'probe timed out' : 'unreachable' });
             return false;
         }
         if (signal.headroom === 'loaded') {

package/dist/lib/exec.js

@@ -40,6 +40,7 @@ import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js
 import { resolveConfigVersion } from './harness/exec-config-version.js';
 import { getAccountInfo } from './agents.js';
 import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset } from './accounting/usage.js';
+import { bootMark, flushBootProfile } from './boot-profile.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -1733,6 +1734,7 @@ async function emitRunLaunch(ctx) {
     }
 }
 async function spawnAgent(options) {
+    bootMark('spawn-agent:enter');
     // Assign a known session id up front for agents that accept one, so the
     // launcher can record an EXACT pid -> session mapping (see pid-registry) —
     // otherwise the headless `ag sessions --active` path can only guess
@@ -1867,6 +1869,7 @@ async function spawnAgent(options) {
     });
     if (tmuxWrap.kind === 'wrap') {
         timer.mark('startup');
+        flushBootProfile('spawn');
         try {
             const result = await runInTmux(options, executable, args);
             timer.end({ exitCode: result.exitCode, status: result.exitCode === 0 ? 'success' : 'failed' });
@@ -1898,6 +1901,7 @@ async function spawnAgent(options) {
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
         const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
         const spawnArgs = useShell ? [] : args;
+        flushBootProfile('spawn');
         const child = spawn(spawnCommand, spawnArgs, {
             cwd: options.cwd || process.cwd(),
             stdio,