@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/lib/session/active.js

@@ -136,6 +136,14 @@ export function filterCachedUnattributed(sessions, attributed, alive) {
         return alive(s.pid, s.startedAtMs);
     });
 }
+/**
+ * Fold index-only enrichment onto live rows, then RE-DERIVE the recap for every
+ * row it touched. The re-derive is load-bearing: `foldRecap` runs inside
+ * {@link getActiveSessions}, before any caller reaches the index, so a `label`
+ * or `generatedTitle` that only the index knows would otherwise never reach the
+ * shown `title` (PHNX-3797). Doing it here rather than at each of the three
+ * backfill call sites is what keeps them from drifting apart.
+ */
 export function backfillActiveRowsFromMeta(sessions, metaById) {
     for (const s of sessions) {
         if (!s.sessionId)
@@ -153,6 +161,8 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             s.firstUserMessage = m.firstUserMessage;
         if (!s.lastUserMessage && m.lastUserMessage)
             s.lastUserMessage = m.lastUserMessage;
+        if (!s.generatedTitle && m.generatedTitle)
+            s.generatedTitle = m.generatedTitle;
         if (!s.ticket && m.ticketId)
             s.ticket = { id: m.ticketId, url: linearIssueUrl(m.ticketId) };
         if (!s.pr && m.prUrl)
@@ -181,6 +191,7 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             if (!Number.isNaN(ts))
                 s.lastActivityMs = ts;
         }
+        applyRecap(s);
     }
 }
 function loadBackfillMetaFor(sessions) {
@@ -2119,7 +2130,8 @@ function recapLine(s, max = 120) {
     return t.length > max ? t.slice(0, max - 1).trimEnd() + '…' : t;
 }
 /**
- * Labels win, then the last assistant line, then the prompt.
+ * The headline ladder (PHNX-3797): an explicit `/rename` label, then the
+ * daemon-generated title, then the classified user prompt.
  *
  * The prompt rung classifies the RAW latest genuine user turn, not the
  * already-collapsed `topic` (PHNX-3939). Classifying `topic` was how a `/model`
@@ -2128,6 +2140,13 @@ function recapLine(s, max = 120) {
  * that scaffolding as the user's words. It also never saw the row's attachments,
  * so an image-only turn could not be recognized. A row that has already been
  * merged with a daemon-folded {@link ActiveSession.request} uses it directly.
+ *
+ * The agent's last transcript line is deliberately NOT a rung. It is still
+ * returned as `lastAgentLine` — and still shown, in the separate live
+ * preview/activity slot — but a rolling monologue is not what the session IS,
+ * and using it as the headline is the defect this ladder fixes. A session the
+ * titler has not reached yet falls back to the classified user prompt, never
+ * to the agent's last line.
  */
 export function deriveSessionRecap(row) {
     const lastAgentLine = recapLine(row.tail?.length ? row.tail[row.tail.length - 1] : undefined);
@@ -2144,6 +2163,7 @@ export function deriveSessionRecap(row) {
     const userPromptClean = tidied?.headline ?? fallback?.clean;
     const userPromptKind = tidied?.kind ?? fallback?.kind;
     const label = recapLine(row.label);
+    const generated = recapLine(row.generatedTitle);
     const prompt = recapLine(userPromptClean || row.topic);
     let title;
     let recapSource;
@@ -2151,9 +2171,9 @@ export function deriveSessionRecap(row) {
         title = label;
         recapSource = 'label';
     }
-    else if (lastAgentLine) {
-        title = lastAgentLine;
-        recapSource = 'last';
+    else if (generated) {
+        title = generated;
+        recapSource = 'generated';
     }
     else if (prompt) {
         title = prompt;
@@ -2168,18 +2188,63 @@ export function deriveSessionRecap(row) {
         ...(tidied ? { request: tidied } : {}),
     };
 }
+/**
+ * The row's SECONDARY line (PHNX-3797 owner feedback): the most important recent
+ * agent message, ranked so the operator sees a block before generic chatter —
+ * a pending question, then a needs-you wait (plan review / permission /
+ * input-required), then the current activity (the agent's latest line). Returns
+ * `undefined` only when there is nothing recent to show at all.
+ *
+ * Pure over the fields it reads so the ranking is unit-tested directly; folded
+ * onto every row by {@link applyRecap} beside the {@link deriveSessionRecap} title.
+ */
+export function deriveImportantMessage(row) {
+    // The agent's latest words — the fallback text for every kind. `lastAgentLine`
+    // is already trimmed/capped; `preview` (a live tool/turn line) is not.
+    const recent = recapLine(row.preview) ?? row.lastAgentLine;
+    // A pending question is the single most important thing an agent can be saying.
+    if (row.awaitingReason === 'question' || row.question) {
+        const text = recapLine(row.question?.text) ?? recent;
+        if (text)
+            return { text, kind: 'question' };
+    }
+    // Blocked on the operator: a plan review, a permission decision, or a bare
+    // input-required wait. The "needs you" case the Fleet has to make loud.
+    const needsYou = row.awaitingReason === 'plan_review'
+        || row.awaitingReason === 'permission'
+        || row.status === 'input_required'
+        || row.activity === 'waiting_input';
+    if (needsYou) {
+        const fallback = row.awaitingReason === 'plan_review'
+            ? 'Waiting on plan review'
+            : row.awaitingReason === 'permission'
+                ? 'Waiting on a permission decision'
+                : 'Waiting for you';
+        return { text: recent ?? fallback, kind: 'needs_you' };
+    }
+    // Nothing blocking — just what the agent is doing now.
+    if (recent)
+        return { text: recent, kind: 'activity' };
+    return undefined;
+}
+/** Write one row's recap fields from its current label/generatedTitle/topic/tail. */
+function applyRecap(s) {
+    const recap = deriveSessionRecap(s);
+    s.title = recap.title;
+    s.recapSource = recap.recapSource;
+    s.userPromptClean = recap.userPromptClean;
+    s.userPromptKind = recap.userPromptKind;
+    s.lastAgentLine = recap.lastAgentLine;
+    if (recap.request)
+        s.request = recap.request;
+    // The secondary line rides the same fold as the headline (PHNX-3797), so every
+    // consumer that reads `title` off a row reads `importantMessage` beside it.
+    s.importantMessage = deriveImportantMessage(s);
+}
 /** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
 export function foldRecap(rows) {
-    for (const s of rows) {
-        const recap = deriveSessionRecap(s);
-        s.title = recap.title;
-        s.recapSource = recap.recapSource;
-        s.userPromptClean = recap.userPromptClean;
-        s.userPromptKind = recap.userPromptKind;
-        s.lastAgentLine = recap.lastAgentLine;
-        if (recap.request)
-            s.request = recap.request;
-    }
+    for (const s of rows)
+        applyRecap(s);
 }
 /**
  * Project a {@link SessionPhase} from the finalized {@link ActiveStatus} (PHNX-2484).
@@ -2233,6 +2298,7 @@ export function annotateOrchestratorLabels(sessions) {
         if (!s.orchestratorSessionId)
             continue;
         const orch = byId.get(s.orchestratorSessionId);
+        // ladder-exempt: the team orchestrator's LABEL, resolved before any index backfill (no generatedTitle exists yet); not a headline render.
         if (orch)
             s.orchestratorLabel = orch.label || orch.topic || undefined;
     }

package/dist/lib/session/cloud.js

@@ -53,6 +53,8 @@ function agentToFormat(agent) {
         return 'rush';
     if (agent === 'droid')
         return 'droid';
+    if (agent === 'opencode')
+        return 'opencode';
     return null;
 }
 export function assertContained(candidate, rootDir) {
@@ -128,7 +130,7 @@ export async function ensureCloudSessionCached(executionId, destPath) {
         throw new Error(`session.jsonl fetch ${res.status}: ${body.slice(0, 200)}`);
     }
     const format = (res.headers.get('X-Session-Format') || '').toLowerCase();
-    if (!['claude', 'codex', 'rush'].includes(format)) {
+    if (!['claude', 'codex', 'rush', 'opencode'].includes(format)) {
         throw new Error(`Unknown X-Session-Format on cloud response: "${format}"`);
     }
     const finalPath = callerPath ?? cachePathForExecution(id, format);

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

@@ -14,7 +14,7 @@ import { type TimelineState } from './timeline.js';
 /** 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 declare const SCHEMA_VERSION = 49;
+export declare const SCHEMA_VERSION = 50;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -530,6 +530,8 @@ export interface LocalMirrorSource {
     topic: string | null;
     firstUserMessage: string | null;
     label: string | null;
+    /** The daemon-generated headline (PHNX-3797), so a peer row shows the same title. */
+    generatedTitle: string | null;
     lastActivity: string | null;
     timestamp: string;
     ticketId: string | null;
@@ -558,6 +560,8 @@ export interface MirrorSessionUpsert {
     topic?: string | null;
     firstUser?: string | null;
     label?: string | null;
+    /** The publisher's daemon-generated headline (PHNX-3797); undefined when it has none yet. */
+    generatedTitle?: string | null;
     lastActivity?: string | null;
     timestamp: string;
     ticketId?: string | null;
@@ -579,6 +583,45 @@ export interface MirrorSessionUpsert {
  * row collapses with the live fan-out row under the same `machine:id` key.
  */
 export declare function upsertMirrorSession(row: MirrorSessionUpsert, source: string, syncedAt: number): boolean;
+/** One indexed session the daemon titler may generate a headline for (PHNX-3797). */
+export interface SessionTitleCandidateRow {
+    id: string;
+    agent: string;
+    cwd: string | null;
+    project: string | null;
+    topic: string | null;
+    firstUserMessage: string | null;
+    label: string | null;
+    ticketId: string | null;
+    gitBranch: string | null;
+    generatedTitle: string | null;
+    generatedTitleKey: string | null;
+}
+/**
+ * The most-recently-active LOCAL sessions the titler may consider (PHNX-3797).
+ *
+ * Deliberately not "every untitled row": the caller decides which of these still
+ * needs work by comparing each row's stored `generatedTitleKey` against the key
+ * of its current user text, so a first-user-message change re-titles without a
+ * second stored copy of that text. Rows excluded here can never be titled:
+ *  - a peer MIRROR row — its owning box generates its title and publishes it;
+ *  - a row with no user text at all — there is nothing user-anchored to title;
+ *  - a row that already carries a `/rename`-style `label`, which outranks a
+ *    generated title in the ladder, so generating one would buy nothing.
+ * `sinceMs` bounds the work to sessions recent enough to still be shown.
+ */
+export declare function querySessionTitleCandidates(limit: number, opts?: {
+    sinceMs?: number;
+    id?: string;
+}): SessionTitleCandidateRow[];
+/**
+ * Persist one generated title against the source key it was derived from
+ * (PHNX-3797). `sourceKey` is what makes generation once-per-session: the next
+ * sweep sees a stored key equal to the row's current user text and skips it,
+ * and regenerates only when that text changed. Never touches a mirror row —
+ * the publishing box owns its own sessions' titles.
+ */
+export declare function setSessionGeneratedTitle(id: string, title: string, sourceKey: string, now?: number): boolean;
 /**
  * Drop peer mirror rows (and their cached digests) whose last sync predates the
  * cutoff — the size ceiling / staleness pruner for the fleet session mirror

package/dist/lib/session/db.js

@@ -29,7 +29,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 = 49;
+export const SCHEMA_VERSION = 50;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -154,7 +154,18 @@ CREATE TABLE IF NOT EXISTS sessions (
   -- 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
+  mirror_source TEXT,
+  -- Daemon-generated session TITLE (PHNX-3797): a short technical label for what
+  -- the session worked on, produced once by the session-title daemon service and
+  -- read by every headline surface. Deliberately NOT transcript-derived, so the
+  -- scanner's upsert omits these columns entirely (an omitted column keeps its
+  -- prior value) and only the titler writes them. generated_title_key is the
+  -- hash of the user text the title was derived from, so the titler can tell
+  -- "already titled" from "the first user message changed"; generated_title_at
+  -- is when it was produced.
+  generated_title TEXT,
+  generated_title_key TEXT,
+  generated_title_at INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -1310,10 +1321,15 @@ function migrateSchema(db, fromVersion) {
         // The idx_sessions_mirror_synced index is created unconditionally after this
         // block (fresh DBs skip migrations), alongside idx_sessions_last_activity.
     }
-    if (fromVersion < 49) {
-        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map(c => c.name));
-        if (!cols.has('account_id'))
-            db.exec(`ALTER TABLE sessions ADD COLUMN account_id TEXT`);
+    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`);
     }
     if (fromVersion < 48) {
         // v47 -> v48: retain the LATEST genuine user turn beside the first
@@ -1334,15 +1350,26 @@ function migrateSchema(db, fromVersion) {
         if (!cols.has('last_user_message'))
             db.exec(`ALTER TABLE sessions ADD COLUMN last_user_message TEXT`);
     }
-    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).
+    if (fromVersion < 49) {
+        // v48 -> v49: account-first storage (PHNX-3940).
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map(c => c.name));
+        if (!cols.has('account_id'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN account_id TEXT`);
+    }
+    if (fromVersion < 50) {
+        // v49 -> v50: the daemon-generated session title (PHNX-3797). Additive
+        // columns, no ledger wipe: nothing in a transcript produces them — the
+        // session-title service writes them and the scanner's upsert never names
+        // them — so re-parsing every indexed transcript would be pure churn. Rows
+        // stay NULL until the titler reaches them, which the recap ladder handles by
+        // falling back to the user's own first message.
         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`);
+        if (!cols.has('generated_title'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN generated_title TEXT`);
+        if (!cols.has('generated_title_key'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN generated_title_key TEXT`);
+        if (!cols.has('generated_title_at'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN generated_title_at INTEGER`);
     }
 }
 /**
@@ -2753,6 +2780,7 @@ function rowToMeta(row) {
         topic: row.topic ?? undefined,
         firstUserMessage: row.first_user_message ?? undefined,
         lastUserMessage: row.last_user_message ?? undefined,
+        generatedTitle: row.generated_title ?? undefined,
         label: row.label ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
         prUrl: row.pr_url ?? undefined,
@@ -3552,7 +3580,7 @@ export function writeSessionTimeline(entry) {
 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
+           label, generated_title, last_activity, timestamp, ticket_id, pr_url
     FROM sessions
     WHERE mirror_synced_at IS NULL
       AND file_path IS NOT NULL AND file_path <> ''
@@ -3565,6 +3593,7 @@ export function queryLocalOriginSessionsForMirror(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,
+        generatedTitle: r.generated_title,
         lastActivity: r.last_activity, timestamp: r.timestamp, ticketId: r.ticket_id, prUrl: r.pr_url,
         // Ride the daemon-computed summary alongside the digest so a peer renders it
         // without a transcript (PHNX-3939); only a summarized session carries one.
@@ -3589,11 +3618,11 @@ export function upsertMirrorSession(row, source, syncedAt) {
     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,
+      topic, first_user_message, label, generated_title, 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,
+      @topic, @first_user, @label, @generated_title, NULL, '', @scanned_at,
       0, @ticket_id, @pr_url, @machine, @synced_at, @source
     )
     ON CONFLICT(id) DO UPDATE SET
@@ -3611,6 +3640,12 @@ export function upsertMirrorSession(row, source, syncedAt) {
       -- symptom this feature fixes. A null peer label clears it so the list falls
       -- back to the synced topic.
       label = excluded.label,
+      -- Same rule for the generated headline (PHNX-3797): the publishing box owns
+      -- its sessions' titles, and this box's titler never generates for a mirror
+      -- row, so the peer's value wins outright and a peer that has not titled the
+      -- session yet clears it (the ladder then falls back to the synced first
+      -- user message, never to an agent line).
+      generated_title = excluded.generated_title,
       ticket_id = COALESCE(excluded.ticket_id, sessions.ticket_id),
       pr_url = COALESCE(excluded.pr_url, sessions.pr_url),
       machine = excluded.machine,
@@ -3628,6 +3663,7 @@ export function upsertMirrorSession(row, source, syncedAt) {
         topic: row.topic ?? null,
         first_user: row.firstUser ?? null,
         label: row.label ?? null,
+        generated_title: row.generatedTitle ?? null,
         ticket_id: row.ticketId ?? null,
         pr_url: row.prUrl ?? null,
         machine: row.machine,
@@ -3665,6 +3701,75 @@ export function upsertMirrorSession(row, source, syncedAt) {
     }
     return true;
 }
+/**
+ * The most-recently-active LOCAL sessions the titler may consider (PHNX-3797).
+ *
+ * Deliberately not "every untitled row": the caller decides which of these still
+ * needs work by comparing each row's stored `generatedTitleKey` against the key
+ * of its current user text, so a first-user-message change re-titles without a
+ * second stored copy of that text. Rows excluded here can never be titled:
+ *  - a peer MIRROR row — its owning box generates its title and publishes it;
+ *  - a row with no user text at all — there is nothing user-anchored to title;
+ *  - a row that already carries a `/rename`-style `label`, which outranks a
+ *    generated title in the ladder, so generating one would buy nothing.
+ * `sinceMs` bounds the work to sessions recent enough to still be shown.
+ */
+export function querySessionTitleCandidates(limit, opts = {}) {
+    const clauses = [
+        `mirror_synced_at IS NULL`,
+        `(first_user_message IS NOT NULL OR topic IS NOT NULL)`,
+    ];
+    const params = [];
+    if (opts.id) {
+        clauses.push(`(id = ? OR short_id = ?)`);
+        params.push(opts.id, opts.id);
+    }
+    else {
+        // An explicitly requested session is titled even when it carries a label or
+        // is older than the window; the periodic sweep honours both bounds.
+        clauses.push(`(label IS NULL OR trim(label) = '')`);
+        if (opts.sinceMs != null) {
+            clauses.push(`COALESCE(last_activity, timestamp) >= ?`);
+            params.push(new Date(opts.sinceMs).toISOString());
+        }
+    }
+    const rows = getDB().prepare(`
+    SELECT id, agent, cwd, project, topic, first_user_message, label, ticket_id,
+           git_branch, generated_title, generated_title_key
+    FROM sessions
+    WHERE ${clauses.join(' AND ')}
+    ORDER BY COALESCE(last_activity, timestamp) DESC
+    LIMIT ?
+  `).all(...params, limit);
+    return rows.map((r) => ({
+        id: r.id,
+        agent: r.agent,
+        cwd: r.cwd,
+        project: r.project,
+        topic: r.topic,
+        firstUserMessage: r.first_user_message,
+        label: r.label,
+        ticketId: r.ticket_id,
+        gitBranch: r.git_branch,
+        generatedTitle: r.generated_title,
+        generatedTitleKey: r.generated_title_key,
+    }));
+}
+/**
+ * Persist one generated title against the source key it was derived from
+ * (PHNX-3797). `sourceKey` is what makes generation once-per-session: the next
+ * sweep sees a stored key equal to the row's current user text and skips it,
+ * and regenerates only when that text changed. Never touches a mirror row —
+ * the publishing box owns its own sessions' titles.
+ */
+export function setSessionGeneratedTitle(id, title, sourceKey, now = Date.now()) {
+    const result = getDB().prepare(`
+    UPDATE sessions
+    SET generated_title = ?, generated_title_key = ?, generated_title_at = ?
+    WHERE id = ? AND mirror_synced_at IS NULL
+  `).run(title, sourceKey, now, id);
+    return result.changes > 0;
+}
 /**
  * Drop peer mirror rows (and their cached digests) whose last sync predates the
  * cutoff — the size ceiling / staleness pruner for the fleet session mirror

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

@@ -40,8 +40,16 @@ export interface ForkRecapInput {
     /** Changed-files tally so far. */
     changes?: ForkRecapChanges;
 }
-/** Resolve the human display label the caller passes in from a raw SessionMeta. */
-export declare function forkLabelFor(session: Pick<SessionMeta, 'label' | 'topic' | 'shortId'>): string;
+/**
+ * Resolve the human display label the caller passes in from a raw SessionMeta.
+ *
+ * Pass the session WHOLE. A caller that re-lists fields into an object literal
+ * can legally omit the optional `generatedTitle` — the type system does not
+ * flag a missing optional property — and the headline then silently degrades to
+ * `topic`. That is what the fork call site did (PHNX-3797); the rebuilt-literal
+ * shape is caught by `title.ladder-completeness.test.ts`.
+ */
+export declare function forkLabelFor(session: Pick<SessionMeta, 'label' | 'generatedTitle' | 'topic' | 'shortId'>): string;
 /**
  * Build the recap-seed prompt handed to the forked sibling as its opening input.
  *

package/dist/lib/session/fork.js

@@ -1,3 +1,4 @@
+import { sessionHeadline } from './title.js';
 /** Longest last-assistant excerpt carried into the seed — enough to convey intent
  * without pasting a wall of text (decision: Recap, not Full digest). */
 const LAST_LINE_CAP = 400;
@@ -9,9 +10,17 @@ function trimLastLine(text) {
         return collapsed;
     return `${collapsed.slice(0, LAST_LINE_CAP).trimEnd()}…`;
 }
-/** Resolve the human display label the caller passes in from a raw SessionMeta. */
+/**
+ * Resolve the human display label the caller passes in from a raw SessionMeta.
+ *
+ * Pass the session WHOLE. A caller that re-lists fields into an object literal
+ * can legally omit the optional `generatedTitle` — the type system does not
+ * flag a missing optional property — and the headline then silently degrades to
+ * `topic`. That is what the fork call site did (PHNX-3797); the rebuilt-literal
+ * shape is caught by `title.ladder-completeness.test.ts`.
+ */
 export function forkLabelFor(session) {
-    return session.label || session.topic || session.shortId;
+    return sessionHeadline(session) || session.shortId;
 }
 /**
  * Build the recap-seed prompt handed to the forked sibling as its opening input.

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

@@ -48,6 +48,12 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         cwd: active.cwd,
         project: active.project ?? undefined,
         label: active.label,
+        // Carried even though this projection only runs for a session with NO indexed
+        // row (so the value is `undefined` today): a hand-built SessionMeta that
+        // omits the rung is exactly the shape that silently degrades the headline the
+        // moment its reachability changes (PHNX-3797). Neither guard can see it here
+        // — it calls no ladder, and its fields sit on separate lines.
+        generatedTitle: active.generatedTitle,
         topic: active.topic,
         firstUserMessage: active.firstUserMessage,
         version: active.version,

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

@@ -10,8 +10,9 @@
  * 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.
+ * only topic/label, the peer's daemon-generated title (PHNX-3797), 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

package/dist/lib/session/mirror.js

@@ -10,8 +10,9 @@
  * 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.
+ * only topic/label, the peer's daemon-generated title (PHNX-3797), 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
@@ -94,6 +95,7 @@ export async function publishSessionMirrorToSharedStore(options = {}) {
         ...(s.cwd ? { cwd: s.cwd } : {}),
         ...(snippet(s.topic, 200) ? { topic: snippet(s.topic, 200) } : {}),
         ...(s.label ? { label: s.label } : {}),
+        ...(snippet(s.generatedTitle, 200) ? { title: snippet(s.generatedTitle, 200) } : {}),
         ...(snippet(s.firstUserMessage) ? { firstUser: snippet(s.firstUserMessage) } : {}),
         ...(s.lastActivity ? { lastActivity: s.lastActivity } : {}),
         timestamp: s.timestamp,
@@ -171,6 +173,7 @@ function toUpsert(raw) {
         topic: cap(r.topic, 400),
         firstUser: cap(r.firstUser, SESSION_MIRROR_SNIPPET_MAX),
         label: cap(r.label, 400),
+        generatedTitle: cap(r.title, 200),
         lastActivity: isString(r.lastActivity) ? r.lastActivity : undefined,
         timestamp,
         ticketId: cap(r.ticketId, 64),

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

@@ -229,6 +229,7 @@ export declare function parseGrok(filePath: string): SessionEvent[];
  */
 export declare const OPENCODE_TRANSCRIPT_QUERY: string;
 export declare function parseOpenCode(filePath: string): SessionEvent[];
+export declare function parseOpencodeCloud(filePath: string): SessionEvent[];
 /** Parse a Rush JSONL session file into normalized events. */
 export declare function parseRush(filePath: string): SessionEvent[];
 /**