@phnx-labs/agents-cli 1.22.114 → 1.22.116

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';
@@ -64,12 +66,9 @@ import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerSessionsForkCommand } from './fork.js';
 import { registerSessionsBookmarkCommand } from './sessions-bookmark.js';
 import { isBookmarked, listBookmarks } from '../lib/session/bookmarks.js';
-import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
-import { registerReconnectCommand } from './reconnect.js';
 import { registerDetachCommand } from './detach.js';
 import { registerSessionsStopCommand } from './sessions-stop.js';
-import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
 import { registerSessionsRenderCommand } from './sessions-render.js';
@@ -1985,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.
@@ -2062,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: {
@@ -2098,6 +2240,7 @@ export async function renderSessionPreview(query, scope) {
             } : null,
             preview: digest ?? null,
             error: error ?? null,
+            details: buildSessionDetailBlock(session, digest, events, sourceStamp),
         }));
         return;
     }
@@ -3963,7 +4106,7 @@ async function resumeOnOwnerIfRemote(session) {
 export async function resumeSessionInPlace(session) {
     // This function is the LOCAL takeover, and every caller is responsible for
     // routing a peer-owned session before it gets here (the picker above,
-    // `agents sessions resume`, `sessions attach`). Reaching it with one anyway means a
+    // `agents sessions resume`). Reaching it with one anyway means a
     // caller skipped that step, so refuse rather than start the harness against
     // state this box does not have — the `fs.existsSync(session.cwd)` fallback
     // just below is exactly how that used to pass unnoticed, quietly swapping in
@@ -5317,7 +5460,6 @@ export function registerSessionsCommands(program) {
         resume <id> --attach-only  attach only; never fork a copy
         resume                  multi-select history -> open tabs
         detach <id>             the other direction: interactive -> headless
-        (retired, still working for one release: sessions attach, sessions go, reconnect)
       - The interactive listing and every live-status flag fold in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; single-id lookups stay local.
       - --all is not a device flag: it widens historical directory and time filters. Fleet collection is already the default. A status flag (--working/--idle/--waiting/--orphan/--crashed/--closed/--abandoned/--queued/--unknown) implies --active; combine status flags for a union.
       - --version <version> requires --agent and is equivalent to --agent <agent@version>.
@@ -5374,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
@@ -5386,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) => {
@@ -5402,18 +5550,17 @@ export function registerSessionsCommands(program) {
             local: options.local,
             hosts: hosts.length > 0 ? hosts : undefined,
             json: options.json,
+            refresh: options.refresh,
+            revision: options.revision,
         });
     });
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerSessionsForkCommand(sessionsCmd);
     registerSessionsBookmarkCommand(sessionsCmd);
-    registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
-    registerReconnectCommand(sessionsCmd);
     registerDetachCommand(sessionsCmd);
     registerSessionsStopCommand(sessionsCmd);
-    registerAttachCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
     registerSessionsRenderCommand(sessionsCmd);

package/dist/commands/setup-browser.js

@@ -7,6 +7,7 @@
  * Idempotent: re-running shows the current default profile and offers to change
  * the pinned browser or re-point the device default.
  */
+import { openSetupTerminal } from './setup-terminal.js';
 import chalk from 'chalk';
 import { setConfigValue } from '../lib/device-config.js';
 import { listInstalledBrowsers } from '../lib/browser/chrome.js';
