@phnx-labs/agents-cli 1.22.72 → 1.22.74

package/dist/lib/session/db.js

@@ -28,7 +28,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 45;
+export const SCHEMA_VERSION = 47;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -135,6 +135,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   linear_project_url TEXT,
   actor TEXT,
   initiated_by TEXT,
+  phoenix_id TEXT,
   used_browser INTEGER,
   used_computer INTEGER,
   -- Epoch ms of the first time a previously-scanned transcript was confirmed
@@ -143,7 +144,14 @@ CREATE TABLE IF NOT EXISTS sessions (
   -- DB and flagged, instead of being dropped when the file vanishes. A row whose
   -- file is missing but which has NO cached content is a phantom (a stale/moved
   -- file_path), never stamped, still suppressed — see querySessions.
-  archived_at INTEGER
+  archived_at INTEGER,
+  -- Epoch ms this row was last written from a PEER's synced session mirror
+  -- (PHNX-3792), NULL for a genuine local/host-dispatch row. Non-NULL marks a
+  -- row created/enriched purely from a fleet-synced digest so it can be pruned
+  -- by age without touching real rows; mirror_source names the publishing
+  -- device. A row keeps a NULL mirror_synced_at once it gains a real transcript.
+  mirror_synced_at INTEGER,
+  mirror_source TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -151,7 +159,8 @@ CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent);
 CREATE INDEX IF NOT EXISTS idx_sessions_file_path ON sessions(file_path);
 CREATE INDEX IF NOT EXISTS idx_sessions_short_id ON sessions(short_id);
 -- idx_sessions_machine_ts / idx_sessions_agent_ts are created after migration
