@phnx-labs/agents-cli 1.22.109 → 1.22.110

package/dist/lib/daemon/session-title-service.js

@@ -0,0 +1,76 @@
+/**
+ * Session-title service (PHNX-3797) — the ONE generator of session headlines.
+ *
+ * Every session row's headline used to be the agent's latest transcript line.
+ * This service replaces it with a user-anchored NAME: it sweeps the local
+ * session index for recent sessions whose title is still the raw first user
+ * message, asks a {@link SessionTitleProvider} (the cloud cheap-model call by
+ * default) for a short action+object headline, and persists it
+ * (`lib/session/title.ts`). Because the value lands in the index, every consumer
+ * — the CLI list, the picker, `sessions watch --json`, the fleet mirror, AGI EXT
+ * — reads one title that was generated exactly once.
+ *
+ * Cost is bounded by construction, not by hope: at most
+ * {@link SESSION_TITLE_MAX_PER_TICK} generations per tick, only for sessions
+ * inside the display window, only for rows whose stored source key no longer
+ * matches their user text (so a titled session is a pure DB read forever after),
+ * and never for the titler's own spawned sessions. When the harness is missing
+ * or signed out every attempt fails, so the service backs off exponentially
+ * instead of respawning two processes a minute forever — the rows simply keep
+ * showing the user's own words, which is the honest fallback.
+ */
+import { runSessionTitleTick, SESSION_TITLE_MAX_PER_TICK } from '../session/title.js';
+import { BasePeriodicService } from './service.js';
+/** Cadence of the sweep. Slow on purpose: a title is not a live signal. */
+const SESSION_TITLE_TICK_MS = 2 * 60_000;
+/** Above the worst case (limit x the per-generation subprocess timeout), below the interval. */
+const SESSION_TITLE_DEADLINE_MS = 110_000;
+/** Ticks skipped after the first all-failed sweep, doubling up to the ceiling. */
+const SESSION_TITLE_BACKOFF_START = 2;
+/** ~1h at the tick cadence — long enough that a signed-out box stays quiet. */
+const SESSION_TITLE_BACKOFF_MAX = 30;
+export class SessionTitleService extends BasePeriodicService {
+    run;
+    id = 'session-title';
+    intervalMs = SESSION_TITLE_TICK_MS;
+    deadlineMs = SESSION_TITLE_DEADLINE_MS;
+    /** Let the box settle (shims, PATH, index warm) before spawning a harness. */
+    startupDelayMs = 60_000;
+    /** Ticks still to skip before the next attempt; 0 = attempt this tick. */
+    skipTicks = 0;
+    /** Skip count applied after the next all-failed sweep. */
+    backoff = 0;
+    /** `run` is the model-call seam (defaults to the real subprocess); tests inject one. */
+    constructor(run) {
+        super();
+        this.run = run;
+    }
+    async onStart(_ctx) { }
+    async onStop() { }
+    async onTick(ctx, signal) {
+        if (this.skipTicks > 0) {
+            this.skipTicks--;
+            return;
+        }
+        const result = await runSessionTitleTick({
+            limit: SESSION_TITLE_MAX_PER_TICK,
+            signal,
+            ...(this.run ? { run: this.run } : {}),
+        });
+        if (result.generated > 0) {
+            // A success clears the backoff: whatever was broken is working again.
+            this.backoff = 0;
+            ctx.log('INFO', `session-title: generated ${result.generated} title(s) (${result.cached} already current)`);
+            return;
+        }
+        if (result.failed > 0) {
+            this.backoff = this.backoff === 0
+                ? SESSION_TITLE_BACKOFF_START
+                : Math.min(this.backoff * 2, SESSION_TITLE_BACKOFF_MAX);
+            this.skipTicks = this.backoff;
+            ctx.log('WARN', `session-title: ${result.failed} generation(s) produced no title; backing off ${this.backoff} tick(s)`);
+        }
+        // Nothing generated and nothing failed = every recent session is titled.
+        // That is the steady state, and it logs nothing.
+    }
+}

package/dist/lib/daemon/usage-sync-service.d.ts