@@ -14,6 +15,8 @@ import { DEFAULT_BROWSER_PROFILE_NAME, getAutoDetectedProfile, createProfile, fi
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { defaultBrowserChoice } from './setup-preferences.js';
+import { installSetupTool } from '../lib/setup-tool-install.js';
+import { refreshToolSetup } from '../lib/setup-tool-status.js';
 const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, Comet, or Arc, then re-run `agents setup browser`.\n' +
     '(This wizard picks a Chromium-family browser. An installed Firefox is not auto-picked here; its profiles are ' +
     'discovered from profiles.ini and selected with `agents browser use firefox-<name>`. Safari is not supported.)';
@@ -116,9 +119,22 @@ export function registerSetupBrowserCommand(setupCmd) {
     setupCmd
         .command('browser')
         .description('Set up `agents browser` — detect an installed browser and create the default profile.')
-        .action(async () => {
+        .option('--install-only', 'Install the standalone Browser CLI without changing profiles or starting a browser')
+        .option('--terminal [backend]', 'Open interactive setup in a detected or selected terminal')
+        .action(async (options) => {
         try {
-            await runBrowserWizard();
+            if (options.terminal !== undefined) {
+                await openSetupTerminal('browser', options.terminal, options.installOnly);
+                return;
+            }
+            if (options.installOnly) {
+                if (!(await installSetupTool('browser')))
+                    process.exitCode = 1;
+                return;
+            }
+            if (!(await runBrowserWizard()))
+                process.exitCode = 1;
+            await refreshToolSetup('browser');
         }
         catch (err) {
             if (isPromptCancelled(err)) {

package/dist/commands/setup-computer.js

@@ -8,12 +8,15 @@
  * this wizard chains them with the permission hand-holding a fresh machine needs.
  * Idempotent: re-running re-installs the current helper and re-checks trust.
  */
+import { openSetupTerminal } from './setup-terminal.js';
 import os from 'node:os';
-import { execFileSync, spawnSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import chalk from 'chalk';
 import { installComputerHelperMacLocal, activateComputerHelperMacLocal, probeComputerTrust, } from './computer.js';
 import { resolveComputerBin, ComputerClientError } from '../lib/computer-client.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { installSetupTool } from '../lib/setup-tool-install.js';
+import { refreshToolSetup } from '../lib/setup-tool-status.js';
 const ACCESSIBILITY_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility';
 const SCREEN_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -43,9 +46,7 @@ export async function runComputerWizard() {
     catch (error) {
         if (!(error instanceof ComputerClientError) || error.code !== 'COMPUTER_BIN_MISSING')
             throw error;
-        console.log('Installing @phnx-labs/computer-cli@0.1.2…');
-        const installed = spawnSync('npm', ['install', '-g', '@phnx-labs/computer-cli@0.1.2'], { stdio: 'inherit' });
-        if (installed.status !== 0)
+        if (!(await installSetupTool('computer')))
             return false;
         try {
             resolveComputerBin();
@@ -136,9 +137,22 @@ export function registerSetupComputerCommand(setupCmd) {
     setupCmd
         .command('computer')
         .description('Set up `agents computer` (macOS) — install the signed helper and grant control permissions.')
-        .action(async () => {
+        .option('--install-only', 'Install the standalone Computer CLI without starting the helper or changing permissions')
+        .option('--terminal [backend]', 'Open interactive setup in a detected or selected terminal')
+        .action(async (options) => {
         try {
-            await runComputerWizard();
+            if (options.terminal !== undefined) {
+                await openSetupTerminal('computer', options.terminal, options.installOnly);
+                return;
+            }
+            if (options.installOnly) {
+                if (!(await installSetupTool('computer')))
+                    process.exitCode = 1;
+                return;
+            }
+            if (!(await runComputerWizard()))
+                process.exitCode = 1;
+            await refreshToolSetup('computer');
         }
         catch (err) {
             if (isPromptCancelled(err)) {

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-secrets.js

@@ -7,6 +7,7 @@
  * `agents clis install secrets` (system `clis/secrets.yaml`) then a pinned
  * `npm i -g`. Users do not set extra env vars.
  */
+import { openSetupTerminal } from './setup-terminal.js';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -14,7 +15,12 @@ import { spawnSync } from 'node:child_process';
 import { getHistoryDir } from '../lib/state.js';
 import { resolveSecretsBin, invocation, SecretsClientError, _resetSecretsClientForTest } from '../lib/secrets-client.js';
 import { installCli, resolveCliManifest } from '../lib/cli-resources.js';
-export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.4';
+import { SECRETS_CLI_SPEC } from '../lib/secrets-cli.js';
+import { refreshToolSetup } from '../lib/setup-tool-status.js';
+import { execFileShellSpec } from '../lib/platform/exec.js';
+// Re-exported for back-compat; the canonical pin lives in `secrets-cli.ts` so a
+// version bump touches ONE place (PHNX-3989 consolidation).
+export const SECRETS_CLI_PACKAGE = SECRETS_CLI_SPEC;
 export const INSTALL_HINT = `agents clis install secrets   # or: npm i -g ${SECRETS_CLI_PACKAGE}`;
 export function setupSecretsPrefsPath() {
     return path.join(getHistoryDir(), 'setup', 'secrets.json');
@@ -56,7 +62,8 @@ export function installSecretsCli() {
             console.error(chalk.gray(result.error));
     }
     console.log(chalk.gray(`Installing ${SECRETS_CLI_PACKAGE}…`));
-    const r = spawnSync('npm', ['install', '-g', SECRETS_CLI_PACKAGE], { stdio: 'inherit' });
+    const npm = execFileShellSpec('npm', ['install', '-g', SECRETS_CLI_PACKAGE]);
+    const r = spawnSync(npm.command, npm.args, { stdio: 'inherit', shell: npm.shell });
     _resetSecretsClientForTest();
     if (r.error) {
         console.error(chalk.red(`npm install failed: ${r.error.message}`));
@@ -93,8 +100,21 @@ export function registerSetupSecretsCommand(setupCmd) {
     setupCmd
         .command('secrets')
         .description('Install the standalone `secrets` CLI if missing, then run its `secrets migrate` onboarding.')
-        .action(async () => {
-        if (!(await runSecretsSetupWizard()))
+        .option('--install-only', 'Install the standalone Secrets CLI without migrating or unlocking secrets')
+        .option('--terminal [backend]', 'Open interactive setup in a detected or selected terminal')
+        .action(async (options) => {
+        if (options.terminal !== undefined) {
+            try {
+                await openSetupTerminal('secrets', options.terminal, options.installOnly);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                process.exitCode = 1;
+            }
+            return;
+        }
+        if (!(options.installOnly ? installSecretsCli() : await runSecretsSetupWizard()))
             process.exitCode = 1;
+        await refreshToolSetup('secrets');
     });
 }

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-terminal.d.ts

@@ -0,0 +1,3 @@
+import type { SetupTool } from '../lib/setup-tool-status.js';
+/** The GUI starts a terminal; the terminal child owns wizard completion. */
+export declare function openSetupTerminal(tool: SetupTool, terminal: boolean | string, installOnly?: boolean): Promise<void>;

package/dist/commands/setup-terminal.js

@@ -0,0 +1,22 @@
+import os from 'node:os';
+import { currentContext, openRunInTerminal, parseTerminalFlag } from '../lib/terminal/index.js';
+/** The GUI starts a terminal; the terminal child owns wizard completion. */
+export async function openSetupTerminal(tool, terminal, installOnly = false) {
+    if (installOnly)
+        throw new Error('--terminal and --install-only are separate setup modes.');
+    const parsed = parseTerminalFlag(terminal);
+    if (parsed.error)
+        throw new Error(parsed.error);
+    const { readActiveSessionsCache } = await import('../lib/session/session-cache.js');
+    const sessions = parsed.backend ? [] : (readActiveSessionsCache('local')?.sessions ?? []).map(({ host, lastActivityMs, startedAtMs }) => ({ host, lastActivityMs, startedAtMs }));
+    const result = await openRunInTerminal({
+        argv: ['setup', tool],
+        forced: parsed.backend,
+        cwd: os.homedir(),
+        sessions,
+        ctx: currentContext(),
+    });
+    if (!result.ok)
+        throw new Error(result.error ?? 'Could not open a terminal for setup.');
+    console.log(result.description ?? 'Setup opened in a terminal.');
+}

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' | 'share' | '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;