@phnx-labs/agents-cli 1.22.115 → 1.22.116

package/dist/commands/sessions-picker.js

@@ -8,12 +8,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
-import { truncate, humanDuration } from '../lib/format.js';
+import { truncate, humanDuration, formatBytes } from '../lib/format.js';
 import { sessionDisplayAgent } from '../lib/session/types.js';
 import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { parseSession, sanitizeForTerminal, SNAPSHOT_TODO_TOOLS } from '../lib/session/parse.js';
+import { readSessionTail, readSessionHead } from '../lib/session/tail.js';
 import { safeTeamText } from '../lib/session/team-filter.js';
-import { cleanSessionPrompt, extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
+import { cleanSessionPrompt, extractSessionTopic, isSyntheticUserMessage, firstUserMessageFromEvents } from '../lib/session/prompt.js';
 import { linkPath, linkUrl, relativeToCwd, shortenModel } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
@@ -324,7 +325,14 @@ export function loadSessionPreviewDigest(session) {
             archived.plugins = getSessionPlugins(session.id);
             return { digest: archived, events: [] };
         }
-        return { events: [] };
+        // No file on disk AND no archived digest: a metadata-only row (a Rush
+        // dispatch/audit row, a synthesized attach-only entry, a live session not
+        // yet indexed) with nothing to read (PHNX-3999). Callers that only
+        // destructure `digest` (the picker's "not indexed here" note) are
+        // unaffected; a JSON caller reading `error` gets a truthful reason instead
+        // of a `preview: null` that looks identical to "this session genuinely has
+        // no content yet".
+        return { events: [], error: 'no local transcript for this session (metadata-only entry, no archived digest)' };
     }
     const safe = sanitizeMeta(session);
     let events = [];