@@ -32,13 +32,21 @@ import type { DaemonServiceId } from '../daemon-services.js';
  * freshness gate is the CONSUMER of this producer's cadence: it skips the
  * pushes when the last exchange is older than one usage-sync interval, so it
  * must track this constant rather than its own equal-by-coincidence literal.
+ * Sourced from `usage-sync.ts`'s `USAGE_SYNC_INTERVAL_MS` rather than a
+ * second literal, so the two files can't drift out of sync with each other.
  */
 export declare const USAGE_SYNC_TICK_MS: number;
+/**
+ * Offset from auth-sync's 60s kickoff so the two never contend for the
+ * shared-repo lock. Auth fires at T+1m, T+16m, …; usage at T+8m, T+23m, …
+ * The git exchange deadline is 45s, so a 7-minute gap is the whole point.
+ */
+export declare const USAGE_SYNC_KICKOFF_MS: number;
 export declare class UsageSyncService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;
     readonly deadlineMs: number;
-    readonly startupDelayMs = 90000;
+    readonly startupDelayMs: number;
     protected onStart(_ctx: DaemonContext): Promise<void>;
     protected onStop(): Promise<void>;
     protected onTick(ctx: DaemonContext): Promise<void>;

package/dist/lib/daemon/usage-sync-service.js

@@ -26,15 +26,23 @@
  * deadline and circuit breaker.
  */
 import { BasePeriodicService } from './service.js';
+import { USAGE_SYNC_INTERVAL_MS } from '../accounting/usage-sync.js';
 /**
  * The usage-sync tick cadence. Exported because auth-sync's credential-push
  * freshness gate is the CONSUMER of this producer's cadence: it skips the
  * pushes when the last exchange is older than one usage-sync interval, so it
  * must track this constant rather than its own equal-by-coincidence literal.
+ * Sourced from `usage-sync.ts`'s `USAGE_SYNC_INTERVAL_MS` rather than a
+ * second literal, so the two files can't drift out of sync with each other.
  */
-export const USAGE_SYNC_TICK_MS = 15 * 60_000;
+export const USAGE_SYNC_TICK_MS = USAGE_SYNC_INTERVAL_MS;
 const USAGE_SYNC_DEADLINE_MS = 2 * 60_000;
