@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/session/remote/remote-list.d.ts

@@ -145,7 +145,23 @@ export declare function fetchPeerPreviewDigest(sessionId: string, machine: strin
  * `opts.sessionId` (with `tty`) prints the session id and resume command when
  * the SSH hop ends, so OpenSSH's `Shared connection … closed.` is not the last
  * thing on the local shell (RUSH-3227). Omit it for one-shot non-TTY renders.
+ *
+ * Resolves `'unreachable'` when the SSH connection itself failed — ssh could not
+ * launch (spawn error) or exited with {@link SSH_CONN_FAILURE_CODE} (255, its
+ * connect-failure convention) — as opposed to `'ok'` for a hop that actually
+ * reached the peer (whatever the remote command's own exit code). This lets a
+ * caller prefer the recorded device yet fall back locally when it is genuinely
+ * offline (PHNX-3626); callers that ignore `'unreachable'` behave exactly as
+ * before (it was `'ok'`).
+ */
+/**
+ * Classify a finished SSH hop by its exit code: `'unreachable'` when the
+ * connection itself failed (ssh's {@link SSH_CONN_FAILURE_CODE} = 255, or a null
+ * code from a killed/never-launched child), else `'ok'` — the remote command ran,
+ * whatever its own exit status. Pure so the offline-device fallback is unit-tested
+ * without a live SSH hop (PHNX-3626).
  */
+export declare function peerHopOutcome(code: number | null): 'ok' | 'unreachable';
 export declare function peerHopCloseNotice(opts: {
     tty?: boolean;
     sessionId?: string;
@@ -154,4 +170,4 @@ export declare function runOnPeer(args: string[], machine: string, opts?: {
     tty?: boolean;
     env?: Record<string, string>;
     sessionId?: string;
-}): Promise<'ok' | 'no-target'>;
+}): Promise<'ok' | 'no-target' | 'unreachable'>;

package/dist/lib/session/remote/remote-list.js

@@ -582,7 +582,25 @@ export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEE
  * `opts.sessionId` (with `tty`) prints the session id and resume command when
  * the SSH hop ends, so OpenSSH's `Shared connection … closed.` is not the last
  * thing on the local shell (RUSH-3227). Omit it for one-shot non-TTY renders.
+ *
+ * Resolves `'unreachable'` when the SSH connection itself failed — ssh could not
+ * launch (spawn error) or exited with {@link SSH_CONN_FAILURE_CODE} (255, its
+ * connect-failure convention) — as opposed to `'ok'` for a hop that actually
+ * reached the peer (whatever the remote command's own exit code). This lets a
+ * caller prefer the recorded device yet fall back locally when it is genuinely
+ * offline (PHNX-3626); callers that ignore `'unreachable'` behave exactly as
+ * before (it was `'ok'`).
+ */
+/**
+ * Classify a finished SSH hop by its exit code: `'unreachable'` when the
+ * connection itself failed (ssh's {@link SSH_CONN_FAILURE_CODE} = 255, or a null
+ * code from a killed/never-launched child), else `'ok'` — the remote command ran,
+ * whatever its own exit status. Pure so the offline-device fallback is unit-tested
+ * without a live SSH hop (PHNX-3626).
  */
+export function peerHopOutcome(code) {
+    return code === SSH_CONN_FAILURE_CODE || code === null ? 'unreachable' : 'ok';
+}
 export function peerHopCloseNotice(opts, machine, code) {
     if (!opts.tty || !opts.sessionId)
         return undefined;
@@ -596,9 +614,13 @@ export async function runOnPeer(args, machine, opts = {}) {
     const cols = terminalWidth();
     const env = { ...(cols > 0 ? { COLUMNS: String(cols) } : {}), ...opts.env };
     const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+    const invocation = assignments.concat(['agents', ...args].map(shellQuote)).join(' ');
+    // OpenSSH uses 255 for transport failure, but also propagates a reached remote
+    // program's 255 verbatim. Remap only the remote program's 255 inside the peer
+    // shell so the outer SSH status remains an unambiguous connectivity signal.
     const remoteCmd = remoteShellFor(peer.os) === 'powershell'
-        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined })
-        : `bash -lc ${shellQuote(assignments.concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined, remapExit255: true })
+        : `bash -lc ${shellQuote(`${invocation}; agents_rc=$?; if [ "$agents_rc" -eq 255 ]; then exit 254; fi; exit "$agents_rc"`)}`;
     const sshArgs = [...SSH_OPTS, ...controlOpts()];
     if (opts.tty)
         sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive
@@ -610,7 +632,7 @@ export async function runOnPeer(args, machine, opts = {}) {
         // we resolve once it settles so the picker flow completes.
         child.on('error', (err) => {
             process.stderr.write(chalk.red(`Failed to reach ${machine}: ${err?.message ?? 'ssh failed to launch'}\n`));
-            resolve('ok');
+            resolve('unreachable');
         });
         child.on('close', (code) => {
             // Interactive TTY hop: OpenSSH prints "Shared connection … closed." and
@@ -618,7 +640,10 @@ export async function runOnPeer(args, machine, opts = {}) {
             const notice = peerHopCloseNotice(opts, machine, code);
             if (notice)
                 process.stderr.write(notice);
-            resolve('ok');
+            // ssh exits 255 only when the connection itself failed (host down/asleep),
+            // distinct from the remote command's own non-zero exit. Report that so a
+            // caller can fall back locally instead of silently completing.
+            resolve(peerHopOutcome(code));
         });
     });
 }

package/dist/lib/session/remote/watch.d.ts

@@ -1,7 +1,9 @@
 import { type ActiveSession } from '../active.js';
+import type { SessionMeta } from '../types.js';
 import { readActiveSessionsCache } from '../session-cache.js';
 export declare const SESSION_WATCH_VERSION: 1;
 export declare const SESSION_WATCH_HEARTBEAT_MS = 15000;
+export declare const SESSION_WATCH_PREVIOUS_LIMIT = 50;
 export type SessionWatchScopeStatus = 'available' | 'unavailable';
 export type SessionWatchEnvelope = {
     version: 1;
@@ -45,9 +47,15 @@ export type SessionWatchEnvelope = {
     scope: string;
     capturedAt: number;
 };
-export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
+export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn' | 'context'> {
+    context: ActiveSession['context'] | 'recent';
+    /** Flat durable branch for history rows that are not currently in a worktree. */
+    branch?: string;
     rowKey: string;
     sourceDevice: string;
+    /** Durable index rows are kept on the stream under a distinct identity so a
+     * live row can replace/disappear without erasing its recoverable history. */
+    previous: boolean;
     resumable: boolean;
     unwatched: boolean;
     viewingIn: string | null;
@@ -60,6 +68,13 @@ export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
 /** Stable, opaque identity for one row within one device scope. */
 export declare function sessionWatchRowKey(scope: string, row: ActiveSession): string;
 export declare function toSessionWatchRow(scope: string, row: ActiveSession): SessionWatchRow;
+/** Stable identity for a durable Previous row. It is deliberately distinct
+ * from the live row key for the same session id: both may coexist on the one
+ * stream, and the presentation layer lets the live row win while it exists. */
+export declare function previousSessionWatchRowKey(scope: string, sessionId: string): string;
+/** Project one durable indexed session into the same canonical watch contract
+ * as live sessions. This is the only history backfill consumed by AGI EXT. */
+export declare function toPreviousSessionWatchRow(scope: string, session: SessionMeta): SessionWatchRow;
 /** Stream-local sequencer and convergent row diff. */
 export declare class SessionWatchState {
     readonly streamId: string;
@@ -67,7 +82,10 @@ export declare class SessionWatchState {
     private readonly rows;
     constructor(streamId?: string);
     private base;
-    reset(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope;
+    /** Keep one visible Previous row per session and the newest bounded window.
+     * Returns removed keys so delta callers can converge already-connected clients. */
+    private prunePrevious;
+    reset(scope: string, sourceRows: ActiveSession[], indexedRows?: SessionMeta[]): SessionWatchEnvelope;
     update(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope[];
     patch(scope: string, upserts: ActiveSession[], removes: string[]): SessionWatchEnvelope[];
     scope(scope: string, status: SessionWatchScopeStatus, reason?: string): SessionWatchEnvelope;
@@ -80,9 +98,14 @@ export interface WatchLocalOptions {
     refreshMs?: number;
     heartbeatMs?: number;
     readCache?: typeof readActiveSessionsCache;
+    readPrevious?: (scope: string) => SessionMeta[];
     journalPath?: string;
     journalPollMs?: number;
 }
+/** One bounded index read when the watch starts. The stream then owns this
+ * projection: active rows update through the journal, and removals demote into
+ * Previous rows without another transcript/index poll. */
+export declare function readPreviousSessionsForWatch(scope: string): SessionMeta[];
 /**
  * Keep one local subscription alive. Startup reads one canonical reset snapshot;
  * steady state tails the canonical writer journal and never invokes a gather.

package/dist/lib/session/remote/watch.js

@@ -9,9 +9,13 @@ import { machineId, normalizeHost } from '../../machine-id.js';
 import { SSH_OPTS, controlOpts, shellQuote } from '../../ssh-exec.js';
 import { buildWindowsAgentsCommand, remoteShellFor } from '../../hosts/remote-cmd.js';
 import { isReapableOrphan } from '../active.js';
+import { querySessions } from '../db.js';
+import { linearIssueUrl } from '../linear.js';
+import { sessionAgentSupportsResume } from '../recovery.js';
 import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, noteActiveSessionsJournalReader, } from '../session-cache.js';
 export const SESSION_WATCH_VERSION = 1;
 export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
+export const SESSION_WATCH_PREVIOUS_LIMIT = 50;
 /** Stable, opaque identity for one row within one device scope. */
 export function sessionWatchRowKey(scope, row) {
     const identity = activeSessionJournalIdentity(row);
@@ -24,6 +28,9 @@ export function toSessionWatchRow(scope, row) {
     // leaked --device tunnel sessions (RUSH-3011 / issue #3b). A live or
     // recently-exited session stays resumable.
     const resumable = Boolean(row.sessionId) && !isReapableOrphan(row);
+    const previous = row.status === 'closed'
+        || row.status === 'crashed'
+        || (row.status === 'abandoned' && row.pidAlive === false);
     const viewingIn = row.viewingIn
         ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
         : null;
@@ -31,6 +38,7 @@ export function toSessionWatchRow(scope, row) {
         ...row,
         rowKey,
         sourceDevice: scope,
+        previous,
         resumable,
         unwatched: !viewingIn,
         viewingIn,
@@ -39,6 +47,88 @@ export function toSessionWatchRow(scope, row) {
             : null,
     };
 }
+function epochMs(value) {
+    const parsed = value ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** Stable identity for a durable Previous row. It is deliberately distinct
+ * from the live row key for the same session id: both may coexist on the one
+ * stream, and the presentation layer lets the live row win while it exists. */
+export function previousSessionWatchRowKey(scope, sessionId) {
+    return createHash('sha256').update(`${scope}\0previous\0${sessionId}`).digest('base64url').slice(0, 22);
+}
+/** Project one durable indexed session into the same canonical watch contract
+ * as live sessions. This is the only history backfill consumed by AGI EXT. */
+export function toPreviousSessionWatchRow(scope, session) {
+    const resumable = sessionAgentSupportsResume(session.agent);
+    const sourceDevice = normalizeHost(session.machine ?? scope);
+    const startedAtMs = epochMs(session.timestamp);
+    const lastActivityMs = epochMs(session.lastActivity) || startedAtMs;
+    const worktree = session.worktreeSlug && session.cwd
+        ? { slug: session.worktreeSlug, path: session.cwd, ...(session.gitBranch ? { branch: session.gitBranch } : {}) }
+        : undefined;
+    return {
+        context: 'recent',
+        kind: session.agent,
+        ...(session.harness ? { harness: session.harness } : {}),
+        sessionId: session.id,
+        ...(session.cwd ? { cwd: session.cwd } : {}),
+        ...(session.project ? { project: session.project } : {}),
+        ...(session.label ? { label: session.label, title: session.label } : session.topic ? { title: session.topic } : {}),
+        ...(session.topic ? { topic: session.topic } : {}),
+        ...(session.firstUserMessage ? { firstUserMessage: session.firstUserMessage } : {}),
+        ...(session.version ? { version: session.version } : {}),
+        ...(session.account ? { account: session.account } : {}),
+        ...(session.prUrl ? { pr: { url: session.prUrl, number: session.prNumber } } : {}),
+        ...(worktree ? { worktree } : {}),
+        ...(session.gitBranch ? { branch: session.gitBranch } : {}),
+        ...(session.ticketId ? { ticket: { id: session.ticketId, url: linearIssueUrl(session.ticketId) } } : {}),
+        ...(session.createdTickets ? { createdTickets: session.createdTickets } : {}),
+        ...(session.spawnedTeam ? { spawnedTeam: session.spawnedTeam } : {}),
+        ...(session.tokenCount != null ? { tokenCount: session.tokenCount } : {}),
+        ...(session.durationMs != null ? { durationMs: session.durationMs } : {}),
+        ...(session.subAgentCount != null ? { subAgentCount: session.subAgentCount } : {}),
+        startedAtMs,
+        lastActivityMs,
+        status: 'closed',
+        phase: 'done',
+        pidAlive: false,
+        rowKey: previousSessionWatchRowKey(scope, session.id),
+        sourceDevice,
+        previous: true,
+        resumable,
+        unwatched: true,
+        viewingIn: null,
+        recovery: resumable
+            ? { command: 'agents', args: ['sessions', 'resume', session.id, '--device', sourceDevice], ...(session.cwd ? { cwd: session.cwd } : {}) }
+            : null,
+    };
+}
+function demoteWatchRow(scope, row) {
+    if (!row.sessionId || row.rowKey === previousSessionWatchRowKey(scope, row.sessionId))
+        return null;
+    const sourceDevice = row.sourceDevice || scope;
+    return {
+        ...row,
+        context: 'recent',
+        status: 'closed',
+        phase: 'done',
+        pidAlive: false,
+        rowKey: previousSessionWatchRowKey(scope, row.sessionId),
+        previous: true,
+        unwatched: true,
+        viewingIn: null,
+        recovery: row.resumable
+            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', sourceDevice], ...(row.cwd ? { cwd: row.cwd } : {}) }
+            : null,
+    };
+}
+function isDurablePreviousRow(scope, row) {
+    return Boolean(row.sessionId) && row.rowKey === previousSessionWatchRowKey(scope, row.sessionId);
+}
+function rowRecency(row) {
+    return row.lastActivityMs ?? row.startedAtMs ?? 0;
+}
 function sameRow(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
@@ -51,24 +141,77 @@ export class SessionWatchState {
     base(type) {
         return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
     }
-    reset(scope, sourceRows) {
-        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
-        return { ...this.base('reset'), scope, rows };
+    /** Keep one visible Previous row per session and the newest bounded window.
+     * Returns removed keys so delta callers can converge already-connected clients. */
+    prunePrevious(scope, rows) {
+        const removed = [];
+        const bySession = new Map();
+        for (const row of rows.values()) {
+            if (!row.previous || !row.sessionId)
+                continue;
+            const existing = bySession.get(row.sessionId);
+            if (!existing) {
+                bySession.set(row.sessionId, row);
+                continue;
+            }
+            const keepRow = rowRecency(row) > rowRecency(existing)
+                || (rowRecency(row) === rowRecency(existing) && isDurablePreviousRow(scope, row));
+            const drop = keepRow ? existing : row;
+            const keep = keepRow ? row : existing;
+            if (rows.delete(drop.rowKey))
+                removed.push(drop.rowKey);
+            bySession.set(row.sessionId, keep);
+        }
+        const previous = [...bySession.values()].sort((a, b) => rowRecency(b) - rowRecency(a));
+        for (const row of previous.slice(SESSION_WATCH_PREVIOUS_LIMIT)) {
+            if (rows.delete(row.rowKey))
+                removed.push(row.rowKey);
+        }
+        return removed;
+    }
+    reset(scope, sourceRows, indexedRows = []) {
+        const liveRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        const sourceIds = new Set(liveRows.map((row) => row.sessionId).filter((id) => Boolean(id)));
+        const rows = new Map(liveRows.map((row) => [row.rowKey, row]));
+        for (const indexed of indexedRows) {
+            if (sourceIds.has(indexed.id))
+                continue;
+            const row = toPreviousSessionWatchRow(scope, indexed);
+            rows.set(row.rowKey, row);
+        }
+        this.prunePrevious(scope, rows);
+        this.rows.set(scope, rows);
+        return { ...this.base('reset'), scope, rows: [...rows.values()] };
     }
     update(scope, sourceRows) {
         const previous = this.rows.get(scope) ?? new Map();
         const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
+        const activeIds = new Set(nextRows.filter((row) => !row.previous).map((row) => row.sessionId).filter((id) => Boolean(id)));
+        const next = new Map([...previous.values()]
+            .filter((row) => isDurablePreviousRow(scope, row) && (!row.sessionId || !activeIds.has(row.sessionId)))
+            .map((row) => [row.rowKey, row]));
+        for (const row of nextRows)
+            next.set(row.rowKey, row);
         const events = [];
         for (const [rowKey, row] of next) {
             if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
                 events.push({ ...this.base('upsert'), scope, rowKey, row });
             }
         }
-        for (const rowKey of previous.keys()) {
-            if (!next.has(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
+        for (const [rowKey, row] of previous) {
+            if (next.has(rowKey))
+                continue;
+            if (isDurablePreviousRow(scope, row) && (!row.sessionId || !activeIds.has(row.sessionId)))
+                continue;
+            events.push({ ...this.base('remove'), scope, rowKey });
+            const demoted = demoteWatchRow(scope, row);
+            if (demoted && (!next.has(demoted.rowKey) || !sameRow(next.get(demoted.rowKey), demoted))) {
+                next.set(demoted.rowKey, demoted);
+                events.push({ ...this.base('upsert'), scope, rowKey: demoted.rowKey, row: demoted });
+            }
+        }
+        for (const rowKey of this.prunePrevious(scope, next)) {
+            events.push({ ...this.base('remove'), scope, rowKey });
         }
         this.rows.set(scope, next);
         return events;
@@ -78,6 +221,11 @@ export class SessionWatchState {
         const events = [];
         for (const source of upserts) {
             const row = toSessionWatchRow(scope, source);
+            if (!row.previous && row.sessionId) {
+                const previousKey = previousSessionWatchRowKey(scope, row.sessionId);
+                if (current.delete(previousKey))
+                    events.push({ ...this.base('remove'), scope, rowKey: previousKey });
+            }
             if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
                 current.set(row.rowKey, row);
                 events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
@@ -85,8 +233,18 @@ export class SessionWatchState {
         }
         for (const identity of removes) {
             const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
-            if (current.delete(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
+            const removed = current.get(rowKey);
+            if (!current.delete(rowKey))
+                continue;
+            events.push({ ...this.base('remove'), scope, rowKey });
+            const demoted = removed ? demoteWatchRow(scope, removed) : null;
+            if (demoted && (!current.has(demoted.rowKey) || !sameRow(current.get(demoted.rowKey), demoted))) {
+                current.set(demoted.rowKey, demoted);
+                events.push({ ...this.base('upsert'), scope, rowKey: demoted.rowKey, row: demoted });
+            }
+        }
+        for (const rowKey of this.prunePrevious(scope, current)) {
+            events.push({ ...this.base('remove'), scope, rowKey });
         }
         this.rows.set(scope, current);
         return events;
@@ -100,6 +258,21 @@ export class SessionWatchState {
         return { ...this.base('heartbeat'), scope, capturedAt };
     }
 }
+/** One bounded index read when the watch starts. The stream then owns this
+ * projection: active rows update through the journal, and removals demote into
+ * Previous rows without another transcript/index poll. */
+export function readPreviousSessionsForWatch(scope) {
+    try {
+        return querySessions({
+            machine: normalizeHost(scope),
+            limit: SESSION_WATCH_PREVIOUS_LIMIT,
+            excludeTeamOrigin: true,
+        });
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Keep one local subscription alive. Startup reads one canonical reset snapshot;
  * steady state tails the canonical writer journal and never invokes a gather.
@@ -107,6 +280,7 @@ export class SessionWatchState {
 export async function watchLocalSessions(options) {
     const state = new SessionWatchState();
     const readCache = options.readCache ?? readActiveSessionsCache;
+    const readPrevious = options.readPrevious ?? readPreviousSessionsForWatch;
     const journal = options.journalPath ?? activeSessionsJournalPath();
     const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
     let offset = 0;
@@ -115,7 +289,7 @@ export async function watchLocalSessions(options) {
     }
     catch { /* first publication */ }
     const initial = readCache('local');
-    options.emit(state.reset(options.scope, initial?.sessions ?? []));
+    options.emit(state.reset(options.scope, initial?.sessions ?? [], readPrevious(options.scope)));
     // Known gap (out of scope for RUSH-2484): a present cache alone marks
     // 'available' with no staleness/age check, so a reconnect can briefly render
     // a stale snapshot as live before the out-of-band gather this file triggers

package/dist/lib/session/session-cache.d.ts

@@ -32,6 +32,7 @@ export declare function activeSessionJournalIdentity(row: ActiveSession): string
  */
 export interface ImmutableSessionFields {
     topic?: string;
+    firstUserMessage?: string;
     label?: string;
     name?: string;
     cwd?: string;
@@ -51,7 +52,7 @@ export interface ImmutableSessionFields {
     context?: ActiveSession['context'];
 }
 /** Keys stored in the immutable memo (transcript-stable). */
-export declare const IMMUTABLE_FIELD_KEYS: readonly ["topic", "label", "name", "cwd", "project", "attachments", "startedAtMs", "version", "pr", "worktree", "ticket", "createdTickets", "spawnedTeam", "sessionFile", "owner", "assignedTask", "kind", "context"];
+export declare const IMMUTABLE_FIELD_KEYS: readonly ["topic", "firstUserMessage", "label", "name", "cwd", "project", "attachments", "startedAtMs", "version", "pr", "worktree", "ticket", "createdTickets", "spawnedTeam", "sessionFile", "owner", "assignedTask", "kind", "context"];
 /**
  * Live / volatile fields that MUST NOT be served from the immutable memo.
  * They either change without a transcript write (pid death, attach state) or

package/dist/lib/session/session-cache.js

@@ -51,6 +51,7 @@ const activeSnapshotMemory = createMemoryCache({
 /** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',
+    'firstUserMessage',
     'label',
     'name',
     'cwd',

package/dist/lib/session/types.d.ts

@@ -232,6 +232,8 @@ export interface SessionMeta {
     /** Effective normalized launch mode captured by the SessionStart hook. */
     mode?: SessionRunMode;
     topic?: string;
+    /** Full, cleaned first genuine user turn; distinct from the one-line topic. */
+    firstUserMessage?: string;
     /**
      * The session's human-readable name — one field, several sources with a plain
      * priority: an agent-generated title / Claude `/rename` wins; else the launch

package/dist/lib/share/publish.d.ts

@@ -24,9 +24,12 @@ export interface PublishOptions {
     /**
      * Server-enforced visibility (RUSH-3135). `public` (default) is listed in
      * the gallery; `unlisted` is a capability URL (GET still 200, X-Robots-Tag:
-     * noindex, hidden from gallery/list). `me` requires a Phoenix session and is
-     * visible only to the signed-in owner; `org` requires the same and is visible
-     * to members of the same Phoenix organization.
+     * noindex, hidden from gallery/list — obscurity, NOT authentication);
+     * `private` is token-gated (the Worker serves it only to a request carrying
+     * the matching viewer key, else 404 — the real read-auth fix, PHNX-3654);
+     * `me` requires a Phoenix session and is visible only to the signed-in owner;
+     * `org` requires the same and is visible to members of the same Phoenix
+     * organization.
      */
     visibility?: ShareVisibility;
     /**
@@ -37,6 +40,14 @@ export interface PublishOptions {
      * not break.
      */
     unlisted?: boolean;
+    /**
+     * Token-gate this page (`--protected` → `visibility=private`, PHNX-3654). The
+     * CLI mints a random viewer token, the Worker stores only its SHA-256 hash,
+     * and the published URL carries `?k=<token>`; a request without a matching
+     * `?k=` / `Authorization: Bearer` gets a `404`. Unlike `unlisted` (obscurity),
+     * this is enforced read-auth. Alias of `--visibility private`.
+     */
+    protected?: boolean;
     /**
      * Bypass the pre-publish sensitive-content scan (emails / credential-shaped
      * strings). Required when the page intentionally carries those patterns.
@@ -91,9 +102,17 @@ export interface PublishOptions {
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
-export type ShareVisibility = 'public' | 'unlisted' | 'me' | 'org';
-/** The visibility levels a share may carry — the Worker's own set, used to
- * validate `--visibility` and `share visibility <target> <level>`. */
+export type ShareVisibility = 'public' | 'unlisted' | 'private' | 'me' | 'org';
+/** The visibility levels a publish `--visibility` may select — the Worker's own
+ * set. `private` (token-gated, PHNX-3654) is settable only at publish time,
+ * since it mints a viewer token the metadata-edit route can't carry, so it is
+ * NOT in {@link SHARE_VISIBILITY_LEVELS} (the in-place `share visibility <level>`
+ * set). */
+export declare const PUBLISH_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/** The visibility levels an ALREADY-published share may be re-scoped to in place
+ * — the set `share visibility <target> <level>` and the inline owner control
+ * accept. Excludes `private`: re-scoping to token-gated needs a fresh viewer
+ * token, which only the publish path mints. */
 export declare const SHARE_VISIBILITY_LEVELS: readonly ShareVisibility[];
 export interface PublishResult {
     url: string;
@@ -105,19 +124,46 @@ export interface PublishResult {
     visibility?: ShareVisibility;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
+    /** The raw viewer token minted for a `private` (token-gated) publish, or
+     * undefined for any other visibility. It rides in {@link url} as `?k=<token>`;
+     * only its hash is stored server-side. Treat as a secret. */
+    viewerToken?: string;
     /** The label stored with this share — explicit (`--label`) or derived. */
     label?: string;
     /** Whether `label` came from `--label` or was auto-derived. */
     labelSource?: 'explicit' | 'derived';
 }
 /**
- * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
- * passes through; otherwise `visibility` (default public).
+ * `--protected` / `{ protected: true }` map to `private` (token-gated — it wins
+ * over `--unlisted` when both are set, being the stronger control); `--unlisted`
+ * maps to `unlisted`; `--visibility private|unlisted|me|org` passes through;
+ * otherwise `visibility` (default public).
  */
 export declare function resolveShareVisibility(opts?: {
     visibility?: ShareVisibility;
     unlisted?: boolean;
+    protected?: boolean;
 }): ShareVisibility;
+/** Mint a fresh random viewer token for a `private` (token-gated) publish. The
+ * raw token rides ONLY in the returned URL's `?k=`; the Worker stores just its
+ * SHA-256 hash, so the object metadata never carries the secret. */
+export declare function generateViewerToken(): string;
+/** SHA-256 hex of a viewer token — the form the Worker also computes and stores,
+ * so a CLI-side preview of the stored hash matches. Exported for tests. */
+export declare function hashViewerToken(token: string): string;
+/** A 64-bit random slug tail (16 lowercase hex chars) for a capability-URL
+ * publish, so the slug can never be derived/guessed from the title (PHNX-3654).
+ * `unlisted` leans on this for obscurity; `private` uses it as defense-in-depth
+ * behind the viewer token. */
+export declare function randomSlugTail(): string;
+/**
+ * The loud stderr warning printed on an `unlisted` / `--private` publish
+ * (PHNX-3654): `unlisted` is obscurity, NOT read-authentication — anyone with
+ * the URL can read it. Points the user at the real controls (`--protected`,
+ * `--expire`, `me`/`org`). Lives here beside the visibility logic; `share.ts`
+ * prints it so the lib layer stays free of `console.*`.
+ */
+export declare function unlistedNotPrivateWarning(): string;
 export interface ShareProvenance {
     /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
     agent?: string;
@@ -136,7 +182,7 @@ export interface ShareProvenance {
  * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
  * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source", "og-title", "og-description", "og-generated", "og-source-etag"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "viewer-token-hash", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source", "og-title", "og-description", "og-generated", "og-source-etag"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a