@phnx-labs/agents-cli 1.22.109 → 1.22.110

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/remote/watch.js

@@ -60,6 +60,16 @@ function epochMs(value) {
 export function previousSessionWatchRowKey(scope, sessionId) {
     return createHash('sha256').update(`${scope}\0previous\0${sessionId}`).digest('base64url').slice(0, 22);
 }
+/**
+ * The headline for a durable history row, on the same ladder a live row uses
+ * ({@link deriveSessionRecap}): an explicit `/rename` label, then the
+ * daemon-generated title (PHNX-3797), then the daemon-folded request headline
+ * (`request.headline` — the user's own sentence with attachment noise pulled
+ * out, PHNX-3939) when the transcript cache has one, else the raw `topic`.
+ */
+function previousRowTitle(session, foldedHeadline) {
+    return session.label || session.generatedTitle || foldedHeadline || session.topic || undefined;
+}
 /** 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) {
@@ -86,6 +96,7 @@ export function toPreviousSessionWatchRow(scope, session) {
     // transcript-keyed cache the live merge reads (PHNX-3939), so a closed session
     // still shows the request it was given and what the agent did — no re-parse.
     const folded = readSessionTimelineAny(session.id);
+    const title = previousRowTitle(session, folded?.request?.headline);
     return {
         context: 'recent',
         kind: session.agent,
@@ -93,14 +104,13 @@ export function toPreviousSessionWatchRow(scope, session) {
         sessionId: session.id,
         ...(session.cwd ? { cwd: session.cwd } : {}),
         ...(session.project ? { project: session.project } : {}),
-        // `request.headline` is the user's own sentence with the attachment noise
-        // pulled out, so it beats the raw `topic` for the row title — a `/model` echo
-        // or a skill body can no longer become a session's name (PHNX-3939).
-        ...(session.label
-            ? { label: session.label, title: session.label }
-            : folded?.request?.headline
-                ? { title: folded.request.headline }
-                : session.topic ? { title: session.topic } : {}),
+        // Same headline ladder as a live row (`deriveSessionRecap`, PHNX-3797):
+        // `/rename` label → the daemon-generated title → `request.headline` (the
+        // user's own sentence with attachment noise pulled out, PHNX-3939) →
+        // the raw `topic`. See {@link previousRowTitle}.
+        ...(session.label ? { label: session.label } : {}),
+        ...(session.generatedTitle ? { generatedTitle: session.generatedTitle } : {}),
+        ...(title ? { title } : {}),
         ...(session.topic ? { topic: session.topic } : {}),
         ...(session.firstUserMessage ? { firstUserMessage: session.firstUserMessage } : {}),
         ...(session.version ? { version: session.version } : {}),