@phnx-labs/agents-cli 1.22.64 → 1.22.65

package/dist/lib/accounting/usage.js

@@ -437,8 +437,22 @@ export async function getUsageInfoForIdentity(input, opts) {
     // stale snapshot here is safe, and an absent one reports
     // {@link USAGE_NOT_COLLECTED_MARKER}.
     if (readOnly) {
-        if (cached)
+        // A row carries a CONFIRMED reading when it has a fresh window, a
+        // subscription plan (meterless-healthy, e.g. Grok's tier), or a live refusal
+        // (out_of_credits / session_limit). Those report `usageError: null`.
+        if (cached && (cached.windows.length > 0 || cached.plan || cached.unavailable)) {
             return { snapshot: cached, error: null };
+        }
+        // A row whose ONLY content is last-known stale readings — the all-expired
+        // Claude case, its windows moved to `staleWindows` (view-only) so the
+        // TERMINAL view still renders the number with its age — must NOT read as a
+        // healthy account. `staleWindows` is deliberately excluded from `--json`
+        // (which projects only `windows`), so keep `usageError` non-null: a consumer
+        // polling `agents view --json` must still see the staleness signal, the exact
+        // RUSH-2858 weeks-stale case this marker exists for. The snapshot is still
+        // returned, so the human view is unaffected.
+        if (cached)
+            return { snapshot: cached, error: USAGE_NOT_COLLECTED_MARKER };
         return { snapshot: null, error: USAGE_NOT_COLLECTED_MARKER };
     }
     // Explicit refresh: block on the shared device collector.
@@ -590,14 +604,25 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         // multi-meter agent cannot force the whole table to wrap.
         const selected = pickCompactUsageWindows(snapshot.windows, opts?.maxWindows);
         const hidden = Math.max(0, snapshot.windows.filter((w) => w.key !== 'sonnet_week').length - selected.length);
+        // Last-known windows the freshness gate dropped (see UsageSnapshot.staleWindows).
+        // Rendered with an age suffix so a stale reading stays visible instead of a
+        // bare "unavailable"; never in `snapshot.windows`, so routing never sees them.
+        const now = new Date();
+        const staleWindows = snapshot.staleWindows ?? [];
+        const staleByKey = new Map(staleWindows.map((w) => [w.key, w]));
         const expected = opts?.expectedWindows;
         const windowsToRender = expected
-            ? expected.map(({ key, shortLabel }) => ({ window: selected.find((item) => item.key === key), shortLabel }))
-            : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
-        const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
+            ? expected.map(({ key, shortLabel }) => ({ key, window: selected.find((item) => item.key === key), shortLabel }))
+            : selected.map((window) => ({ key: window.key, window, shortLabel: window.shortLabel }));
+        const windowParts = windowsToRender.map(({ key, window, shortLabel }, index) => {
             if (!window) {
-                const missing = chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
-                return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
+                // A window we expected but have no fresh reading for: render the
+                // last-known value with its age if we still have it, else "unavailable".
+                const stale = staleByKey.get(key);
+                const rendered = stale
+                    ? renderStaleUsageWindow(stale, snapshot.capturedAt, shortLabel, now)
+                    : chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
+                return index < windowsToRender.length - 1 ? padToWidth(rendered, 20) : rendered;
             }
             const bar = renderCompactUsageBar(window.usedPercent);
             const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
@@ -611,6 +636,16 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         if (windowParts.length > 0) {
             parts.push(windowParts.join('  '));
         }
+        else if (staleWindows.length > 0) {
+            // No fresh bars, but we have last-known readings (e.g. Grok's weekly bar
+            // from an ended billing period): show them with an age suffix rather than
+            // the "run once to refresh" hint, which hid a number we actually had.
+            const cap = opts?.maxWindows ?? staleWindows.length;
+            const rendered = staleWindows
+                .slice(0, cap)
+                .map((w) => renderStaleUsageWindow(w, snapshot.capturedAt, w.shortLabel, now));
+            parts.push(rendered.join('  '));
+        }
         else if (snapshot.refreshHint) {
             parts.push(chalk.dim(snapshot.refreshHint));
         }
@@ -1879,9 +1914,12 @@ function serializeClaudeUsageSnapshot(snapshot) {
  * have burned since. Zeroing-but-keeping it (the previous behavior) rendered a
  * weeks-frozen cache as "S: 0% (now)" with `deriveUsageStatusFromSnapshot` →
  * 'available', so a genuinely rate-limited account read as an idle dispatch
- * candidate (RUSH-2858). Dropping mirrors the Grok collector, and an all-expired
- * snapshot deserializes to null so `readClaudeUsageCache` deletes the entry and
- * callers surface "usage unavailable" plus the recorded throttle reason.
+ * candidate (RUSH-2858). Dropping keeps them out of `windows` (routing stays
+ * blind), but they are preserved on `staleWindows` so the view can render the
+ * last-known number with its age instead of a bare "unavailable" — a row that
+ * carries only stale windows therefore survives (it is worth showing), and only
+ * a row with NOTHING to show — no fresh window, no stale window, no plan, no
+ * refusal — deserializes to null so `readClaudeUsageCache` deletes it.
  *
  * A row that carries a plan survives even with no fresh windows: the plan is a
  * truthful reading in its own right, and losing it is what made the cached view
@@ -1889,16 +1927,21 @@ function serializeClaudeUsageSnapshot(snapshot) {
  */
 function deserializeClaudeUsageSnapshot(snapshot, now) {
     const capturedAt = parseDateValue(snapshot.capturedAt);
-    const windows = snapshot.windows
-        .map((window) => ({
+    const deserialized = snapshot.windows.map((window) => ({
         key: window.key,
         label: window.label,
         shortLabel: window.shortLabel,
         usedPercent: window.usedPercent,
         resetsAt: parseDateValue(window.resetsAt),
         windowMinutes: window.windowMinutes,
-    }))
-        .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+    }));
+    const windows = deserialized.filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+    // The dropped windows are still the LAST reading we saw for those meters —
+    // routing must not trust them (they stay out of `windows`), but the view
+    // renders them with an age suffix rather than a bare "unavailable" (see
+    // UsageSnapshot.staleWindows). Skip any meter that already has a fresh row.
+    const freshKeys = new Set(windows.map((window) => window.key));
+    const staleWindows = deserialized.filter((window) => !freshKeys.has(window.key) && !isCachedUsageWindowFresh(window, capturedAt, now));
     const unavailable = deserializeUnavailable(snapshot.unavailable, now);
     // A windowless row is not automatically worthless. Grok's collector reports
     // the subscription tier and no meters at all, so treating "no fresh windows"
@@ -1910,7 +1953,11 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
     // and `deriveUsageStatusFromSnapshot` still returns null for zero windows, so
     // it can never read as a 0% bar or an "available" badge (the RUSH-2858
     // property that made expired windows drop in the first place).
-    if (windows.length === 0 && !unavailable && !snapshot.plan && !snapshot.refreshHint) {
+    if (windows.length === 0 &&
+        staleWindows.length === 0 &&
+        !unavailable &&
+        !snapshot.plan &&
+        !snapshot.refreshHint) {
         return null;
     }
     return {
@@ -1918,6 +1965,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         sourceLabel: CACHED_CLAUDE_USAGE_SOURCE_LABEL,
         capturedAt,
         windows,
+        staleWindows: staleWindows.length > 0 ? staleWindows : undefined,
         plan: snapshot.plan ?? null,
         refreshHint: snapshot.refreshHint ?? null,
         unavailable,
@@ -2246,6 +2294,56 @@ function formatResetHint(date) {
     const days = Math.round(hours / 24);
     return `${days}d`;
 }
+/**
+ * Compact elapsed-time label for a stale reading's age: "30m", "6h", "2d".
+ * Coarse single-unit like {@link formatResetHint}, floored at "1m" so a
+ * just-expired window never reads "0m".
+ */
+function formatAgeShort(diffMs) {
+    const mins = Math.max(1, Math.round(diffMs / 60000));
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.round(hours / 24);
+    return `${days}d`;
+}
+/**
+ * Staleness suffix for a last-known window the freshness gate dropped. A window
+ * whose reset/period boundary passed while the sample itself is still inside its
+ * `windowMinutes` rolled OVER — the number describes a period that is done, so
+ * name it ("period ended 1h ago", e.g. Grok's weekly billing period). A window
+ * that aged past its own `windowMinutes` (Claude's 5h session read never
+ * refreshed in time) is a stale sample of a still-rolling window, so report the
+ * capture age ("6h old"). Falls back to the reset age, then a bare "stale".
+ */
+function formatStaleWindowSuffix(window, capturedAt, now) {
+    const resetPassed = !!window.resetsAt && window.resetsAt.getTime() <= now.getTime();
+    const captureExpired = !!capturedAt &&
+        window.windowMinutes !== null &&
+        capturedAt.getTime() + window.windowMinutes * 60 * 1000 <= now.getTime();
+    if (resetPassed && !captureExpired) {
+        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+    }
+    if (capturedAt)
+        return `${formatAgeShort(now.getTime() - capturedAt.getTime())} old`;
+    if (resetPassed)
+        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+    return 'stale';
+}
+/**
+ * Render a dropped-but-last-known window as "S: ▍░░░░ 30% · 6h old": the gauge
+ * and percentage exactly as a live bar, then a dim staleness suffix so the
+ * number is always visible and unmistakably not current. VIEW-ONLY — these
+ * windows are never in `snapshot.windows`, so routing never sees them.
+ */
+function renderStaleUsageWindow(window, capturedAt, shortLabel, now) {
+    const bar = renderCompactUsageBar(window.usedPercent);
+    const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
+    const suffix = formatStaleWindowSuffix(window, capturedAt, now);
+    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct} ${chalk.dim(`· ${suffix}`)}`;
+}
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {
     const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -2308,8 +2406,13 @@ async function getGrokUsageInfo(options) {
         // (see readLatestGrokBilling).
         const now = new Date();
         const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
+        // A window from an ended billing period is the LAST reading we saw — routing
+        // must not trust it (kept out of `windows`), but the view renders it with a
+        // "period ended Xh ago" suffix instead of the bare refresh hint. Only when
+        // there is nothing at all to show does the refresh hint stand alone.
+        const staleWindows = match.windows.filter((window) => !isCachedUsageWindowFresh(window, match.capturedAt, now));
         const version = options?.cliVersion;
-        const refreshHint = windows.length === 0
+        const refreshHint = windows.length === 0 && staleWindows.length === 0
             ? `run grok${version ? `@${version}` : ''} once to refresh usage`
             : null;
         return {
@@ -2318,6 +2421,7 @@ async function getGrokUsageInfo(options) {
                 sourceLabel: 'last seen in Grok logs',
                 capturedAt: match.capturedAt,
                 windows,
+                staleWindows: staleWindows.length > 0 ? staleWindows : undefined,
                 plan: match.subscriptionTier,
                 refreshHint,
             },

package/dist/lib/agent-spec/agents.js

@@ -1513,15 +1513,30 @@ function credentialFileExistsUnder(agentId, home) {
     const alternatives = CREDENTIAL_FILE_SEGMENTS[agentId];
     if (!alternatives)
         return false;
-    for (const segments of alternatives) {
+    const hasSegment = alternatives.some((segments) => {
         const p = path.join(home, ...segments);
         try {
-            if (fs.existsSync(p))
-                return true;
+            return fs.existsSync(p);
         }
-        catch { /* unreadable */ }
-    }
-    return false;
+        catch {
+            return false;
+        }
+    });
+    if (!hasSegment)
+        return false;
+    // Claude's `.claude.json` is account METADATA Claude Code writes on any
+    // launch, not the credential itself — a version can carry stale identity
+    // there (e.g. install-time carry-forward) with no usable credential behind
+    // it: a failed OAuth refresh blanks `.credentials.json`, and a Linux worker
+    // can be missing BOTH `.credentials.json` and the `.oauth_token` setup-token
+    // file entirely (PHNX-3502). `credentialPresence` promises to mirror what a
+    // real launch would find, so it must fail whenever `isClaudeCredentialFileBlank`
+    // — the SAME floor `getAccountInfo` applies — would. On macOS that floor is a
+    // no-op (Keychain-only, always "not blank"), so this reduces to the identity
+    // check above, unchanged.
+    if (agentId === 'claude')
+        return !isClaudeCredentialFileBlank(home);
+    return true;
 }
 /**
  * File-presence probe for an agent's credential, split by location: whether it

package/dist/lib/daemon-ticks.js

@@ -114,17 +114,21 @@ export async function runFleetCacheWarmTick() {
  */
 export async function runUsageRefreshTick() {
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
-    const { writeClaudeUsageCache } = await import('./accounting/usage.js');
+    const { writeClaudeUsageCache, readClaudeUsageCache } = await import('./accounting/usage.js');
     const { usageRateLimitedUntil } = await import('./usage-backoff.js');
     const r = await runUsageRefresh({
         listAccounts: buildLocalUsageAccounts,
         writeUsageCache: writeClaudeUsageCache,
         backoffUntil: (agentId, usageKey) => usageRateLimitedUntil(agentId, Date.now(), usageKey),
+        // The free statusline ingest of a live `agents run` writes this same cache,
+        // so a recent capture means the account is already fresh at zero API cost —
+        // the refresher re-derives headroom from it and skips the API fetch.
+        readCachedSnapshot: (usageKey) => readClaudeUsageCache(usageKey),
     });
     const { listProfiles } = await import('./profiles.js');
     const { refreshDueByokUsage } = await import('./byok-usage.js');
     const byok = await refreshDueByokUsage(listProfiles());
-    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
+    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped, ${r.skippedBudget} over-budget, ${r.skippedFresh} statusline-fresh; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
 }
 /**
  * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session

package/dist/lib/feed-broadcast.d.ts

@@ -42,6 +42,8 @@ export interface FeedBroadcastContext {
     level: FeedPostLevel;
     /** Tracker id for the work, e.g. `RUSH-2081`. */
     ticket?: string;
+    /** Canonical clickable tracker URL for `ticket`, when the tracker can resolve it. */
+    ticketUrl?: string;
     /** Repo/project the post came from. */
     project?: string;
     agent?: string;

package/dist/lib/feed-broadcast.js

@@ -38,6 +38,7 @@ import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } fro
 import { lookupTransport } from './channels/resolve.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { sendToOwner } from './notify.js';
+import { linearIssueUrl } from './session/linear.js';
 import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -78,6 +79,7 @@ export function blockBroadcastContext(block, extras = {}) {
         text,
         level: 'important',
         ticket: block.ticket,
+        ticketUrl: linearIssueUrl(block.ticket),
         project: extras.project,
         agent: extras.agent,
         host: block.host,
@@ -118,7 +120,7 @@ export function blockDeliveryFailure(blocked, outcomes) {
     }
     return undefined;
 }
-const PLACEHOLDER = /\{([a-z]+)\}/g;
+const PLACEHOLDER = /\{([a-z_]+)\}/g;
 /**
  * Short host label for a phone line — strip user@ and domain so
  * `muqsit@mac-mini.tailnet.ts.net` reads as `mac-mini`.
@@ -241,7 +243,9 @@ export function composeBroadcastMessage(ctx) {
     const head = title || body;
     const mid = title && body && title !== body ? body : undefined;
     const footer = composeBroadcastFooter(ctx);
-    const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
+    const links = [ctx.ticketUrl, ...(ctx.links ?? [])]
+        .filter((l) => !!l && /^https?:\/\//i.test(l))
+        .filter((l, i, all) => all.indexOf(l) === i);
     // The action block: the one thing the operator can act on from a phone. Show the
     // choices, then what happens if they do not answer. Deliberately NOT a CLI command
     // (`agents focus <id>` is unusable from a phone) -- the safe default is the real
@@ -256,7 +260,7 @@ export function composeBroadcastMessage(ctx) {
         : undefined;
     const action = [choices, fallback].filter(Boolean).join('\n') || undefined;
     // Link trail after the "Sent from" footer so the human sentence stays at the top.
-    const trail = [footer, link].filter(Boolean);
+    const trail = [footer, ...links].filter(Boolean);
     const parts = [];
     if (head)
         parts.push(head);
@@ -285,6 +289,7 @@ function templateVars(ctx) {
         title: ctx.title,
         text: ctx.text,
         ticket: ctx.ticket,
+        ticket_url: ctx.ticketUrl,
         project: ctx.project,
         agent: ctx.agent,
         host: ctx.host,
@@ -339,7 +344,20 @@ export function renderSinkMessage(template, ctx) {
     });
     if (missing)
         return undefined;
-    const text = rendered.trim();
+    const seenUrls = new Set();
+    const text = rendered
+        .trim()
+        .split('\n')
+        .filter((line) => {
+        const value = line.trim();
+        if (!/^https?:\/\/\S+$/i.test(value))
+            return true;
+        if (seenUrls.has(value))
+            return false;
+        seenUrls.add(value);
+        return true;
+    })
+        .join('\n');
     return text || undefined;
 }
 /**

package/dist/lib/harness/adapters/claude.js

@@ -28,28 +28,33 @@ export const claudeAdapter = {
         // The `auth` bundle's setup-token exists so a run with NO human present
         // authenticates without the Touch-ID-gated login item — usage probes,
         // routines, dispatched runs (claude-account-token.ts). It is a WORKER
-        // credential. Two kinds of run defer to the per-version login instead:
+        // credential. Exactly one kind of run defers to the per-version login
+        // instead: ANY run on a `personal`/`desktop` (headed) device — the user's
+        // own interactive box (zion), marked `config.role: personal`. That box
+        // holds a real per-version login and is the single origin of it, so every
+        // run there — interactive TUI OR a headless one-shot like `agents run
+        // claude "fix the bug"` — MUST use that login, not the setup-token. Keying
+        // the credential on DEVICE ROLE, not run mode, is RUSH-2395's fix: gating on
+        // `ctx.interactive` alone sent a headless run on the laptop onto the
+        // setup-token and hijacked the login.
         //
-        //   1. An interactive run: a human is at the TTY, and their per-version login
-        //      is the credential they established and expect. Overriding it made
-        //      `/status` report `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal
-        //      machine and took every hand-driven session off that login.
-        //   2. ANY run on a `personal` device — the user's own interactive box (zion),
-        //      marked `config.role: personal`. That box holds a real per-version login
-        //      and is the single origin of it, so every run there — interactive TUI OR
-        //      a headless one-shot like `agents run claude "fix the bug"` — MUST use
-        //      that login, not the setup-token. Gating on run mode ALONE
-        //      (resolveInteractive = "this opens a TUI", NOT "a human is present")
-        //      sent a headless run on the laptop onto the setup-token and hijacked the
-        //      login. Keying the credential on DEVICE ROLE is the fix — RUSH-2395.
+        // A WORKER device carries no such login regardless of interactive/headless:
+        // an interactive run there is a remotely dispatched TUI (`agents run claude
+        // --interactive --device <worker>`), not a human sitting at that box's own
+        // Keychain-trusted session — the same worker credential headless runs use is
+        // the only credential that exists to authenticate it. Treating `interactive`
+        // as "defer to native login" regardless of device role left a keychain-less
+        // worker with NO injected token and a per-version `.credentials.json` that
+        // was never written, so the run landed on Claude Code's login screen instead
+        // of authenticating (PHNX-3502).
         //
         // macOS cannot cheaply confirm a home's login first (probing the Keychain
         // raises an authorization sheet per installed version on the `agents run` hot
-        // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
-        // Claude Code, which reads its own ACL-trusted login item without a prompt and
-        // asks a present human to log in only if the login is missing.
+        // path — agents.ts `isClaudeCredentialFileBlank`), so the headed-device path
+        // defers to Claude Code, which reads its own ACL-trusted login item without a
+        // prompt and asks a present human to log in only if the login is missing.
         const headedDevice = isHeadedDeviceRole(ctx.deviceRole);
-        if (ctx.interactive || headedDevice) {
+        if (headedDevice) {
             // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
             // headless agent's shell inherits that agent's injected value via
             // sanitizeProcessEnv(process.env) and would keep authenticating as it,
@@ -66,16 +71,17 @@ export const claudeAdapter = {
             }
         }
         else {
-            // Headless run on a NON-personal device (worker, dispatched, provisioned
-            // box): mirror the routines path (`runner.ts`) UNCONDITIONALLY. Inject the
-            // per-account setup-token when one resolves — it replaces any ambient shared
-            // value inherited from the launcher. When NONE resolves, STRIP the ambient
-            // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
-            // authenticate as the shared, rotating token an earlier version of this path
-            // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.
-            // A missing login then fails loud (401) against this home's own credential
-            // instead of quietly borrowing another's. options.env still wins below for an
-            // explicit caller override.
+            // Any run on a NON-personal device (worker, dispatched, provisioned box) —
+            // interactive OR headless: mirror the routines path (`runner.ts`)
+            // UNCONDITIONALLY. Inject the per-account setup-token when one resolves —
+            // it replaces any ambient shared value inherited from the launcher. When
+            // NONE resolves, STRIP the ambient CLAUDE_CODE_OAUTH_TOKEN so a run on a
+            // provisioned box can never silently authenticate as the shared, rotating
+            // token an earlier version of this path let through — the RUSH-1822
+            // fleet-wide-logout hazard, tracked by RUSH-2360. A missing login then
+            // fails loud (401) against this home's own credential instead of quietly
+            // borrowing another's. options.env still wins below for an explicit
+            // caller override.
             if (setupToken) {
                 result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
             }

package/dist/lib/hosts/passthrough.d.ts

@@ -25,6 +25,23 @@ export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 interface RemoteSpec {
     /** Flags appended when running non-interactively (no local TTY / `--no-tty`). */
     nonInteractive?: string[];
+    /**
+     * Pure read-only RENDER command: draws a screen and exits, never reads stdin.
+     * Forwarded over a PLAIN PIPE rather than `ssh -tt` (a forced PTY), because the
+     * PTY teardown + local-terminal restore on a CLEAN exit wipes the just-drawn
+     * output — so the render "flashes and vanishes" the moment it finishes
+     * (PHNX-3583). Over a pipe the output persists exactly as the working non-TTY
+     * path already proves; color and terminal geometry are forced into the remote
+     * env so it still comes back colored and correctly wrapped
+     * ({@link renderForwardDecision}).
+     */
+    render?: boolean;
+    /**
+     * For a {@link render} command with a NARROW interactive sub-path, return `true`
+     * when THIS argv hits it — the PTY is kept for that one invocation. Absent means
+     * the command never prompts, so it is always safe to forward over a pipe.
+     */
+    interactiveWhen?: (forwarded: string[]) => boolean;
 }
 /**
  * First-class groups that run transparently on a remote via SSH when
@@ -58,6 +75,33 @@ export declare const OWN_HOST_COMMANDS: Set<string>;
  * (RUSH-2864).
  */
 export declare function buildPassthroughForwardedArgs(command: string, allArgs: string[], interactive: boolean): string[];
+/**
+ * Decide whether a `--device` passthrough should forward over a PLAIN PIPE
+ * instead of a PTY, and what color/geometry env to inject when it does.
+ *
+ * A pure read-only render ({@link RemoteSpec.render}) drawn under a forced
+ * `ssh -tt` PTY vanishes on clean exit: the PTY teardown + local-terminal
+ * restore (`restoreLocalTerminal` in ssh-exec.ts) wipes the output the command
+ * just drew (PHNX-3583). The non-TTY (piped) path never had this problem, so a
+ * render command takes it too — but only when a human is actually at a real
+ * local terminal (`isTTY` and not `--no-tty`); a genuinely piped local run is
+ * already on the pipe path and wants neither color nor forced geometry.
+ *
+ * A render command's narrow interactive sub-path ({@link RemoteSpec.interactiveWhen},
+ * e.g. `view --prune`'s confirm) keeps the PTY. When forwarding over a pipe the
+ * remote sees `isTTY=false`, so chalk goes colorless and `terminalWidth()` has no
+ * `$COLUMNS` to read; `FORCE_COLOR`/`COLUMNS`/`LINES` restore both. `FORCE_COLOR`
+ * is withheld under `--json` so it can never taint machine-readable output.
+ */
+export declare function renderForwardDecision(command: string, allArgs: string[], io: {
+    isTTY: boolean;
+    noTty: boolean;
+    columns?: number;
+    rows?: number;
+}): {
+    noPty: boolean;
+    env?: Record<string, string>;
+};
 /** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
 export interface FleetPassthroughOptions {
     /** Override the device registry loader (tests). */

package/dist/lib/hosts/passthrough.js

@@ -54,14 +54,23 @@ export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
  * `add`/`use`/`list`, and none) and were removed.
  */
 export const REMOTE_PASSTHROUGH = {
-    // inspect
-    view: {},
-    inspect: {},
-    doctor: {},
+    // inspect — pure read-only renders: forward over a pipe, never a forced PTY
+    // (PHNX-3583), so the drawn output persists instead of vanishing on exit.
+    view: {
+        render: true,
+        // Only `--prune` (without --yes/--dry-run) asks a confirm(); that one
+        // invocation needs the PTY. Every other `view` is a pure render.
+        interactiveWhen: (f) => f.includes('--prune') &&
+            !f.includes('--dry-run') &&
+            !f.includes('--yes') &&
+            !f.includes('-y'),
+    },
+    inspect: { render: true },
+    doctor: { render: true },
     check: {},
     list: {},
     usage: {},
-    insights: {},
+    insights: { render: true },
     // config / resources
     config: {},
     sync: { nonInteractive: ['--yes'] },
@@ -162,6 +171,41 @@ export function buildPassthroughForwardedArgs(command, allArgs, interactive) {
     }
     return forwarded;
 }
+/**
+ * Decide whether a `--device` passthrough should forward over a PLAIN PIPE
+ * instead of a PTY, and what color/geometry env to inject when it does.
+ *
+ * A pure read-only render ({@link RemoteSpec.render}) drawn under a forced
+ * `ssh -tt` PTY vanishes on clean exit: the PTY teardown + local-terminal
+ * restore (`restoreLocalTerminal` in ssh-exec.ts) wipes the output the command
+ * just drew (PHNX-3583). The non-TTY (piped) path never had this problem, so a
+ * render command takes it too — but only when a human is actually at a real
+ * local terminal (`isTTY` and not `--no-tty`); a genuinely piped local run is
+ * already on the pipe path and wants neither color nor forced geometry.
+ *
+ * A render command's narrow interactive sub-path ({@link RemoteSpec.interactiveWhen},
+ * e.g. `view --prune`'s confirm) keeps the PTY. When forwarding over a pipe the
+ * remote sees `isTTY=false`, so chalk goes colorless and `terminalWidth()` has no
+ * `$COLUMNS` to read; `FORCE_COLOR`/`COLUMNS`/`LINES` restore both. `FORCE_COLOR`
+ * is withheld under `--json` so it can never taint machine-readable output.
+ */
+export function renderForwardDecision(command, allArgs, io) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    const localTty = io.isTTY && !io.noTty;
+    if (!spec?.render || !localTty)
+        return { noPty: false };
+    const forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    if (spec.interactiveWhen?.(forwarded))
+        return { noPty: false };
+    const env = {};
+    if (!allArgs.includes('--json'))
+        env.FORCE_COLOR = '1';
+    if (io.columns && io.columns > 0)
+        env.COLUMNS = String(io.columns);
+    if (io.rows && io.rows > 0)
+        env.LINES = String(io.rows);
+    return { noPty: true, env: Object.keys(env).length ? env : undefined };
+}
 /** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
 function syntheticHost(target) {
     const at = target.indexOf('@');
@@ -554,10 +598,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         return true;
     }
     const target = sshTargetFor(host);
+    // A read-only render (view/inspect/insights/doctor) must forward over a plain
+    // pipe even from a real terminal — a forced `ssh -tt` PTY wipes its output on
+    // clean exit (PHNX-3583). renderForwardDecision returns that choice plus the
+    // color/geometry env that keeps a piped render colored and correctly wrapped.
+    const { noPty: renderNoPty, env: renderForwardEnv } = renderForwardDecision(command, allArgs, {
+        isTTY: !!process.stdout.isTTY,
+        noTty: allArgs.includes('--no-tty'),
+        columns: process.stdout.columns,
+        rows: process.stdout.rows,
+    });
     // Interactive only when our own stdout is a terminal and the caller didn't opt
     // out — otherwise force the command's non-interactive path so no half-drawn
-    // picker is piped into a file or another program.
-    const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
+    // picker is piped into a file or another program. A no-PTY render is
+    // non-interactive by construction.
+    const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty') && !renderNoPty;
     const forwarded = buildPassthroughForwardedArgs(command, allArgs, interactive);
     // The one long-running case: keep the remote team supervisor alive past a
     // disconnect by dispatching it detached (nohup), still streaming live.
@@ -583,10 +638,13 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     const doctorPath = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
         ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
         : undefined;
+    // Merge the doctor PATH bootstrap with the render color/geometry env (doctor is
+    // itself a render command, so both can apply). undefined when neither is needed.
+    const extraEnv = doctorPath || renderForwardEnv ? { ...doctorPath, ...renderForwardEnv } : undefined;
     process.exitCode = streamAgentsOnHost(host, forwarded, {
         remoteCwd,
         interactive,
-        extraEnv: doctorPath,
+        extraEnv,
         remoteOs,
         target,
     });