--- v17 guarantees the machine column exists (same pattern as last_activity).
+-- v17 guarantees the machine column exists (same pattern as last_activity);
+-- idx_sessions_mirror_synced likewise waits for migration v46's column add.
 
 CREATE VIRTUAL TABLE IF NOT EXISTS session_text USING fts5(
   session_id UNINDEXED,
@@ -1247,6 +1256,29 @@ function migrateSchema(db, fromVersion) {
         if (!cols.has('first_user_message'))
             db.exec(`ALTER TABLE sessions ADD COLUMN first_user_message TEXT`);
     }
+    if (fromVersion < 46) {
+        // v45 -> v46: mirror provenance for fleet-synced peer session digests
+        // (PHNX-3792). Additive columns, no ledger wipe: they are written only by the
+        // session-mirror consume path (never a transcript scan), so re-parsing every
+        // indexed transcript would be pure churn — a genuine local row keeps them NULL.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('mirror_synced_at'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN mirror_synced_at INTEGER`);
+        if (!cols.has('mirror_source'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN mirror_source TEXT`);
+        // The idx_sessions_mirror_synced index is created unconditionally after this
+        // block (fresh DBs skip migrations), alongside idx_sessions_last_activity.
+    }
+    if (fromVersion < 47) {
+        // v46 -> v47: carry the actor's Phoenix id (PHNX-3798). Additive, write-once
+        // launch metadata joined from the actor sidecar — never transcript-derived,
+        // exactly like actor/initiated_by (v19) — so there is no ledger wipe: a rescan
+        // can't backfill it and forcing a full re-parse would be pure churn. Existing
+        // rows stay NULL until the sidecar-join fills them (the ON CONFLICT COALESCEs).
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('phoenix_id'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN phoenix_id TEXT`);
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -1322,6 +1354,10 @@ export function getDB() {
     // DB would fail the index build on a column it doesn't have yet.
     db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_last_activity ON sessions(last_activity DESC)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_origin ON sessions(origin)`);
+    // Same fresh-vs-migrated rule: the column is guaranteed above (fresh from
+    // CREATE TABLE, existing from migration v46), so index the mirror pruner's
+    // scan column here rather than in SCHEMA (PHNX-3792).
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_mirror_synced ON sessions(mirror_synced_at)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_routine_run_id ON sessions(routine_run_id)`);
     // Account attribution repair. Two ways a Claude row ends up wrong even at v33:
     // an older CLI (whose INSERT does not name the column) writes NULL, and a DB
@@ -1796,7 +1832,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     pr_url, pr_number, worktree_slug, ticket_id, spawned_team,
     sub_agent_count, background_shell_count, plan, todos,
     recent_directories_touched, linear_project, linear_project_url, machine,
-    actor, initiated_by, used_browser, used_computer
+    actor, initiated_by, phoenix_id, used_browser, used_computer
   ) VALUES (
     @id, @short_id, @agent, @harness, @origin, @routine_name, @routine_run_id,
     @version, @account, @account_key, @account_org, @mode, @timestamp, @last_activity,
@@ -1807,7 +1843,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team,
     @sub_agent_count, @background_shell_count, @plan, @todos,
     @recent_directories_touched, @linear_project, @linear_project_url, @machine,
-    @actor, @initiated_by, @used_browser, @used_computer
+    @actor, @initiated_by, @phoenix_id, @used_browser, @used_computer
   )
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
@@ -1891,7 +1927,28 @@ const upsertSessionStmt = (db) => db.prepare(`
     -- the actor sidecar landed — once the sidecar-join finally provides one. Plain
     -- exclusion locked those rows to NULL forever (RUSH-2018/2019 fix).
     actor = COALESCE(sessions.actor, excluded.actor),
-    initiated_by = COALESCE(sessions.initiated_by, excluded.initiated_by)
+    initiated_by = COALESCE(sessions.initiated_by, excluded.initiated_by),
+    -- Phoenix id rides the same write-once join as actor/initiated_by: a rescan
+    -- carries none (excluded.phoenix_id is NULL -> stored value wins), but a row
+    -- indexed NULL-first backfills once the sidecar-join finally provides one.
+    phoenix_id = COALESCE(sessions.phoenix_id, excluded.phoenix_id),
+    -- A genuine local transcript write (the scanner always carries a non-empty
+    -- file_path) reclaims a row that was first seeded as a peer mirror: clear the
+    -- mirror provenance so pruneMirrorSessions (which deletes mirror_synced_at IS
+    -- NOT NULL rows past the age cutoff) can never delete real local content, and
+    -- so queryLocalOriginSessionsForMirror (mirror_synced_at IS NULL) re-publishes
+    -- it. Without this the stamp set by upsertMirrorSession survived a later real
+    -- scan, since an omitted column keeps its prior value on upsert (PHNX-3792).
+    -- An empty-file write (a host-dispatch stub) is NOT a real transcript, so it
+    -- leaves the stamp intact — matching the mirror guard's own file_path test.
+    mirror_synced_at = CASE
+      WHEN excluded.file_path IS NOT NULL AND excluded.file_path <> '' THEN NULL
+      ELSE sessions.mirror_synced_at
+    END,
+    mirror_source = CASE
+      WHEN excluded.file_path IS NOT NULL AND excluded.file_path <> '' THEN NULL
+      ELSE sessions.mirror_source
+    END
 `);
 /**
  * Did this session emit at least one browser/computer-automation event?
@@ -2159,6 +2216,7 @@ export function upsertSession(meta, content, scan, assistantContent = '') {
         machine: resolveMachine(meta),
         actor: meta.actor ?? actorRec?.actor ?? null,
         initiated_by: meta.initiatedBy ?? actorRec?.initiatedBy ?? null,
+        phoenix_id: meta.phoenixId ?? actorRec?.phoenixId ?? null,
         used_browser: toolUsage.usedBrowser ? 1 : 0,
         used_computer: toolUsage.usedComputer ? 1 : 0,
     };
@@ -2398,6 +2456,7 @@ export function upsertSessionsBatch(entries) {
                     machine: resolveMachine(meta),
                     actor: meta.actor ?? actorIndex.get(meta.id)?.actor ?? null,
                     initiated_by: meta.initiatedBy ?? actorIndex.get(meta.id)?.initiatedBy ?? null,
+                    phoenix_id: meta.phoenixId ?? actorIndex.get(meta.id)?.phoenixId ?? null,
                     used_browser: toolUsage.usedBrowser ? 1 : 0,
                     used_computer: toolUsage.usedComputer ? 1 : 0,
                 };
@@ -2633,6 +2692,7 @@ function rowToMeta(row) {
         // Narrow the free-text column to the known kinds; an unexpected value maps
         // to undefined rather than being asserted as a valid kind.
         initiatedBy: row.initiated_by === 'human' || row.initiated_by === 'agent' ? row.initiated_by : undefined,
+        phoenixId: row.phoenix_id ?? undefined,
         // NULL = never computed by this scanner (legacy row) — leave undefined so
         // the sessions picker knows to fall back to the transcript-regex detection
         // instead of trusting a false "never used browser/computer".
@@ -2643,6 +2703,8 @@ function rowToMeta(row) {
         // flagged, never dropped (RUSH-2436). NULL leaves both undefined (live row).
         archivedAt: row.archived_at ?? undefined,
         archived: row.archived_at != null ? true : undefined,
+        mirrorSyncedAt: row.mirror_synced_at ?? undefined,
+        mirrorSource: row.mirror_source ?? undefined,
     };
 }
 function isSessionRunMode(value) {
@@ -3278,6 +3340,129 @@ export function readArchivedSessionPreview(id) {
         return undefined;
     }
 }
+/**
+ * The most-recently-active sessions whose transcript is genuinely local to this
+ * box — a real `file_path`, not a peer mirror — for publishing to the fleet
+ * session mirror (PHNX-3792). Bounded and team-origin-excluded so the published
+ * payload stays the size a picker would show. Never returns a row this box is
+ * itself mirroring from a peer (`mirror_synced_at IS NULL`).
+ */
+export function queryLocalOriginSessionsForMirror(self, limit) {
+    const rows = getDB().prepare(`
+    SELECT id, short_id, agent, version, machine, cwd, topic, first_user_message,
+           label, last_activity, timestamp, ticket_id, pr_url
+    FROM sessions
+    WHERE mirror_synced_at IS NULL
+      AND file_path IS NOT NULL AND file_path <> ''
+      AND machine = ?
+      AND is_team_origin = 0
+      AND (topic IS NOT NULL OR first_user_message IS NOT NULL OR label IS NOT NULL)
+    ORDER BY last_activity DESC, timestamp DESC
+    LIMIT ?
+  `).all(self, limit);
+    return rows.map((r) => ({
+        id: r.id, shortId: r.short_id, agent: r.agent, version: r.version, machine: r.machine,
+        cwd: r.cwd, topic: r.topic, firstUserMessage: r.first_user_message, label: r.label,
+        lastActivity: r.last_activity, timestamp: r.timestamp, ticketId: r.ticket_id, prUrl: r.pr_url,
+    }));
+}
+/**
+ * Write one peer session's digest into the local `sessions` index as a mirror
+ * row (PHNX-3792), so the picker/list/focus render its topic/preview inline
+ * with no per-row SSH. The upsert is GUARDED: it never overwrites a genuine
+ * local transcript row (`file_path` non-empty and not itself a mirror), so a
+ * mirror can only create a new peer-only row or enrich an existing empty-file
+ * host-dispatch stub / older mirror. Returns true when a row was written (the
+ * caller then persists the matching preview digest); false when a real row was
+ * protected. `machine` carries the publisher's recorded execution host so the
+ * row collapses with the live fan-out row under the same `machine:id` key.
+ */
+export function upsertMirrorSession(row, source, syncedAt) {
+    const db = getDB();
+    const lastActivity = row.lastActivity ?? row.timestamp;
+    const result = db.prepare(`
+    INSERT INTO sessions (
+      id, short_id, agent, origin, version, timestamp, last_activity, cwd,
+      topic, first_user_message, label, message_count, file_path, scanned_at,
+      is_team_origin, ticket_id, pr_url, machine, mirror_synced_at, mirror_source
+    ) VALUES (
+      @id, @short_id, @agent, 'cli', @version, @timestamp, @last_activity, @cwd,
+      @topic, @first_user, @label, NULL, '', @scanned_at,
+      0, @ticket_id, @pr_url, @machine, @synced_at, @source
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      short_id = excluded.short_id,
+      agent = excluded.agent,
+      version = COALESCE(excluded.version, sessions.version),
+      timestamp = excluded.timestamp,
+      last_activity = excluded.last_activity,
+      cwd = COALESCE(excluded.cwd, sessions.cwd),
+      topic = COALESCE(excluded.topic, sessions.topic),
+      first_user_message = COALESCE(excluded.first_user_message, sessions.first_user_message),
+      -- The peer is authoritative for the session's real name, so OVERWRITE (not
+      -- COALESCE) the label: a host-dispatch stub carries the [host/peer]
+      -- placeholder, and coalescing would keep it forever — the exact bare-row
+      -- symptom this feature fixes. A null peer label clears it so the list falls
+      -- back to the synced topic.
+      label = excluded.label,
+      ticket_id = COALESCE(excluded.ticket_id, sessions.ticket_id),
+      pr_url = COALESCE(excluded.pr_url, sessions.pr_url),
+      machine = excluded.machine,
+      mirror_synced_at = excluded.mirror_synced_at,
+      mirror_source = excluded.mirror_source
+    WHERE sessions.file_path IS NULL OR sessions.file_path = '' OR sessions.mirror_synced_at IS NOT NULL
+  `).run({
+        id: row.id,
+        short_id: row.shortId,
+        agent: row.agent,
+        version: row.version ?? null,
+        timestamp: row.timestamp,
+        last_activity: lastActivity,
+        cwd: row.cwd ?? null,
+        topic: row.topic ?? null,
+        first_user: row.firstUser ?? null,
+        label: row.label ?? null,
+        ticket_id: row.ticketId ?? null,
+        pr_url: row.prUrl ?? null,
+        machine: row.machine,
+        scanned_at: syncedAt,
+        synced_at: syncedAt,
+        source,
+    });
+    if (result.changes === 0)
+        return false;
+    // Keep the mirror row searchable by topic + first user turn, like a local row.
+    db.prepare(`DELETE FROM session_text WHERE session_id = ?`).run(row.id);
+    db.prepare(`
+    INSERT INTO session_text (session_id, label, topic, project, content, assistant)
+    VALUES (?, ?, ?, '', ?, '')
+  `).run(row.id, row.label ?? '', row.topic ?? '', row.firstUser ?? '');
+    return true;
+}
+/**
+ * Drop peer mirror rows (and their cached digests) whose last sync predates the
+ * cutoff — the size ceiling / staleness pruner for the fleet session mirror
+ * (PHNX-3792). Only ever touches mirror rows (`mirror_synced_at IS NOT NULL`),
+ * never a genuine local or host-dispatch row. Returns the number of rows pruned.
+ */
+export function pruneMirrorSessions(cutoffMs) {
+    const db = getDB();
+    const stale = db.prepare(`SELECT id FROM sessions WHERE mirror_synced_at IS NOT NULL AND mirror_synced_at < ?`).all(cutoffMs);
+    if (stale.length === 0)
+        return 0;
+    const delRow = db.prepare(`DELETE FROM sessions WHERE id = ?`);
+    const delText = db.prepare(`DELETE FROM session_text WHERE session_id = ?`);
+    const delPreview = db.prepare(`DELETE FROM session_preview_cache WHERE session_id = ?`);
+    const txn = db.transaction(() => {
+        for (const { id } of stale) {
+            delRow.run(id);
+            delText.run(id);
+            delPreview.run(id);
+        }
+    });
+    txn();
+    return stale.length;
+}
 /** Plugin provenance already indexed for resources used by one session. */
 export function getSessionPlugins(id) {
     const rows = getDB().prepare(`

package/dist/lib/session/live-metadata.d.ts

@@ -13,3 +13,27 @@ export declare function activeSessionToSessionMeta(active: ActiveSession, self:
  * (no id, non-agent kind) are dropped. Order follows the input.
  */
 export declare function liveSessionMetas(active: ActiveSession[], self: string, nowMs: number): SessionMeta[];
+/**
+ * Which box the AGENT of each live session executes on, keyed by lowercased id,
+ * as recovered from the fleet-active snapshot (`agents sessions --active`'s
+ * cross-machine merge). A dispatcher that launched a session running on a peer
+ * has a live shim row locally whose `machine` self-defaulted to itself — the
+ * launch process IS here, the agent is not (PHNX-3890). The fleet snapshot
+ * already reconciled that against the peer's own self-report, so it is the one
+ * place that knows the true execution host without a synced index row (which is
+ * why `foldExecutionMachine` can't recover it: there is no local index row to
+ * join). Only rows the fleet attributes to a real machine are included.
+ */
+export declare function fleetExecutionMachineById(fleet: ActiveSession[]): Map<string, string>;
+/**
+ * Correct a live `SessionMeta` candidate's machine to its true EXECUTION host
+ * using the fleet-active attribution (PHNX-3890). Only a **self-attributed,
+ * transcript-less** row is a candidate for correction — the launcher-shim shape
+ * a dispatcher holds for a session whose agent runs on a peer, which is
+ * indistinguishable from a genuinely-local just-started session by its local
+ * fields alone. A row already attributed to another box, or one carrying a
+ * transcript path, is left untouched. A corrected row is stamped `_remote` so
+ * the read-vs-resume router (`transcriptOnPeerOf`) sends the preview to the
+ * owning peer instead of dead-ending on the local "not indexed here" stub.
+ */
+export declare function reconcileLiveMetaMachine(metas: SessionMeta[], fleetExecutionMachine: Map<string, string>, self: string): SessionMeta[];

package/dist/lib/session/live-metadata.js

@@ -76,3 +76,58 @@ export function liveSessionMetas(active, self, nowMs) {
     }
     return out;
 }
+/**
+ * Which box the AGENT of each live session executes on, keyed by lowercased id,
+ * as recovered from the fleet-active snapshot (`agents sessions --active`'s
+ * cross-machine merge). A dispatcher that launched a session running on a peer
+ * has a live shim row locally whose `machine` self-defaulted to itself — the
+ * launch process IS here, the agent is not (PHNX-3890). The fleet snapshot
+ * already reconciled that against the peer's own self-report, so it is the one
+ * place that knows the true execution host without a synced index row (which is
+ * why `foldExecutionMachine` can't recover it: there is no local index row to
+ * join). Only rows the fleet attributes to a real machine are included.
+ */
+export function fleetExecutionMachineById(fleet) {
+    const byId = new Map();
+    for (const s of fleet) {
+        // The AGENT machine is `machine` (where the transcript/harness lives), NOT
+        // `offloadedFrom` (where the launcher shim runs) — reading follows the
+        // transcript owner, so a would-be reader must reach `machine`.
+        if (!s.sessionId || !s.machine)
+            continue;
+        byId.set(s.sessionId.toLowerCase(), s.machine);
+    }
+    return byId;
+}
+/**
+ * Correct a live `SessionMeta` candidate's machine to its true EXECUTION host
+ * using the fleet-active attribution (PHNX-3890). Only a **self-attributed,
+ * transcript-less** row is a candidate for correction — the launcher-shim shape
+ * a dispatcher holds for a session whose agent runs on a peer, which is
+ * indistinguishable from a genuinely-local just-started session by its local
+ * fields alone. A row already attributed to another box, or one carrying a
+ * transcript path, is left untouched. A corrected row is stamped `_remote` so
+ * the read-vs-resume router (`transcriptOnPeerOf`) sends the preview to the
+ * owning peer instead of dead-ending on the local "not indexed here" stub.
+ */
+export function reconcileLiveMetaMachine(metas, fleetExecutionMachine, self) {
+    return metas.map(meta => {
+        // Already attributed elsewhere, or locally readable — not a self-default.
+        if (meta.machine && meta.machine !== self)
+            return meta;
+        if (meta.filePath)
+            return meta;
+        const exec = fleetExecutionMachine.get(meta.id.toLowerCase());
+        // Only a PEER attribution is positive information. A snapshot entry that
+        // names THIS box cannot be trusted as confirmation, because the snapshot is
+        // a merge that INCLUDES this box's own rows — so for exactly the session
+        // shape being corrected here (no index row to fold from), a `self` entry may
+        // be nothing but an echo of the self-default above, recorded while the
+        // owning peer had not reported yet or was unreachable during that gather.
+        // Treating it as proof would skip the fan-out and dead-end on the local stub
+        // for a session genuinely running elsewhere — the PHNX-3890 bug itself.
+        if (!exec || exec === self)
+            return meta;
+        return { ...meta, machine: exec, _remote: true };
+    });
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Fleet distribution of lightweight per-session preview/metadata (PHNX-3792).
+ *
+ * On the interactive/personal device, a session that originated on another host
+ * used to render as a bare `[host/<peer>]` row with no topic, and its preview
+ * pane fetched the peer's digest LIVE over SSH per row — slow, and blank when
+ * the peer is asleep. This module mirrors each box's own session digests into
+ * its conflict-free `~/.agents/devices/<device>/daemon-state.json`, which the
+ * daemon's existing bounded Git transport (`fleet-shared-repo-sync.ts`) already
+ * delivers fleet-wide with no operator step. The consuming device folds peer
+ * digests into its local `sessions` index as mirror rows, so the picker/list/
+ * focus read a LOCAL row instead of dialing the peer. No transcript is shipped —
+ * only topic/label, a first-user-message snippet, last-activity, agent+version,
+ * cwd, ticket, and PR — and the mirror is bounded and pruned by age.
+ *
+ * Direction is deliberately the inverse of usage-sync: EVERY box publishes its
+ * own local sessions (workers are exactly where the remote sessions the personal
+ * box lacks previews for are created), and every box EXCEPT a marked worker folds
+ * peers' digests in (the picker is an interactive surface). A worker skips the
+ * consume so its DB is not written with rows it never renders.
+ */
+import { type ConfiguredDeviceRole } from '../device-config.js';
+/** Cap on sessions published per device — the payload stays what a picker shows. */
+export declare const SESSION_MIRROR_MAX_ROWS = 200;
+/** First-user-message snippet ceiling; the full turn stays on the owning box. */
+export declare const SESSION_MIRROR_SNIPPET_MAX = 280;
+/** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
+export declare const SESSION_MIRROR_MAX_AGE_MS: number;
+export interface PublishSessionMirrorOptions {
+    userAgentsDir?: string;
+    device?: string;
+    limit?: number;
+}
+export interface PublishSessionMirrorResult {
+    published: boolean;
+    changed: boolean;
+    count: number;
+    skipped: string | null;
+    error: string | null;
+    path: string | null;
+}
+/** Publish this device's most-recent local sessions into its owned shared-state file. */
+export declare function publishSessionMirrorToSharedStore(options?: PublishSessionMirrorOptions): Promise<PublishSessionMirrorResult>;
+export interface ConsumeSessionMirrorOptions {
+    userAgentsDir?: string;
+    device?: string;
+    role?: ConfiguredDeviceRole;
+    now?: number;
+    maxAgeMs?: number;
+}
+export interface ConsumeSessionMirrorResult {
+    sources: string[];
+    merged: number;
+    pruned: number;
+    skipped: string | null;
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+/**
+ * Fold peers' published session digests into this box's local `sessions` index
+ * as mirror rows, then prune stale ones. Reads only the local user-repo checkout
+ * (the daemon's Git transport already delivered peers' files) — no network. A
+ * marked worker skips: the mirror feeds an interactive picker it never renders.
+ */
+export declare function consumeSessionMirrorFromSharedStore(options?: ConsumeSessionMirrorOptions): ConsumeSessionMirrorResult;

package/dist/lib/session/mirror.js

@@ -0,0 +1,158 @@
+/**
+ * Fleet distribution of lightweight per-session preview/metadata (PHNX-3792).
+ *
+ * On the interactive/personal device, a session that originated on another host
+ * used to render as a bare `[host/<peer>]` row with no topic, and its preview
+ * pane fetched the peer's digest LIVE over SSH per row — slow, and blank when
+ * the peer is asleep. This module mirrors each box's own session digests into
+ * its conflict-free `~/.agents/devices/<device>/daemon-state.json`, which the
+ * daemon's existing bounded Git transport (`fleet-shared-repo-sync.ts`) already
+ * delivers fleet-wide with no operator step. The consuming device folds peer
+ * digests into its local `sessions` index as mirror rows, so the picker/list/
+ * focus read a LOCAL row instead of dialing the peer. No transcript is shipped —
+ * only topic/label, a first-user-message snippet, last-activity, agent+version,
+ * cwd, ticket, and PR — and the mirror is bounded and pruned by age.
+ *
+ * Direction is deliberately the inverse of usage-sync: EVERY box publishes its
+ * own local sessions (workers are exactly where the remote sessions the personal
+ * box lacks previews for are created), and every box EXCEPT a marked worker folds
+ * peers' digests in (the picker is an interactive surface). A worker skips the
+ * consume so its DB is not written with rows it never renders.
+ */
+import { selfConfiguredDeviceRole } from '../device-config.js';
+import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
+import { getUserAgentsDir } from '../state.js';
+import { machineId, normalizeHost } from './sync/config.js';
+import { pruneMirrorSessions, queryLocalOriginSessionsForMirror, upsertMirrorSession, } from './db.js';
+/** Cap on sessions published per device — the payload stays what a picker shows. */
+export const SESSION_MIRROR_MAX_ROWS = 200;
+/** First-user-message snippet ceiling; the full turn stays on the owning box. */
+export const SESSION_MIRROR_SNIPPET_MAX = 280;
+/** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
+export const SESSION_MIRROR_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
+function snippet(value, max = SESSION_MIRROR_SNIPPET_MAX) {
+    if (!value)
+        return undefined;
+    const trimmed = value.replace(/\s+/g, ' ').trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+/** Publish this device's most-recent local sessions into its owned shared-state file. */
+export async function publishSessionMirrorToSharedStore(options = {}) {
+    const result = {
+        published: false, changed: false, count: 0, skipped: null, error: null, path: null,
+    };
+    const device = options.device ?? machineId();
+    const self = normalizeHost(device);
+    const limit = options.limit ?? SESSION_MIRROR_MAX_ROWS;
+    const capturedAt = Date.now();
+    const sources = queryLocalOriginSessionsForMirror(self, limit);
+    const rows = sources.map((s) => ({
+        id: s.id,
+        shortId: s.shortId,
+        agent: s.agent,
+        ...(s.version ? { version: s.version } : {}),
+        machine: s.machine?.trim() || self,
+        ...(s.cwd ? { cwd: s.cwd } : {}),
+        ...(snippet(s.topic, 200) ? { topic: snippet(s.topic, 200) } : {}),
+        ...(s.label ? { label: s.label } : {}),
+        ...(snippet(s.firstUserMessage) ? { firstUser: snippet(s.firstUserMessage) } : {}),
+        ...(s.lastActivity ? { lastActivity: s.lastActivity } : {}),
+        timestamp: s.timestamp,
+        ...(s.ticketId ? { ticketId: s.ticketId } : {}),
+        ...(s.prUrl ? { prUrl: s.prUrl } : {}),
+        capturedAt,
+    }));
+    try {
+        const write = await updateFleetSharedDeviceStateAsync(device, { sessions: { rows } }, options.userAgentsDir ?? getUserAgentsDir());
+        result.published = true;
+        result.changed = write.changed;
+        result.count = rows.length;
+        result.path = write.path;
+    }
+    catch (err) {
+        result.error = err.message;
+    }
+    return result;
+}
+function isString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Validate one untrusted peer-supplied row into a DB upsert (or null when it is
+ * missing a load-bearing field). Terminal-escape scrubbing is NOT done here —
+ * the render path (`sanitizeMeta` in sessions-picker) scrubs every meta string
+ * before it reaches a TTY, exactly as it does for live fan-out rows — this only
+ * enforces shape and bounds so a malformed/hostile peer can't poison the index.
+ */
+function toUpsert(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const r = raw;
+    if (!isString(r.id) || !isString(r.agent) || !isString(r.machine))
+        return null;
+    const timestamp = isString(r.timestamp) ? r.timestamp : (isString(r.lastActivity) ? r.lastActivity : null);
+    if (!timestamp)
+        return null;
+    const shortId = isString(r.shortId) ? r.shortId : r.id.slice(0, 8);
+    const cap = (v, max) => isString(v) ? (v.length > max ? v.slice(0, max) : v) : undefined;
+    return {
+        id: r.id,
+        shortId,
+        agent: r.agent,
+        version: cap(r.version, 64),
+        machine: r.machine,
+        cwd: cap(r.cwd, 1024),
+        topic: cap(r.topic, 400),
+        firstUser: cap(r.firstUser, SESSION_MIRROR_SNIPPET_MAX),
+        label: cap(r.label, 400),
+        lastActivity: isString(r.lastActivity) ? r.lastActivity : undefined,
+        timestamp,
+        ticketId: cap(r.ticketId, 64),
+        prUrl: cap(r.prUrl, 512),
+    };
+}
+/**
+ * Fold peers' published session digests into this box's local `sessions` index
+ * as mirror rows, then prune stale ones. Reads only the local user-repo checkout
+ * (the daemon's Git transport already delivered peers' files) — no network. A
+ * marked worker skips: the mirror feeds an interactive picker it never renders.
+ */
+export function consumeSessionMirrorFromSharedStore(options = {}) {
+    const result = { sources: [], merged: 0, pruned: 0, skipped: null, errors: [] };
+    const role = options.role ?? selfConfiguredDeviceRole();
+    const now = options.now ?? Date.now();
+    if (role === 'worker') {
+        // A worker never renders the picker, so it does not consume peers' digests.
+        // But if this box was previously a non-worker it may still hold mirror rows,
+        // which it will never refresh or render — prune them all now (cutoff = now
+        // drops every row synced before this tick) rather than leave a demoted box's
+        // index permanently bloated with stale peer rows (PHNX-3792).
+        result.pruned = pruneMirrorSessions(now);
+        result.skipped = 'this device is a worker; the session mirror feeds the interactive picker';
+        return result;
+    }
+    const read = readFleetSharedDeviceStates(options.userAgentsDir ?? getUserAgentsDir());
+    result.errors.push(...read.errors);
+    const self = normalizeHost(options.device ?? machineId());
+    for (const state of read.states) {
+        if (normalizeHost(state.device) === self || !state.sessions?.rows)
+            continue;
+        let mergedForDevice = 0;
+        for (const raw of state.sessions.rows) {
+            const row = toUpsert(raw);
+            if (!row)
+                continue;
+            if (upsertMirrorSession(row, state.device, now))
+                mergedForDevice++;
+        }
+        if (mergedForDevice > 0) {
+            result.sources.push(state.device);
+            result.merged += mergedForDevice;
+        }
+    }
+    result.sources.sort();
+    result.pruned = pruneMirrorSessions(now - (options.maxAgeMs ?? SESSION_MIRROR_MAX_AGE_MS));
+    return result;
+}

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

@@ -364,6 +364,15 @@ export interface SessionMeta {
      * split as `AGENTS_ACTOR` / `AGENTS_ACTOR_KIND` on the exec env. RUSH-2018.
      */
     initiatedBy?: 'human' | 'agent';
+    /**
+     * Phoenix id of the actor who initiated this session (`resolveActor().phoenixId`)
+     * — the tailnet human's stable Phoenix identity, resolved from the `actors:` map
+     * at spawn. Pairs with {@link actor}, persisted write-once at session creation
+     * and joined from the actor sidecar at scan time (kept out of the DB upsert's
+     * ON CONFLICT set), so `agents sessions --json` can surface the Phoenix id.
+     * Undefined for rows created before Phoenix-id stamping. PHNX-3798.
+     */
+    phoenixId?: string;
     /**
      * True only for rows pulled from another machine over the live cross-machine
      * fan-out (`remote-list.ts`) — their transcript is on that peer's disk, so
@@ -373,6 +382,15 @@ export interface SessionMeta {
      * `parseRemoteList`; transient (never persisted, stripped from --json).
      */
     _remote?: boolean;
+    /**
+     * Epoch ms this row was last written from a PEER's fleet-synced session mirror
+     * (PHNX-3792); absent for a genuine local or host-dispatch row. When set, the
+     * picker renders the peer session's topic/preview INLINE from this mirror
+     * (no per-row SSH) and stamps a "synced <ago>" / stale marker. `mirrorSource`
+     * names the publishing device. Backed by the `mirror_synced_at` column.
+     */
+    mirrorSyncedAt?: number;
+    mirrorSource?: string;
     /**
      * True when the transcript file is gone from disk but the session's user turns
      * still live in the local DB (session_text), so the row is served and rendered