@@ -340,9 +348,53 @@ export function loadSessionPreviewDigest(session) {
         fileSize: sourceStamp.size,
     });
     if (!digest) {
-        try {
-            events = parseSession(session.filePath, session.agent);
+        if (sourceStamp.size > PREVIEW_DIGEST_MAX_PARSE_BYTES) {
+            // A full `parseSession` on a cache miss is a synchronous, unbounded
+            // whole-file parse with no time/byte cap of its own (PHNX-3999) — real
+            // 6.3 MiB and 35.7 MiB screenshot-heavy transcripts on this fleet both
+            // lacked a computed digest/timeline, consistent with this path not
+            // finishing in a reasonable request budget for either. `PREVIEW_DIGEST_MAX_PARSE_BYTES`
+            // is deliberately smaller than the daemon's own background-work ceiling
+            // (see that constant's own doc) so this catches both real cases.
+            //
+            // This IS genuinely partial, not empty: rather than parsing nothing,
+            // `readSessionTail` (`tail.ts`) reads only the LAST 128 KiB of the file
+            // (already the live-view's own bounded reader, reused verbatim — no new
+            // parse logic) for a real recent-events window on the two harnesses it
+            // supports (Claude/Codex); event-derived fields below (toolCalls,
+            // toolTags, etc.) reflect that tail window, not the whole session, which
+            // `partialReason` states explicitly.
+            //
+            // `firstUser` is NEVER set from the tail fold: a tail window's "first
+            // user message IN THAT WINDOW" is a mid-session follow-up on any
+            // multi-turn session, not the session's actual original request, and
+            // there is no honest way to tell the two apart from the tail alone.
+            // Falling back to it would silently mislabel a follow-up as the
+            // original ask. Preference order for the CANONICAL original request:
+            // (1) the already-indexed `SessionMeta.firstUserMessage` (zero
+            // extra I/O); (2) failing that, a bounded HEAD read (`readSessionHead`,
+            // `tail.ts` — the mirror of the tail reader, first ~32 KiB from byte 0,
+            // where a session's opening turn always lives) so a row with no indexed
+            // value yet still gets the REAL original request rather than nothing.
+            // Only when neither is available does `firstUser` stay empty —
+            // `partial`/`partialReason` already say why detail is missing, which is
+            // the truthful signal, never a guessed value. The digest is cached
+            // against this stamp so the bound is paid once per transcript version,
+            // not once per call.
+            events = readSessionTail(session.filePath, session.agent);
             digest = buildSessionPreviewDigest(events, safe);
+            if (session.firstUserMessage) {
+                digest.firstUser = session.firstUserMessage;
+            }
+            else {
+                // Reuse the canonical extractor (rejects synthetic/system-injected
+                // turns, unwraps a Grok/Cursor <user_query> wrapper) rather than a
+                // bespoke inline find — the same rules SessionMeta.firstUserMessage
+                // itself was built with.
+                digest.firstUser = firstUserMessageFromEvents(readSessionHead(session.filePath, session.agent)) ?? '';
+            }
+            digest.partial = true;
+            digest.partialReason = `transcript is ${formatBytes(sourceStamp.size)}, over the ${formatBytes(PREVIEW_DIGEST_MAX_PARSE_BYTES)} bounded-parse limit for an uncached preview; digest reflects only the last ~128 KiB (tail) of the transcript, not the whole session`;
             writeSessionPreviewCache({
                 id: session.id,
                 fileMtimeMs: sourceStamp.mtimeMs,
@@ -350,8 +402,20 @@ export function loadSessionPreviewDigest(session) {
                 preview: digest,
             });
         }
-        catch (err) {
-            return { events, error: sanitizeForTerminal(err?.message ?? String(err)) };
+        else {
+            try {
+                events = parseSession(session.filePath, session.agent);
+                digest = buildSessionPreviewDigest(events, safe);
+                writeSessionPreviewCache({
+                    id: session.id,
+                    fileMtimeMs: sourceStamp.mtimeMs,
+                    fileSize: sourceStamp.size,
+                    preview: digest,
+                });
+            }
+            catch (err) {
+                return { events, error: sanitizeForTerminal(err?.message ?? String(err)) };
+            }
         }
     }
     digest.plugins = getSessionPlugins(session.id);
@@ -711,6 +775,23 @@ const DIRS_TOUCHED_MAX = 5;
 // enough to cover any real session's edits, low enough that a runaway rewrite
 // can't bloat the cached JSON. The `changes` counts stay the true totals.
 const CHANGED_FILES_MAX = 200;
+/**
+ * Bound for an uncached `loadSessionPreviewDigest` parse (PHNX-3999).
+ *
+ * Deliberately SMALLER than the daemon's own
+ * `TIMELINE_PASS_MAX_WHOLE_FILE_BYTES` (16 MiB, `timeline-pass.ts`) — that
+ * number bounds BACKGROUND work the daemon tick can afford to spend; this one
+ * bounds a SYNCHRONOUS request an interactive caller (the Menu, with its own
+ * end-to-end latency budget) is actively waiting on. Two real screenshot-heavy
+ * transcripts on this fleet (6.3 MiB and 35.7 MiB) both lacked any computed
+ * digest/timeline — a 16 MiB threshold here would still miss the smaller one.
+ * The exact per-byte cost of `parseSession` is not measured in this change;
+ * 4 MiB is a conservative invariant (well under the 6.3 MiB failure case,
+ * comfortably above ordinary non-screenshot transcript sizes), not a timing
+ * guarantee — verify against real transcripts before relying on a specific
+ * elapsed-time bound.
+ */
+const PREVIEW_DIGEST_MAX_PARSE_BYTES = 4 * 1024 * 1024;
 /** Fold a harness-normalized event stream into the stable preview data model. */
 export function buildSessionPreviewDigest(events, session) {
     let firstUser = '';

package/dist/commands/sessions.d.ts

@@ -1,13 +1,13 @@
 import { type Command } from 'commander';
 import { type ProjectDef } from '../lib/projects.js';
-import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
+import type { SessionAgentId, SessionEvent, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 export { activeSessionProjectKey, backfillActiveRowsFromIndex, backfillActiveRowsFromMeta, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson, type BackfillMeta } from '../lib/session/active.js';
 import { loadLocalActiveSessions } from '../lib/session/session-cache.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type RemoteAgentsJsonParseResult } from '../lib/remote-agents-json.js';
 import { type RunMeta } from '../lib/scheduling/routines.js';
-import { type PickedSession } from './sessions-picker.js';
+import { type PickedSession, type SessionPreviewDigest } from './sessions-picker.js';
 import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
@@ -466,6 +466,23 @@ export declare function printRoutineDrilldown(drill: RoutineDrilldown, liveIndex
     hiddenCount?: number;
     hiddenUnmanaged?: number;
 }): void;
+export interface SessionDetailMessage {
+    role: 'user' | 'assistant';
+    text: string;
+    at: string | null;
+}
+export declare function buildSessionDetailBlock(session: SessionMeta, digest: SessionPreviewDigest | undefined, events: SessionEvent[], sourceStamp?: {
+    fileMtimeMs: number;
+    fileSize: number;
+}): {
+    request: unknown;
+    timeline: unknown;
+    files: unknown;
+    messages: SessionDetailMessage[];
+    sourceRevision: string | null;
+    partial: boolean;
+    reason: string | null;
+};
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export declare function renderSessionPreview(query: string, scope: {
@@ -474,6 +491,8 @@ export declare function renderSessionPreview(query: string, scope: {
     local?: boolean;
     hosts?: string[];
     json?: boolean;
+    refresh?: boolean;
+    revision?: string;
 }): Promise<void>;
 /**
  * The one-line live status banner shown above a session preview: the glyph, the

package/dist/commands/sessions.js

@@ -35,7 +35,9 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
-import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
+import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview, readSessionTimelineAny } from '../lib/session/db.js';
+import { foldTimeline, emptyTimelineState, projectTimeline, projectSessionFiles } from '../lib/session/timeline.js';
+import { readSessionTail } from '../lib/session/tail.js';
 import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
 import { sessionHeadline } from '../lib/session/title.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
@@ -1982,9 +1984,151 @@ function canonicalSessionsCommand(query, options) {
         a.push(JSON.stringify(q));
     return 'ag ' + a.join(' ');
 }
+/** Bound on the `details.messages` array and on each message's `text` — this
+ * rides a cached JSON payload (and, for the remote fast path, an SSH capture
+ * with its own byte cap), so it is capped independently of either. */
+const SESSION_DETAIL_MAX_MESSAGES = 8;
+const SESSION_DETAIL_MESSAGE_MAX_CHARS = 4_000;
+/**
+ * The additive `details` block on `sessions preview --json` (PHNX-3999):
+ * `request`/`timeline`/`files` are read FIRST from the existing
+ * `session_timelines` projection (`readSessionTimelineAny` — the daemon's own
+ * bounded, incrementally-folded cache, `SessionTimelineProjection` in
+ * `lib/session/db.ts`), so a session the daemon has already reached costs
+ * nothing extra here. When that projection is missing (daemon hasn't reached
+ * this session yet), this does an ON-DEMAND fold using the EXACT same pure,
+ * already-redacting pipeline the daemon uses (`foldTimeline` /
+ * `projectTimeline` / `projectSessionFiles`, `timeline.ts`) over whatever
+ * events are cheaply available: the fresh-parse `events` from
+ * `loadSessionPreviewDigest` when there is one, else a bounded 128 KiB tail
+ * read (`readSessionTail`, Claude/Codex only — the same bounded reader the
+ * local preview's over-cap fallback uses) so a WARM cache hit (no fresh parse)
+ * still gets real, on-demand content instead of falling back to a 2-message
+ * digest summary. This is genuinely bounded either way: it folds only events
+ * already in hand or a fixed 128 KiB window, never a fresh whole-file parse.
+ * `partial`/`reason` say when this happened (`daemon-pending: on-demand
+ * bounded fold`) versus a session with no transcript at all.
+ */
+function sessionTranscriptStamp(session) {
+    try {
+        if (!session.filePath)
+            return undefined;
+        const stat = fs.statSync(session.filePath);
+        return { fileMtimeMs: stat.mtimeMs, fileSize: stat.size };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildSessionDetailBlock(session, digest, events, sourceStamp) {
+    const bound = (text) => redactSecrets(sanitizeForTerminal(text)).slice(0, SESSION_DETAIL_MESSAGE_MAX_CHARS);
+    const stamp = sourceStamp ?? sessionTranscriptStamp(session);
+    const canDateEvents = sourceStamp !== undefined || events.length === 0;
+    const daemonProjection = stamp ? readSessionTimelineAny(session.id, stamp) : undefined;
+    // A bounded tail read backs `messages` on EVERY warm cache hit (no fresh
+    // parse this call), REGARDLESS of whether the daemon projection is already
+    // present — this is what fixes a real bug review caught: a warm digest hit
+    // whose daemon timeline HAD landed still fell through to the 2-message
+    // digest summary below, because the tail-read used to be gated on the
+    // on-demand-fold branch only. `messages` and the on-demand fold are two
+    // independent uses of the same cheap, bounded events window.
+    let foldEvents = events;
+    if (foldEvents.length === 0 && session.filePath) {
+        foldEvents = readSessionTail(session.filePath, session.agent);
+    }
+    let projection = daemonProjection;
+    let onDemand = false;
+    if (!projection && foldEvents.length > 0) {
+        const state = foldTimeline(foldEvents, emptyTimelineState());
+        projection = {
+            request: state.request,
+            timeline: projectTimeline(state, undefined),
+            files: projectSessionFiles(state),
+        };
+        onDemand = true;
+    }
+    let messages;
+    if (foldEvents.length > 0) {
+        messages = foldEvents
+            .filter((e) => e.type === 'message' && !e._synthetic && Boolean(e.content) && (e.role === 'user' || e.role === 'assistant'))
+            .slice(-SESSION_DETAIL_MAX_MESSAGES)
+            .map(e => ({ role: e.role, text: bound(e.content), at: e.timestamp ?? null }));
+    }
+    else {
+        messages = [];
+        if (digest?.firstUser)
+            messages.push({ role: 'user', text: bound(digest.firstUser), at: session.timestamp ?? null });
+        if (digest?.lastAssistant)
+            messages.push({ role: 'assistant', text: bound(digest.lastAssistant), at: session.lastActivity ?? null });
+    }
+    const endStamp = sessionTranscriptStamp(session);
+    const unchanged = canDateEvents && stamp !== undefined && endStamp !== undefined
+        && stamp.fileMtimeMs === endStamp.fileMtimeMs && stamp.fileSize === endStamp.fileSize;
+    const partial = Boolean(digest?.partial) || !daemonProjection || !unchanged;
+    const reason = digest?.partialReason
+        ?? (onDemand
+            ? 'background timeline pass has not reached this session yet; request/timeline/files below are an on-demand bounded fold, not the full-history daemon projection'
+            : (!projection ? 'no transcript available to fold request/timeline/files for this session' : null));
+    return {
+        request: projection?.request ?? null,
+        timeline: projection?.timeline ?? null,
+        files: projection?.files ?? null,
+        messages,
+        sourceRevision: unchanged ? new Date(stamp.fileMtimeMs).toISOString() : null,
+        partial,
+        reason,
+    };
+}
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export async function renderSessionPreview(query, scope) {
+    // Exact ID + exactly one named, non-local device: the canonical bounded
+    // preview loader (PHNX-3999) answers in ONE ssh hop plus a durable local
+    // cache, instead of the general resolver's metadata fan-out followed by a
+    // second render hop. Scoped tightly on purpose — a short id/label is not a
+    // stable cache key across devices, and this never touches local discovery.
+    //
+    // Gated on `isCompleteSessionId`, NOT a bare-UUID regex: measured over this
+    // fleet's own index, a "full session id" is a bare UUID for most harnesses
+    // but `session_<uuid>` for kimi/rush and `ses_<ulid>` for opencode
+    // (discover.ts). A bare-UUID-only check would silently skip this fast path
+    // (falling through to the slower general resolver, never wrong, but wrong
+    // to claim as "the fast path" for those harnesses) for a real, exact,
+    // caller-supplied full id on those three.
+    if (scope.json && !scope.local && scope.hosts?.length === 1
+        && scope.hosts[0] !== machineId() && isCompleteSessionId(query.trim())) {
+        const { getRemoteSessionPreview } = await import('../lib/session/remote-preview-cache.js');
+        const result = await getRemoteSessionPreview(query.trim(), scope.hosts[0], {
+            refresh: scope.refresh,
+            revision: scope.revision,
+        });
+        const envelope = result.envelope;
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            session: envelope?.session ?? null,
+            // `active` is a live snapshot the PEER computed at the moment it ran
+            // `sessions preview --local --json` — meaningful only for that instant.
+            // When this response is served from the durable cache (`cache.source ===
+            // 'cache'`, which can be up to 45s old, or indefinitely old under a
+            // matched --revision), presenting that stale snapshot under the same
+            // `active` key would read as the session's CURRENT working/idle status
+            // when it may no longer be. Null it out rather than relabel it with an
+            // age stamp: the caller already has `cache.fetchedAt`/`cache.stale` to
+            // reason about staleness, and getting a fresh `active` read costs
+            // another SSH round trip this fast path exists specifically to avoid.
+            active: result.cache.source === 'live' ? (envelope?.active ?? null) : null,
+            preview: envelope?.preview ?? null,
+            error: envelope?.error ?? (envelope ? null : result.cache.reason),
+            // The peer's own `sessions preview --local --json` already computed
+            // `details` (request/timeline/files/messages) with its own bounded reader
+            // (see buildSessionDetailBlock) — this hop just forwards it verbatim,
+            // never re-derives it, so a metadata-only/no-transcript peer row's
+            // explicit unavailable reason survives the hop unchanged.
+            details: envelope?.details ?? null,
+            cache: result.cache,
+        }));
+        return;
+    }
     let outcome = await resolveSessionMetadataValue(query, scope);
     // resolveSessionMetadataValue already consults the live registry for a running
     // session with no transcript row (RUSH-2682), so a live session resolves above.
@@ -2059,7 +2203,8 @@ export async function renderSessionPreview(query, scope) {
     }
     catch { /* plain preview on any probe failure */ }
     if (scope.json) {
-        const { digest, error } = loadSessionPreviewDigest(session);
+        const sourceStamp = sessionTranscriptStamp(session);
+        const { digest, error, events } = loadSessionPreviewDigest(session);
         console.log(JSON.stringify({
             schemaVersion: 1,
             session: {
@@ -2095,6 +2240,7 @@ export async function renderSessionPreview(query, scope) {
             } : null,
             preview: digest ?? null,
             error: error ?? null,
+            details: buildSessionDetailBlock(session, digest, events, sourceStamp),
         }));
         return;
     }
@@ -5370,7 +5516,9 @@ export function registerSessionsCommands(program) {
         .option('-p, --project <name>', 'Narrow the ID to one project')
         .option('--local', 'Only this machine; do not resolve the ID across the fleet')
         .option('-D, --device <target...>', 'Resolve only on the named device(s)')
-        .option('--json', 'Output the session preview as JSON');
+        .option('--json', 'Output the session preview as JSON')
+        .option('--refresh', 'Bypass the durable remote-preview cache and negative backoff for one bounded fetch (full ID + single --device only)')
+        .option('--revision <cursor>', 'Opaque caller-owned activity cursor (any stable value YOU track, e.g. your own feed\'s lastActivityMs) -- passing the SAME value as your last call confirms nothing changed and serves the cache with zero SSH indefinitely; a different value fetches once, still subject to backoff unless --refresh is also set (full ID + single --device only)');
     setHelpSections(previewCmd, {
         examples: `
       # Preview by the 8-character ID shown in agents sessions
@@ -5382,11 +5530,15 @@ export function registerSessionsCommands(program) {
       # Stay on this machine or restrict the authoritative lookup to one peer
       agents sessions preview 407b8dd5 --local
       agents sessions preview 407b8dd5 --device zion
+
+      # Full ID + one --device: durable-cached fast path (PHNX-3999); force a fresh fetch
+      agents sessions preview c70ecdea-6210-4039-9845-246a3a7a9942 --device zion --json --refresh
     `,
         notes: `
       - Full UUIDs are globally unique and may stop the fleet lookup at the first exact hit.
       - Short IDs wait for every selected device so ambiguity is never hidden.
       - Active status is refreshed through the bounded live-state TTL; transcript-derived details use the durable session index.
+      - A full UUID with exactly one --device and --json is served from a local durable cache (~45s fresh window); the JSON envelope's "cache" field reports fresh/stale/offline state. --refresh forces one bounded re-fetch.
     `,
     });
     previewCmd.action(async (id) => {
@@ -5398,6 +5550,8 @@ export function registerSessionsCommands(program) {
             local: options.local,
             hosts: hosts.length > 0 ? hosts : undefined,
             json: options.json,
+            refresh: options.refresh,
+            revision: options.revision,
         });
     });
     registerSessionsTailCommand(sessionsCmd);

package/dist/commands/setup-secrets.d.ts

@@ -8,8 +8,8 @@
  * `npm i -g`. Users do not set extra env vars.
  */
 import type { Command } from 'commander';
-export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.4";
-export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.4";
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.5";
+export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.5";
 export declare function setupSecretsPrefsPath(): string;
 /** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
 export declare function isSecretsCliInstalled(): boolean;

package/dist/commands/setup-term.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
+ *
+ * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
+ * agents-cli never rebundles it. The OAuth device-code driver (`agents fleet
+ * login`, `agents auth mint`) spawns `term` on demand and fails loud when it is
+ * absent, so onboarding installs it here like every other standalone tool.
+ *
+ * Unlike browser/computer/secrets there is nothing to configure — no profile,
+ * no OS permission, no migrate step. A missing binary is a routine install
+ * (`agents clis install term` via the system `clis/term.yaml`, then a pinned
+ * `npm i -g`, both handled by installSetupTool), and once it is on PATH the
+ * tool is ready.
+ */
+import type { Command } from 'commander';
+/** True when the standalone `term` executable resolves ($TERM_BIN or PATH). */
+export declare function isTermCliInstalled(): boolean;
+/**
+ * Install the standalone `term` CLI if missing. Returns whether `term` is on
+ * PATH afterwards. There is no further onboarding — presence is readiness.
+ */
+export declare function runTermWizard(): Promise<boolean>;
+/** Register `agents setup term` under the parent `setup` command. */
+export declare function registerSetupTermCommand(setupCmd: Command): void;

package/dist/commands/setup-term.js

@@ -0,0 +1,70 @@
+/**
+ * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
+ *
+ * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
+ * agents-cli never rebundles it. The OAuth device-code driver (`agents fleet
+ * login`, `agents auth mint`) spawns `term` on demand and fails loud when it is
+ * absent, so onboarding installs it here like every other standalone tool.
+ *
+ * Unlike browser/computer/secrets there is nothing to configure — no profile,
+ * no OS permission, no migrate step. A missing binary is a routine install
+ * (`agents clis install term` via the system `clis/term.yaml`, then a pinned
+ * `npm i -g`, both handled by installSetupTool), and once it is on PATH the
+ * tool is ready.
+ */
+import chalk from 'chalk';
+import { isPromptCancelled } from './utils.js';
+import { openSetupTerminal } from './setup-terminal.js';
+import { resolveTermBin } from '../lib/term-client.js';
+import { installSetupTool } from '../lib/setup-tool-install.js';
+import { refreshToolSetup } from '../lib/setup-tool-status.js';
+const INSTALL_HINT = 'agents clis install term   # or: npm i -g @phnx-labs/term-cli';
+/** True when the standalone `term` executable resolves ($TERM_BIN or PATH). */
+export function isTermCliInstalled() {
+    return resolveTermBin() !== null;
+}
+/**
+ * Install the standalone `term` CLI if missing. Returns whether `term` is on
+ * PATH afterwards. There is no further onboarding — presence is readiness.
+ */
+export async function runTermWizard() {
+    if (isTermCliInstalled()) {
+        console.log(chalk.green('The standalone `term` CLI is installed.'));
+        return true;
+    }
+    if (await installSetupTool('term')) {
+        console.log(chalk.green('Installed the standalone `term` CLI.'));
+        return true;
+    }
+    console.log(chalk.yellow('The standalone `term` CLI is not installed.'));
+    console.log(chalk.gray('Install it, then re-run `agents setup term`:'));
+    console.log(chalk.cyan(`  ${INSTALL_HINT}`));
+    return false;
+}
+/** Register `agents setup term` under the parent `setup` command. */
+export function registerSetupTermCommand(setupCmd) {
+    setupCmd
+        .command('term')
+        .description('Install the standalone `term` CLI (the PTY engine fleet login and auth mint spawn) if missing.')
+        .option('--install-only', 'Install the standalone term CLI (identical to the wizard; term needs no further setup)')
+        .option('--terminal [backend]', 'Open interactive setup in a detected or selected terminal')
+        .action(async (options) => {
+        try {
+            if (options.terminal !== undefined) {
+                await openSetupTerminal('term', options.terminal, options.installOnly);
+                return;
+            }
+            if (!(await runTermWizard()))
+                process.exitCode = 1;
+            await refreshToolSetup('term');
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.yellow('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/setup.d.ts

@@ -31,7 +31,7 @@ export declare function ensureInitialized(program: Command): Promise<void>;
  * wizard. Never throws — a cancel or an optional wizard's error just skips the
  * rest and lets core setup complete.
  */
-type SetupPhase = 'browser' | 'computer' | 'secrets' | 'accounts' | 'fleet' | 'watchdog' | 'preferences';
+type SetupPhase = 'browser' | 'computer' | 'secrets' | 'term' | 'accounts' | 'fleet' | 'watchdog' | 'preferences';
 type SetupStatusState = 'ready' | 'missing' | 'n/a';
 interface SetupStatusRow {
     phase: 'core' | SetupPhase;

package/dist/commands/setup.js

@@ -22,6 +22,7 @@ import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.j
 import { registerSetupComputerCommand, runComputerWizard } from './setup-computer.js';
 import { registerSetupMineCommand } from './setup-mine.js';
 import { registerSetupSecretsCommand } from './setup-secrets.js';
+import { registerSetupTermCommand, runTermWizard, isTermCliInstalled } from './setup-term.js';
 import { registerSetupFleetCommand } from './setup-fleet.js';
 import { registerSetupAccountsCommand, runAccountsSetupWizard } from './setup-accounts.js';
 import { registerSetupWatchdogCommand, runWatchdogSetupWizard } from './setup-watchdog.js';
@@ -278,6 +279,7 @@ export async function getSetupStatus() {
     const devices = await loadDevices();
     const coreReady = isGitRepo(getAgentsDir());
     const secretsReady = fs.existsSync(setupSecretsPrefsPath());
+    const termReady = isTermCliInstalled();
     const minted = hasMintedSetupToken();
     const watchdogEnabled = getConfigValue('watchdog.enabled').value === true;
     const interactiveHost = getConfigValue('interactive.host').value;
@@ -287,6 +289,7 @@ export async function getSetupStatus() {
         { phase: 'browser', state: browserReady ? 'ready' : 'missing', detail: browserReady ? `profile ${browserProfile.name}` : browserProfile ? `profile ${browserProfile.name} cannot launch here` : installedBrowsers.length ? 'no default profile' : 'no supported browser found' },
         { phase: 'computer', state: computerState, detail: computerState === 'ready' ? 'helper trusted' : computerState === 'n/a' ? 'macOS local setup only' : 'helper not running or not trusted' },
         { phase: 'secrets', state: secretsReady ? 'ready' : 'missing', detail: secretsReady ? 'defaults chosen' : 'defaults not chosen' },
+        { phase: 'term', state: termReady ? 'ready' : 'missing', detail: termReady ? 'installed' : 'not installed (fleet login / auth mint spawn it)' },
         { phase: 'accounts', state: minted.ready ? 'ready' : 'missing', detail: minted.detail },
         { phase: 'fleet', state: Object.keys(devices).length ? 'ready' : 'missing', detail: Object.keys(devices).length ? `${Object.keys(devices).length} device${Object.keys(devices).length === 1 ? '' : 's'} registered` : 'no devices registered' },
         { phase: 'watchdog', state: watchdogEnabled ? 'ready' : 'missing', detail: watchdogEnabled ? 'enabled on this device' : 'disabled on this device' },
@@ -308,6 +311,8 @@ async function runSetupPhase(phase) {
         await runComputerWizard();
     else if (phase === 'secrets')
         await import('./setup-secrets.js').then((m) => m.runSecretsSetupWizard());
+    else if (phase === 'term')
+        await runTermWizard();
     else if (phase === 'accounts')
         await runAccountsSetupWizard();
     else if (phase === 'fleet')
@@ -366,11 +371,12 @@ export function registerSetupCommand(program) {
         .description('Set up agents-cli, or re-open the capability onboarding hub.')
         .option('-f, --force', 'Re-run setup even if ~/.agents/.system/ already exists (use with caution)')
         .option('--no-system-repo', 'Skip cloning the system repo (you must populate ~/.agents/.system/ yourself)');
-    // Capability subcommands: `agents setup browser|computer|mine|secrets|accounts|fleet|alias|beta`.
+    // Capability subcommands: `agents setup browser|computer|term|mine|secrets|accounts|fleet|alias|beta`.
     // Artifact publishing is no longer set up here — it lives in the standalone
     // `artifacts` CLI (`artifacts share setup`/`join`, PHNX-3992).
     registerSetupBrowserCommand(setupCmd);
     registerSetupComputerCommand(setupCmd);
+    registerSetupTermCommand(setupCmd);
     registerSetupMineCommand(setupCmd);
     registerSetupSecretsCommand(setupCmd);
     registerSetupAccountsCommand(setupCmd);
@@ -399,15 +405,15 @@ export function registerSetupCommand(program) {
     `,
     });
     setupCmd.command('status')
-        .description('Show setup readiness for core, browser, computer, secrets, accounts, fleet, watchdog, and preferences.')
+        .description('Show setup readiness for core, browser, computer, secrets, term, accounts, fleet, watchdog, and preferences.')
         .option('--json', 'print machine-readable JSON')
-        .option('--tool <name>', 'Read cached standalone tool status: browser, computer, secrets, or all')
+        .option('--tool <name>', 'Read cached standalone tool status: browser, computer, secrets, term, or all')
         .option('--refresh', 'Explicitly refresh only the selected standalone tool health checks')
         .action(async (options) => {
         if (options.tool || options.refresh) {
             const selected = options.tool ?? 'all';
             if (selected !== 'all' && !SETUP_TOOLS.includes(selected))
-                throw new Error('Unknown tool. Choose browser, computer, secrets, or all.');
+                throw new Error('Unknown tool. Choose browser, computer, secrets, term, or all.');
             const rows = options.refresh
                 ? await refreshToolSetup(selected)
                 : getCachedToolSetup().filter((row) => selected === 'all' || row.tool === selected);
@@ -438,6 +444,7 @@ export function registerSetupCommand(program) {
       agents setup browser
       agents setup computer
       agents setup secrets
+      agents setup term
       agents setup accounts
       agents setup fleet
       agents setup watchdog
@@ -455,6 +462,7 @@ export function registerSetupCommand(program) {
         agents setup browser    # detect a browser + create the default profile
         agents setup computer    # install the signed macOS helper + grant permissions
         agents setup secrets     # choose secrets backend/policy defaults + import
+        agents setup term        # install the standalone term CLI (PTY engine for fleet login / auth mint)
         agents setup accounts    # mint a Claude setup-token for unattended usage/probe
         agents setup fleet       # discover Tailscale devices + configure SSH access
         agents setup watchdog    # choose which devices run the daemon watchdog pass