-const USAGE_SYNC_KICKOFF_MS = 90_000;
+/**
+ * Offset from auth-sync's 60s kickoff so the two never contend for the
+ * shared-repo lock. Auth fires at T+1m, T+16m, …; usage at T+8m, T+23m, …
+ * The git exchange deadline is 45s, so a 7-minute gap is the whole point.
+ */
+export const USAGE_SYNC_KICKOFF_MS = 8 * 60_000;
 export class UsageSyncService extends BasePeriodicService {
     id = 'usage-sync';
     intervalMs = USAGE_SYNC_TICK_MS;

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'attention-notify' | 'harness-update';
+export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'session-title' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'attention-notify' | 'harness-update';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -107,6 +107,11 @@ export const DAEMON_SERVICES = [
         title: 'Attention desktop banners',
         description: 'Posts one actionable desktop banner per new attention item (question / permission / plan review / stall) so the macOS helper can answer it through agents feed answer (PHNX-4004).',
     },
+    {
+        id: 'session-title',
+        title: 'Session titles',
+        description: 'Generates the short technical title shown as each session row\'s headline, once per session, with a cheap model — so a row is named by what the user asked for, never by the agent\'s latest message.',
+    },
     {
         id: 'auth-sync',
         title: 'Auth bundle sync',

package/dist/lib/daemon-ticks.js

@@ -145,6 +145,7 @@ export async function runUsageRefreshTick(signal) {
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
     const { writeClaudeUsageCache, readClaudeUsageCache } = await import('./accounting/usage.js');
     const { usageRateLimitedUntil } = await import('./usage-backoff.js');
+    const { machineId } = await import('./machine-id.js');
     const r = await runUsageRefresh({
         listAccounts: buildLocalUsageAccounts,
         writeUsageCache: writeClaudeUsageCache,
@@ -156,6 +157,11 @@ export async function runUsageRefreshTick(signal) {
         // Thread the supervisor deadline into each provider fetch so the tick's I/O
         // is bounded by deadlineMs, not just each fetch's own 5s timeout (PHNX-3608).
         signal,
+        pollerDevice: machineId(),
+        onSnapshotsChanged: async () => {
+            const { pushUsageSnapshotNow } = await import('./accounting/usage-sync.js');
+            await pushUsageSnapshotNow();
+        },
     });
     const { listProfiles } = await import('./profiles.js');
     const { refreshDueByokUsage } = await import('./byok-usage.js');

package/dist/lib/fleet-shared-state.d.ts

@@ -21,6 +21,8 @@ export interface SessionMirrorRow {
     cwd?: string;
     topic?: string;
     label?: string;
+    /** The publisher's daemon-generated headline (PHNX-3797), when it has produced one. */
+    title?: string;
     firstUser?: string;
     lastActivity?: string;
     timestamp: string;

package/dist/lib/hooks/install.js

@@ -18,8 +18,9 @@ import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from '../agents.js';
 import { supports, explainSkip, capableAgents } from '../capabilities.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from '../state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir, getHistoryDir } from '../state.js';
 import { collectSubruleHooksFromState } from '../rules/compose.js';
+import { codexShortKey, resolveCodexHome } from '../codex-home.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
  * Resolve a hook script's absolute path. Checks user dir first, then enabled
@@ -2257,6 +2258,7 @@ export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, rem
     return removed;
 }
 function trustCodexHooks(hooksPath) {
+    const hookPaths = [...new Set([hooksPath, path.join(fs.realpathSync(path.dirname(hooksPath)), 'hooks.json')])];
     const configPath = path.join(path.dirname(hooksPath), 'config.toml');
     const hooksFile = JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
     let tomlConfig = {};
@@ -2294,16 +2296,16 @@ function trustCodexHooks(hooksPath) {
             group.hooks.forEach((handler, handlerIdx) => {
                 if (handler.type !== 'command')
                     return;
-                const key = `${hooksPath}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`;
+                const keys = hookPaths.map((file) => `${file}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`);
                 const trustedHash = computeCodexHookTrustHash(eventKeyLabel, handler.command, handler.timeout, group.matcher);
                 // Preserve a user's explicit `enabled = false` for this exact hook;
                 // only (re)write the trust hash.
-                const prior = existingState[key];
                 const entry = { trusted_hash: trustedHash };
-                if (prior && prior.enabled === false) {
+                if (keys.some((key) => existingState[key]?.enabled === false)) {
                     entry.enabled = false;
                 }
-                hookState[key] = entry;
+                for (const key of keys)
+                    hookState[key] = entry;
             });
         });
     }
@@ -3283,8 +3285,8 @@ export async function installSessionTrackerHook(agent, version, home) {
     if (!invocation) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
-    const env = sessionTrackerInstallEnv(agent, version, home);
     try {
+        const env = sessionTrackerInstallEnv(agent, version, home);
         await execFileAsync(invocation.command, invocation.args, {
             env,
             encoding: 'utf8',
@@ -3328,8 +3330,8 @@ export function installSessionTrackerHookSync(agent, version, home) {
     if (!invocation) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
-    const env = sessionTrackerInstallEnv(agent, version, home);
     try {
+        const env = sessionTrackerInstallEnv(agent, version, home);
         execFileSync(invocation.command, invocation.args, {
             env,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -3346,5 +3348,10 @@ export function installSessionTrackerHookSync(agent, version, home) {
 /** The hook installer must target this account, not the current global home. */
 function sessionTrackerInstallEnv(agent, version, home) {
     const target = home ?? (version ? getVersionHomePath(agent, version) : undefined);
+    if (agent === 'codex' && target && version) {
+        const originHome = path.join(target, '.codex');
+        const historyDir = getHistoryDir();
+        resolveCodexHome(originHome, path.dirname(historyDir), codexShortKey(originHome, version, historyDir));
+    }
     return target ? { ...process.env, HOME: target, USERPROFILE: target } : { ...process.env };
 }

package/dist/lib/mailbox-target.js

@@ -1,3 +1,4 @@
+import { sessionHeadline } from './session/title.js';
 /**
  * The mailbox id a live session's box is keyed by. Teams stamp a durable
  * `agentId` (== the Claude session id for Claude teammates); a bare run has
@@ -8,7 +9,7 @@ export function mailboxIdForActiveSession(s) {
     return s.agentId ?? s.sessionId;
 }
 function labelFor(s) {
-    return s.label ?? s.topic ?? s.teamName ?? s.host ?? s.context;
+    return sessionHeadline(s) ?? s.teamName ?? s.host ?? s.context;
 }
 /**
  * Resolve `target` against the live sessions. Exact id matches win over prefix

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

@@ -55,7 +55,15 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'account' | 'timestamp' | 'label' | 'firstUserMessage' | 'lastUserMessage' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness' | 'tokenCount' | 'durationMs' | 'subAgentCount' | 'lastActivity'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'account' | 'timestamp' | 'label' | 'firstUserMessage' | 'lastUserMessage' | 'generatedTitle' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness' | 'tokenCount' | 'durationMs' | 'subAgentCount' | 'lastActivity'>;
+/**
+ * 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 declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 export declare function isRunningLiveSession(s: ActiveSession): boolean;
@@ -108,13 +116,43 @@ export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'c
 export type SessionPhase = 'running' | 'waiting' | 'failed' | 'done' | 'idle';
 /**
  * Which rung of the recap ladder produced a row's shown {@link ActiveSession.title}
- * (RUSH-3011), best-first:
- *   - `label`  — a `/rename` or harness-set label (incl. an agent-generated
- *                title, which lands in `label`); always wins.
- *   - `last`   — the last assistant line from the transcript tail; agent-derived.
- *   - `prompt` — the first-user-prompt topic; the last-resort fallback.
+ * (RUSH-3011, reshaped by PHNX-3797), best-first:
+ *   - `label`     — a `/rename` or harness-set label (incl. a harness-generated
+ *                   title, which lands in `label`); always wins.
+ *   - `generated` — the daemon-generated session title (`generatedTitle`).
+ *   - `prompt`    — the first-user-prompt topic; the honest fallback while the
+ *                   titler has not reached this session.
+ *
+ * There is deliberately no rung for the agent's last transcript line: it is a
+ * rolling monologue, not what the session IS. It stays on the row as
+ * `lastAgentLine` for the separate live preview.
  */
-export type RecapSource = 'label' | 'last' | 'prompt';
+export type RecapSource = 'label' | 'generated' | 'prompt';
+/**
+ * How urgent a row's secondary line is (PHNX-3797 owner feedback), best-first:
+ *   - `question`  — the agent asked something and is parked on the answer;
+ *   - `needs_you` — blocked on the operator (a plan review, a permission, or a
+ *                   generic input-required wait) — the "needs you" case;
+ *   - `activity`  — nothing blocking; just what the agent is doing right now.
+ *
+ * `question`/`needs_you` are the signals a plain rolling activity preview buries,
+ * which is why they get their own ranked line distinct from the {@link ActiveSession.title}
+ * headline.
+ */
+export type ImportantMessageKind = 'question' | 'needs_you' | 'activity';
+/**
+ * The single most important recent agent message for a row's secondary line
+ * (PHNX-3797 owner feedback). Distinct from the headline ({@link ActiveSession.title}),
+ * which says what the session IS: this says what the agent is doing or waiting on
+ * RIGHT NOW, ranked by {@link deriveImportantMessage} so a blocking question or a
+ * needs-you beats generic activity.
+ */
+export interface SessionImportantMessage {
+    /** The message to show, trimmed + capped for a single line. */
+    text: string;
+    /** Its urgency class — drives ordering and any glyph/color the renderer adds. */
+    kind: ImportantMessageKind;
+}
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -148,12 +186,21 @@ export interface ActiveSession {
      */
     lastUserMessage?: string;
     /**
-     * The row's shown title — WHAT the session is, best-source-wins (RUSH-3011).
-     * The ladder ({@link deriveSessionRecap}): a `/rename` or harness `label` →
-     * the last agent line (`lastAgentLine`) → the first-prompt `topic`. A session
-     * whose agent did work shows an agent-derived line, not the stale first
-     * prompt. Folded on at the end of {@link getActiveSessions}; `recapSource`
-     * names which rung produced it.
+     * The daemon-generated session title (PHNX-3797) — a short technical label for
+     * what the session worked on, produced once per session by the `session-title`
+     * service and backfilled from the index by {@link backfillActiveRowsFromMeta}.
+     * Rung 2 of the headline ladder; see {@link title}.
+     */
+    generatedTitle?: string;
+    /**
+     * The row's shown title — WHAT the session is, best-source-wins (RUSH-3011,
+     * reshaped by PHNX-3797). The ladder ({@link deriveSessionRecap}): a `/rename`
+     * or harness `label` → the daemon-generated `generatedTitle` → the classified
+     * user prompt (from {@link lastUserMessage}/{@link firstUserMessage}/`topic`,
+     * PHNX-3939). It is a user-anchored NAME, never the agent's latest turn — that
+     * line stays in `lastAgentLine`/`preview`, where a live rolling status belongs.
+     * Folded on at the end of {@link getActiveSessions} (and re-derived after an
+     * index backfill); `recapSource` names which rung produced it.
      */
     title?: string;
     /** Which ladder rung produced {@link title}. */
@@ -168,11 +215,22 @@ export interface ActiveSession {
     userPromptKind?: UserPromptKind;
     /**
      * The most recent assistant line (from the transcript tail) — the free,
-     * always-current signal of what the agent last said/did. Ladder rung 3.
+     * always-current signal of what the agent last said/did. A LIVE-status field
+     * that belongs next to `preview`/`activity`; it is deliberately not a rung of
+     * the {@link title} ladder (PHNX-3797).
      */
     lastAgentLine?: string;
     /** Live preview: the latest turn (agent message or tool action), from the state engine. */
     preview?: string;
+    /**
+     * The row's SECONDARY line (PHNX-3797 owner feedback): the most important recent
+     * agent message — a pending question, a needs-you block, or the current activity —
+     * ranked by {@link deriveImportantMessage}. Distinct from the {@link title}
+     * headline; folded on beside it in {@link foldRecap} and carried on the same
+     * `sessions watch --json` / mirror feed (via spread) so AGI EXT can render a bold
+     * title over a dim secondary line without a second query.
+     */
+    importantMessage?: SessionImportantMessage;
     /** Inferred activity: working / waiting_input / idle (from the transcript tail). */
     activity?: SessionActivity;
     /**
@@ -937,7 +995,8 @@ export declare function sessionProcessIsLocal(s: Pick<ActiveSession, 'machine' |
 export declare function sessionProcessHost(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): string | undefined;
 export declare function foldHostLink(rows: ActiveSession[]): void;
 /**
- * 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`
@@ -946,8 +1005,15 @@ export declare function foldHostLink(rows: ActiveSession[]): void;
  * 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 declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 'topic' | 'tail' | 'firstUserMessage' | 'lastUserMessage' | 'attachments' | 'request'>): {
+export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 'generatedTitle' | 'topic' | 'tail' | 'firstUserMessage' | 'lastUserMessage' | 'attachments' | 'request'>): {
     title?: string;
     recapSource?: RecapSource;
     userPromptClean?: string;
@@ -955,6 +1021,17 @@ export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 't
     lastAgentLine?: string;
     request?: SessionRequest;
 };
+/**
+ * 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 declare function deriveImportantMessage(row: Pick<ActiveSession, 'status' | 'activity' | 'awaitingReason' | 'question' | 'preview' | 'lastAgentLine'>): SessionImportantMessage | undefined;
 /** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
 export declare function foldRecap(rows: ActiveSession[]): void;
 /**

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;
     }