@phnx-labs/agents-cli 1.22.115 → 1.22.117

package/dist/commands/feed.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed/feed.js';
+import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, deriveBlockState, publishBlock, } from '../lib/feed/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/feed/activity.js';
 import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
@@ -16,7 +16,7 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { loadPolicy, applyPolicyToBlock, isPhoneUrgent } from '../lib/feed-policy.js';
 import { notifyUrgentBlock } from '../lib/notify.js';
 import { registerFeedWatchCommand } from './feed-watch.js';
-import { claimAndRouteAttentionAnswer, forwardFeedAnswer } from '../lib/feed/answer.js';
+import { AnswerError, answerOwnerIsLocal, checkAnswerDelivery, claimAndRouteAttentionAnswer, forwardFeedAnswer, parseAttentionKey, } from '../lib/feed/answer.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { isValidMailboxId } from '../lib/mailbox.js';
 import { getActiveSessions } from '../lib/session/active.js';
@@ -171,7 +171,10 @@ function renderBlock(b, localHost, indent = '') {
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
     const rank = b.delayRank ? chalk.gray(`rank:${Math.round(b.delayRank.score)}`) : '';
     // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
-    const marker = b.answer
+    // A PENDING claim carries an answer record while the block is still open, so
+    // the delivered glyph is driven by the canonical state, not by `b.answer`
+    // being set — a claimed-but-undelivered ask must keep reading as needs-you.
+    const marker = deriveBlockState(b) !== 'open'
         ? chalk.green(GLYPH.delivered)
         : b.kind === 'control'
             ? chalk.red('!')
@@ -197,7 +200,9 @@ function renderBlock(b, localHost, indent = '') {
     if (b.answer) {
         const verified = b.answer.verified ? chalk.green(GLYPH.delivered) : chalk.yellow('?');
         const who = b.answer.answeredFrom + (b.answer.answeredBy ? ` (${b.answer.answeredBy})` : '');
-        console.log(`${indent}  ${chalk.green('answered')} by ${who} ${verified}`);
+        const pending = deriveBlockState(b) === 'open';
+        const label = pending ? chalk.yellow('claimed (delivery unconfirmed)') : chalk.green('answered');
+        console.log(`${indent}  ${label} by ${who} ${verified}`);
     }
     if (b.parkedAt) {
         console.log(`${indent}  ${chalk.red('hard-parked')} ${relTime(b.parkedAt)}`);
@@ -314,6 +319,23 @@ export async function loadSessionMetasForFeedEnrichment(load) {
         throw err;
     }
 }
+/**
+ * One human line per answer outcome. The three states the operator has to tell
+ * apart are a real receipt, a hand-off no rail can confirm, and a refusal —
+ * never collapsed into a single "Delivered" (PHNX-3999).
+ */
+function renderAnswerResult(result) {
+    switch (result.status) {
+        case 'failed':
+            return `Not delivered: ${result.reason ?? 'unknown failure'} — answering again is safe.`;
+        case 'unknown':
+            return `Delivery unconfirmed: ${result.reason ?? 'no rail reported a receipt.'} Run \`agents feed answer ${result.attentionKey} --check\` rather than resending.`;
+        case 'already_answered':
+            return `Already answered — ${result.receipt?.status ?? 'claimed'}${result.receipt ? ` as ${result.receipt.msgId}` : ''} at ${result.receipt?.at ?? result.attempt}.`;
+        default:
+            return `Delivered ${result.receipt?.msgId} (${result.receipt?.status}).`;
+    }
+}
 export function registerFeedCommand(program) {
     const feed = program
         .command('feed')
@@ -334,23 +356,52 @@ export function registerFeedCommand(program) {
         .option('--choice <choice-id>', 'Stable choice id from the attention item')
         .option('--text <answer>', 'Free-text answer')
         .option('--as <operator>', 'Verified operator id for high-consequence answers')
+        .option('--check', 'Read-only: report this item\'s delivery state without claiming, routing or resending')
+        .option('--attempt <at>', 'With --check: the attempt timestamp being checked, so a newer one is reported as such')
         .option('--json', 'Emit the delivery result as JSON')
         .action(async (attentionKey, opts, invoked) => {
+        const wantsJson = Boolean(opts.json || invoked.parent?.opts()?.json);
         try {
-            const ownerHost = attentionKey.slice(0, attentionKey.indexOf('/'));
-            const result = ownerHost && ownerHost !== machineId()
-                ? await forwardFeedAnswer({ host: ownerHost, attentionKey, choiceId: opts.choice, text: opts.text, operatorId: opts.as })
-                : await claimAndRouteAttentionAnswer({
-                    attentionKey, choiceId: opts.choice, text: opts.text,
-                    operator: { id: opts.as, verified: Boolean(opts.as), label: opts.as },
-                });
-            if (opts.json || invoked.parent?.opts()?.json)
+            // The key's own host decides the rail; `answerOwnerIsLocal` normalizes
+            // both sides so a `.local` suffix is not read as a different machine.
+            const { host: ownerHost } = parseAttentionKey(attentionKey);
+            const local = answerOwnerIsLocal(ownerHost);
+            if (opts.check && (opts.choice != null || opts.text != null)) {
+                throw new AnswerError('--check is read-only; it takes no --choice or --text.', 'empty_answer');
+            }
+            if (opts.attempt != null && !opts.check) {
+                throw new AnswerError('--attempt only applies to --check.', 'empty_answer');
+            }
+            const result = opts.check
+                ? (local
+                    ? checkAnswerDelivery(attentionKey, undefined, opts.attempt)
+                    : await forwardFeedAnswer({ host: ownerHost, attentionKey, check: true, attempt: opts.attempt, operatorId: opts.as }))
+                : local
+                    ? await claimAndRouteAttentionAnswer({
+                        attentionKey, choiceId: opts.choice, text: opts.text,
+                        operator: { id: opts.as, verified: Boolean(opts.as), label: opts.as },
+                    })
+                    : await forwardFeedAnswer({ host: ownerHost, attentionKey, choiceId: opts.choice, text: opts.text, operatorId: opts.as });
+            if (wantsJson)
                 console.log(JSON.stringify(result));
             else
-                console.log(result.status === 'delivered' ? `Delivered ${result.receipt.msgId}.` : `Already answered (${result.receipt.at}).`);
+                console.log(renderAnswerResult(result));
         }
         catch (error) {
-            invoked.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+            // A failure is a first-class outcome for the operator UI, not a parse
+            // error: `--json` still gets a result object it can branch on, with a
+            // non-zero exit so a scripted caller sees the failure too.
+            const message = error instanceof Error ? error.message : String(error);
+            if (wantsJson) {
+                const failure = {
+                    status: 'failed', delivery: 'failed', resolved: false, reason: message,
+                    code: error instanceof AnswerError ? error.code : 'rail_failed', attentionKey,
+                };
+                console.log(JSON.stringify(failure));
+                process.exitCode = 1;
+                return;
+            }
+            invoked.error(`error: ${message}`);
         }
     });
     feed

package/dist/commands/sessions-picker.d.ts

@@ -153,6 +153,17 @@ export interface SessionPreviewDigest {
     firstError?: string;
     toolHistogram: ReturnType<typeof toolHistogram>;
     test: ReturnType<typeof detectTestResult>;
+    /**
+     * True when this digest was built WITHOUT parsing the transcript (PHNX-3999):
+     * the file exceeded {@link PREVIEW_DIGEST_MAX_PARSE_BYTES} and no cached
+     * digest existed yet. `firstUser`/`lastAssistant` fall back to the already-
+     * indexed `SessionMeta.firstUserMessage`/`lastUserMessage` (cheap, no parse)
+     * rather than being silently empty; every event-derived field (toolCalls,
+     * changedFiles, artifacts, etc.) stays at its zero-value default because it
+     * genuinely was not computed, not because nothing happened.
+     */
+    partial?: boolean;
+    partialReason?: string;
 }
 /** Fold a harness-normalized event stream into the stable preview data model. */
 export declare function buildSessionPreviewDigest(events: SessionEvent[], session: SessionMeta): SessionPreviewDigest;

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,25 @@
+/**
+ * `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 setup-token mint behind `agents accounts
+ * add` / `agents accounts login` (auth-mint.ts → term-driver.ts) 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;