@phnx-labs/agents-cli 1.22.109 → 1.22.111

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

@@ -0,0 +1,256 @@
+/**
+ * Daemon-generated session TITLES (PHNX-3797).
+ *
+ * The headline on a session row answers "what is this session about?", so it has
+ * to be anchored in what the USER asked for. It used to be the agent's latest
+ * transcript line — verbose, rolling, and unrecognizable to the person who
+ * started the run. The fix is a two-rung answer:
+ *
+ *  1. INSTANT, free: the user's own first message (already in the index) is the
+ *     honest fallback shown from the moment the session appears.
+ *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
+ *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
+ *     uses the `cheap` tier — haiku on Claude — through the same
+ *     `agents run --model <tier>` resolution every other call uses) for a short
+ *     ACTION + OBJECT headline of what the session is doing, and persists it in
+ *     the session index.
+ *
+ * Generation happens ONCE per session, in the daemon, and is keyed by
+ * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
+ * from — so a sweep that sees a stored key matching the row's current text skips
+ * it (the cache hit) and regenerates only when that first user message actually
+ * changed, or when an operator asks explicitly
+ * (`agents sessions backfill titles --refresh`). There is no per-tick model call
+ * and no per-client generation: the daemon writes one value, every consumer
+ * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
+ * it off the row.
+ *
+ * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
+ * an injectable runner seam, so the whole path is testable without spawning a
+ * harness.
+ */
+import type { SessionTitleCandidateRow } from './db.js';
+/**
+ * The phrase every generated-title prompt carries. Load-bearing twice over:
+ * `traces/sync.ts` classifies a session whose topic matches it as internal
+ * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
+ * uses it to keep the titler from titling its OWN spawned sessions — which
+ * would otherwise be a runaway loop, since each generation creates one more
+ * untitled session.
+ *
+ * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
+ * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
+ * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
+ * of 4–8 words; the sentinel deliberately carries no word budget so the two never
+ * drift.
+ */
+export declare const SESSION_TITLE_PROMPT_MARKER = "Generate a concise session headline";
+/** Hard ceiling on a stored title; the prompt asks for far less. */
+export declare const SESSION_TITLE_MAX_CHARS = 60;
+/** Hard ceiling on words kept from a model reply that ignored the word budget. */
+export declare const SESSION_TITLE_MAX_WORDS = 8;
+/** How much user text the prompt carries — enough to be specific, bounded for cost. */
+export declare const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
+/** How many sessions one periodic sweep may generate for. */
+export declare const SESSION_TITLE_MAX_PER_TICK = 2;
+/** How many recent rows a sweep inspects before picking that batch. */
+export declare const SESSION_TITLE_CANDIDATE_SCAN = 200;
+/** Only sessions active within this window are titled — older rows are not shown. */
+export declare const SESSION_TITLE_MAX_AGE_MS: number;
+/** Per-generation subprocess ceiling. A title is not worth waiting on. */
+export declare const SESSION_TITLE_TIMEOUT_MS = 45000;
+/** The harnesses the titler will run as, best first. The first installed one wins. */
+export declare const SESSION_TITLE_AGENTS: readonly ["claude", "codex", "grok", "kimi", "opencode"];
+/** The user text a title is derived from, plus the context that makes it technical. */
+export interface SessionTitleInput {
+    firstUserMessage?: string | null;
+    topic?: string | null;
+    project?: string | null;
+    ticketId?: string | null;
+    gitBranch?: string | null;
+}
+/** The user text itself — the ONLY thing the source key is computed over. */
+export declare function sessionTitleSourceText(input: SessionTitleInput): string;
+/**
+ * Stable identity of the text a title was generated from. Storing this beside
+ * the title is what makes "already titled" distinguishable from "the user's
+ * first message changed" without keeping a second copy of that text.
+ * Empty text yields `null`: there is nothing to title.
+ */
+export declare function sessionTitleSourceKey(input: SessionTitleInput): string | null;
+/**
+ * True when this text is one of the titler's OWN prompts. The titler runs a real
+ * harness, which writes a real transcript, which lands in the index as another
+ * untitled session — so without this guard every title generated would create
+ * work for the next sweep, forever.
+ */
+export declare function isSessionTitlePrompt(...values: Array<string | null | undefined>): boolean;
+/**
+ * The one-shot prompt handed to the cheap model.
+ *
+ * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
+ * concrete task, "Triage the AGI board", "Rename browser profile — default
+ * confusion"), not a single terse noun ("Triage") and not a full sentence — the
+ * headline slot has to tell the person who started the run what the session is
+ * doing at a glance. The word budget is soft in the prompt and hard-enforced by
+ * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
+ */
+export declare function renderSessionTitlePrompt(input: SessionTitleInput): string;
+/**
+ * Reduce a model reply to a storable title, or `undefined` when it produced
+ * nothing usable. Takes the first non-empty line (a chatty model puts the title
+ * first), strips wrapping quotes/backticks and trailing punctuation, and applies
+ * the word + character ceilings. A reply that is really a refusal or an
+ * explanation fails the ceilings and is dropped rather than shown.
+ */
+export declare function sanitizeGeneratedTitle(raw: string | null | undefined): string | undefined;
+/**
+ * Compile-time guard: resolves to `T` only when `T` actually declares a
+ * `generatedTitle` key, and to `never` otherwise.
+ *
+ * This exists because structural typing makes the obvious signature useless. A
+ * parameter typed `{ generatedTitle?: string }` is satisfied by an object type
+ * that has no such property at all, so passing a projection that DROPPED the
+ * field — the watchdog's `SessionOutcome`, which copied `label`/`name`/`topic`
+ * off the session and left `generatedTitle` behind — compiles cleanly and
+ * silently degrades {@link sessionHeadline} back to `label || topic`. That is a
+ * real bug this feature shipped once and a lexical lint cannot see, since the
+ * call site looks correct. `keyof` includes optional keys, so every legitimate
+ * carrier (`SessionMeta`, `ActiveSession`, a `Pick<>` that names it) still
+ * passes; only a type that never modelled the rung is rejected.
+ */
+type CarriesTitleRung<T> = 'generatedTitle' extends keyof T ? T : never;
+/**
+ * The headline for an INDEXED session row, on the same ladder the live path uses
+ * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
+ * first-prompt topic. Every `agents sessions` surface that shows "what this
+ * session is" reads it from here, so the CLI and the watch stream can never
+ * disagree about a session's name (PHNX-3797).
+ *
+ * A caller whose row type does not carry `generatedTitle` fails to compile
+ * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
+ * than casting past this.
+ */
+export declare function sessionHeadline<T extends {
+    label?: string | null;
+    generatedTitle?: string | null;
+    topic?: string | null;
+}>(row: CarriesTitleRung<T>): string | undefined;
+/**
+ * Runs the cheap model once and returns its raw stdout. Injectable so tests
+ * exercise the whole tick — candidate selection, key comparison, persistence —
+ * without spawning a harness.
+ */
+export type SessionTitleRunner = (prompt: string, signal?: AbortSignal) => Promise<string>;
+/** The harness the titler runs as on this box, or null when none is installed. */
+export declare function resolveSessionTitleAgent(): Promise<string | null>;
+/**
+ * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
+ * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
+ * `--model cheap` goes through the same tier resolution every other run uses, so
+ * the box's own catalog picks haiku (or its per-harness equivalent) rather than
+ * this module hardcoding a model id that ages out.
+ */
+export declare function defaultSessionTitleRunner(prompt: string, signal?: AbortSignal): Promise<string>;
+/**
+ * A pluggable backend that turns a session's user text into a raw headline reply
+ * — the ONE part of title generation that varies by model host (PHNX-3797).
+ *
+ * The tick decides WHICH sessions need a title, caches by source key, sanitizes,
+ * and persists — none of that is provider-specific, so only the model call itself
+ * sits behind this interface. The shipped default is
+ * {@link CloudSessionTitleProvider} (one cheap cloud-model subprocess). A LOCAL
+ * backend — e.g. an ollama 1–3B instruct model over HTTP — is a drop-in: implement
+ * `generate` and hand the instance to {@link runSessionTitleTick} (or construct
+ * {@link SessionTitleService} with it). No call site inside the tick changes, and
+ * the shared {@link sanitizeGeneratedTitle} still enforces the word/character
+ * ceilings on whatever text the backend returns.
+ *
+ * `generate` returns the model's RAW reply (the tick owns sanitizing). It MAY
+ * throw — harness missing, signed out, timed out — and the tick treats a throw as
+ * "no title this sweep", leaving the row on the user's own words and backing off.
+ */
+export interface SessionTitleProvider {
+    /** Stable id for logs/diagnostics (e.g. `'cloud'`, `'ollama'`). */
+    readonly name: string;
+    /** Produce a raw headline reply for one session's user text, or throw. */
+    generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
+}
+/**
+ * The default, shipped provider: render the shared prompt and run it through a
+ * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
+ * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
+ * a whole fake provider) to exercise the tick without spawning a harness.
+ */
+export declare class CloudSessionTitleProvider implements SessionTitleProvider {
+    private readonly runner;
+    readonly name = "cloud";
+    constructor(runner?: SessionTitleRunner);
+    generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
+}
+/** The provider used when a caller injects neither a `provider` nor a `run`. */
+export declare function defaultSessionTitleProvider(): SessionTitleProvider;
+export interface SessionTitleTickOptions {
+    /** Max sessions generated for in this sweep. */
+    limit?: number;
+    /** Title this session specifically (an explicit refresh), ignoring the recency window. */
+    id?: string;
+    /** Regenerate even when the stored key still matches the row's user text. */
+    force?: boolean;
+    /**
+     * The generation backend. Defaults to {@link defaultSessionTitleProvider}
+     * (the cheap cloud model). Swap this for a local model without touching the
+     * tick. Takes precedence over {@link SessionTitleTickOptions.run}.
+     */
+    provider?: SessionTitleProvider;
+    /**
+     * Shortcut seam for the cloud provider's raw model call — wrapped in a
+     * {@link CloudSessionTitleProvider} when no {@link provider} is given. Kept for
+     * the daemon service and the tests that inject only the subprocess.
+     */
+    run?: SessionTitleRunner;
+    signal?: AbortSignal;
+    nowMs?: number;
+    maxAgeMs?: number;
+}
+export interface SessionTitleTickResult {
+    /** Rows inspected. */
+    scanned: number;
+    /** Rows already carrying a title for their current user text (the cache hit). */
+    cached: number;
+    /** Titles generated and persisted this sweep. */
+    generated: number;
+    /** Generation attempts that produced nothing usable (model unavailable, empty reply). */
+    failed: number;
+    titles: Array<{
+        id: string;
+        title: string;
+    }>;
+}
+/**
+ * Decide what one sweep should do, without touching the model. Pure over its
+ * inputs so the "generate once, then cache-hit" property is directly testable:
+ * a candidate is work only when its user text yields a key AND that key differs
+ * from the one stored beside its title (or `force`).
+ */
+export declare function selectSessionsNeedingTitle(rows: SessionTitleCandidateRow[], opts?: {
+    limit: number;
+    force?: boolean;
+}): {
+    pending: Array<{
+        row: SessionTitleCandidateRow;
+        sourceKey: string;
+    }>;
+    cached: number;
+};
+/**
+ * One titling sweep: pick the sessions whose headline is still the raw user
+ * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
+ * them, and persist each. Best-effort by contract — a failed generation leaves
+ * the row untitled, which the ladder renders as the user's own first message.
+ *
+ * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
+ * indexed session (a caller error); the periodic sweep never throws.
+ */
+export declare function runSessionTitleTick(options?: SessionTitleTickOptions): Promise<SessionTitleTickResult>;
+export {};

package/dist/lib/session/title.js

@@ -0,0 +1,312 @@
+/**
+ * Daemon-generated session TITLES (PHNX-3797).
+ *
+ * The headline on a session row answers "what is this session about?", so it has
+ * to be anchored in what the USER asked for. It used to be the agent's latest
+ * transcript line — verbose, rolling, and unrecognizable to the person who
+ * started the run. The fix is a two-rung answer:
+ *
+ *  1. INSTANT, free: the user's own first message (already in the index) is the
+ *     honest fallback shown from the moment the session appears.
+ *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
+ *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
+ *     uses the `cheap` tier — haiku on Claude — through the same
+ *     `agents run --model <tier>` resolution every other call uses) for a short
+ *     ACTION + OBJECT headline of what the session is doing, and persists it in
+ *     the session index.
+ *
+ * Generation happens ONCE per session, in the daemon, and is keyed by
+ * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
+ * from — so a sweep that sees a stored key matching the row's current text skips
+ * it (the cache hit) and regenerates only when that first user message actually
+ * changed, or when an operator asks explicitly
+ * (`agents sessions backfill titles --refresh`). There is no per-tick model call
+ * and no per-client generation: the daemon writes one value, every consumer
+ * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
+ * it off the row.
+ *
+ * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
+ * an injectable runner seam, so the whole path is testable without spawning a
+ * harness.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The phrase every generated-title prompt carries. Load-bearing twice over:
+ * `traces/sync.ts` classifies a session whose topic matches it as internal
+ * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
+ * uses it to keep the titler from titling its OWN spawned sessions — which
+ * would otherwise be a runaway loop, since each generation creates one more
+ * untitled session.
+ *
+ * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
+ * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
+ * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
+ * of 4–8 words; the sentinel deliberately carries no word budget so the two never
+ * drift.
+ */
+export const SESSION_TITLE_PROMPT_MARKER = 'Generate a concise session headline';
+/** Hard ceiling on a stored title; the prompt asks for far less. */
+export const SESSION_TITLE_MAX_CHARS = 60;
+/** Hard ceiling on words kept from a model reply that ignored the word budget. */
+export const SESSION_TITLE_MAX_WORDS = 8;
+/** How much user text the prompt carries — enough to be specific, bounded for cost. */
+export const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
+/** How many sessions one periodic sweep may generate for. */
+export const SESSION_TITLE_MAX_PER_TICK = 2;
+/** How many recent rows a sweep inspects before picking that batch. */
+export const SESSION_TITLE_CANDIDATE_SCAN = 200;
+/** Only sessions active within this window are titled — older rows are not shown. */
+export const SESSION_TITLE_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
+/** Per-generation subprocess ceiling. A title is not worth waiting on. */
+export const SESSION_TITLE_TIMEOUT_MS = 45_000;
+/** The harnesses the titler will run as, best first. The first installed one wins. */
+export const SESSION_TITLE_AGENTS = ['claude', 'codex', 'grok', 'kimi', 'opencode'];
+/** The user text itself — the ONLY thing the source key is computed over. */
+export function sessionTitleSourceText(input) {
+    const raw = (input.firstUserMessage || input.topic || '').replace(/\s+/g, ' ').trim();
+    return raw.length > SESSION_TITLE_INPUT_MAX_CHARS ? raw.slice(0, SESSION_TITLE_INPUT_MAX_CHARS) : raw;
+}
+/**
+ * Stable identity of the text a title was generated from. Storing this beside
+ * the title is what makes "already titled" distinguishable from "the user's
+ * first message changed" without keeping a second copy of that text.
+ * Empty text yields `null`: there is nothing to title.
+ */
+export function sessionTitleSourceKey(input) {
+    const text = sessionTitleSourceText(input);
+    if (!text)
+        return null;
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * True when this text is one of the titler's OWN prompts. The titler runs a real
+ * harness, which writes a real transcript, which lands in the index as another
+ * untitled session — so without this guard every title generated would create
+ * work for the next sweep, forever.
+ */
+export function isSessionTitlePrompt(...values) {
+    return values.some((v) => typeof v === 'string' && v.includes(SESSION_TITLE_PROMPT_MARKER));
+}
+/**
+ * The one-shot prompt handed to the cheap model.
+ *
+ * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
+ * concrete task, "Triage the AGI board", "Rename browser profile — default
+ * confusion"), not a single terse noun ("Triage") and not a full sentence — the
+ * headline slot has to tell the person who started the run what the session is
+ * doing at a glance. The word budget is soft in the prompt and hard-enforced by
+ * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
+ */
+export function renderSessionTitlePrompt(input) {
+    const text = sessionTitleSourceText(input);
+    const context = [
+        input.project ? `Repository: ${input.project}` : null,
+        input.ticketId ? `Ticket: ${input.ticketId}` : null,
+        input.gitBranch ? `Branch: ${input.gitBranch}` : null,
+    ].filter(Boolean);
+    return [
+        `${SESSION_TITLE_PROMPT_MARKER} naming what this coding session is working on.`,
+        'Write an ACTION + OBJECT headline of 4 to 8 words — a verb phrase naming the concrete task,',
+        'e.g. "Triage the AGI board" or "Rename browser profile — default confusion".',
+        'NOT a single noun, NOT a full sentence. Name the concrete feature, component, or fix —',
+        'not the person, not the pleasantries.',
+        'Respond IMMEDIATELY with only the headline. Do NOT investigate, do NOT read files, do NOT use any tools.',
+        'No quotes, no trailing punctuation, no explanation.',
+        ...(context.length ? ['', ...context] : []),
+        '',
+        "The user's request:",
+        '---',
+        text,
+        '---',
+    ].join('\n');
+}
+/**
+ * Reduce a model reply to a storable title, or `undefined` when it produced
+ * nothing usable. Takes the first non-empty line (a chatty model puts the title
+ * first), strips wrapping quotes/backticks and trailing punctuation, and applies
+ * the word + character ceilings. A reply that is really a refusal or an
+ * explanation fails the ceilings and is dropped rather than shown.
+ */
+export function sanitizeGeneratedTitle(raw) {
+    if (!raw)
+        return undefined;
+    const firstLine = raw.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    if (!firstLine)
+        return undefined;
+    let title = firstLine
+        .replace(/^["'`*_\s]+/, '')
+        .replace(/["'`*_\s]+$/, '')
+        .replace(/[.!?,;:]+$/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!title)
+        return undefined;
+    // A model that ignored the budget gets truncated, not shown in full — a
+    // paragraph in the headline slot is the very failure this feature removes.
+    const words = title.split(' ');
+    if (words.length > SESSION_TITLE_MAX_WORDS)
+        title = words.slice(0, SESSION_TITLE_MAX_WORDS).join(' ');
+    if (title.length > SESSION_TITLE_MAX_CHARS)
+        title = title.slice(0, SESSION_TITLE_MAX_CHARS).trimEnd();
+    // Never store the prompt back as a title (a harness that echoed its input).
+    if (isSessionTitlePrompt(title))
+        return undefined;
+    return title || undefined;
+}
+/**
+ * The headline for an INDEXED session row, on the same ladder the live path uses
+ * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
+ * first-prompt topic. Every `agents sessions` surface that shows "what this
+ * session is" reads it from here, so the CLI and the watch stream can never
+ * disagree about a session's name (PHNX-3797).
+ *
+ * A caller whose row type does not carry `generatedTitle` fails to compile
+ * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
+ * than casting past this.
+ */
+export function sessionHeadline(row) {
+    return row.label || row.generatedTitle || row.topic || undefined;
+}
+/** The harness the titler runs as on this box, or null when none is installed. */
+export async function resolveSessionTitleAgent() {
+    // Lazy import: this module is also imported by render paths that must not pull
+    // the installation store (and its filesystem probes) into a hot listing.
+    const { listInstalledVersions } = await import('../installations/store.js');
+    for (const agent of SESSION_TITLE_AGENTS) {
+        try {
+            if (listInstalledVersions(agent).length > 0)
+                return agent;
+        }
+        catch {
+            // An unreadable store for one agent must not hide the others.
+        }
+    }
+    return null;
+}
+/**
+ * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
+ * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
+ * `--model cheap` goes through the same tier resolution every other run uses, so
+ * the box's own catalog picks haiku (or its per-harness equivalent) rather than
+ * this module hardcoding a model id that ages out.
+ */
+export async function defaultSessionTitleRunner(prompt, signal) {
+    const [{ getAgentsInvocation }, { execFile }, { promisify }] = await Promise.all([
+        import('../daemon/daemon.js'),
+        import('node:child_process'),
+        import('node:util'),
+    ]);
+    const agent = await resolveSessionTitleAgent();
+    if (!agent)
+        throw new Error('no installed harness can generate a session title');
+    const inv = getAgentsInvocation(['run', agent, '--mode', 'plan', '--model', 'cheap', prompt]);
+    const { stdout } = await promisify(execFile)(inv.command, inv.args, {
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+        timeout: SESSION_TITLE_TIMEOUT_MS,
+        signal,
+    });
+    return stdout;
+}
+/**
+ * The default, shipped provider: render the shared prompt and run it through a
+ * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
+ * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
+ * a whole fake provider) to exercise the tick without spawning a harness.
+ */
+export class CloudSessionTitleProvider {
+    runner;
+    name = 'cloud';
+    constructor(runner = defaultSessionTitleRunner) {
+        this.runner = runner;
+    }
+    generate(input, signal) {
+        return this.runner(renderSessionTitlePrompt(input), signal);
+    }
+}
+/** The provider used when a caller injects neither a `provider` nor a `run`. */
+export function defaultSessionTitleProvider() {
+    return new CloudSessionTitleProvider();
+}
+/**
+ * Decide what one sweep should do, without touching the model. Pure over its
+ * inputs so the "generate once, then cache-hit" property is directly testable:
+ * a candidate is work only when its user text yields a key AND that key differs
+ * from the one stored beside its title (or `force`).
+ */
+export function selectSessionsNeedingTitle(rows, opts = { limit: SESSION_TITLE_MAX_PER_TICK }) {
+    const pending = [];
+    let cached = 0;
+    for (const row of rows) {
+        // The titler's own runs are sessions too; titling them would spawn another.
+        if (isSessionTitlePrompt(row.firstUserMessage, row.topic))
+            continue;
+        const sourceKey = sessionTitleSourceKey(row);
+        if (!sourceKey)
+            continue;
+        if (!opts.force && row.generatedTitle && row.generatedTitleKey === sourceKey) {
+            cached++;
+            continue;
+        }
+        if (pending.length < opts.limit)
+            pending.push({ row, sourceKey });
+    }
+    return { pending, cached };
+}
+/**
+ * One titling sweep: pick the sessions whose headline is still the raw user
+ * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
+ * them, and persist each. Best-effort by contract — a failed generation leaves
+ * the row untitled, which the ladder renders as the user's own first message.
+ *
+ * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
+ * indexed session (a caller error); the periodic sweep never throws.
+ */
+export async function runSessionTitleTick(options = {}) {
+    const limit = options.limit ?? SESSION_TITLE_MAX_PER_TICK;
+    const now = options.nowMs ?? Date.now();
+    const result = { scanned: 0, cached: 0, generated: 0, failed: 0, titles: [] };
+    const { querySessionTitleCandidates, setSessionGeneratedTitle } = await import('./db.js');
+    const rows = querySessionTitleCandidates(options.id ? 1 : SESSION_TITLE_CANDIDATE_SCAN, options.id
+        ? { id: options.id }
+        : { sinceMs: now - (options.maxAgeMs ?? SESSION_TITLE_MAX_AGE_MS) });
+    result.scanned = rows.length;
+    // An explicitly requested session that has no indexed row is a caller error,
+    // not a quiet sweep outcome: reporting "0 generated" would read as "already
+    // current" for an id that was simply mistyped or not scanned yet.
+    if (options.id && rows.length === 0) {
+        throw new Error(`no indexed session matches "${options.id}" on this machine — ` +
+            `a session is titled after it is indexed (the daemon indexes within seconds), ` +
+            `and a peer's sessions are titled on the box that owns them`);
+    }
+    const { pending, cached } = selectSessionsNeedingTitle(rows, { limit, force: options.force });
+    result.cached = cached;
+    if (pending.length === 0)
+        return result;
+    // The provider is the ONLY thing that varies by model host; everything above
+    // (candidate selection, the source-key cache) and below (sanitize, persist) is
+    // shared. A local backend is dropped in here, not woven through the tick.
+    const provider = options.provider ?? new CloudSessionTitleProvider(options.run);
+    for (const { row, sourceKey } of pending) {
+        if (options.signal?.aborted)
+            break;
+        let title;
+        try {
+            title = sanitizeGeneratedTitle(await provider.generate(row, options.signal));
+        }
+        catch {
+            // Harness unavailable, signed out, or over its deadline. Best-effort: the
+            // row keeps showing the user's own words, and the caller backs off.
+            title = undefined;
+        }
+        if (!title) {
+            result.failed++;
+            continue;
+        }
+        if (setSessionGeneratedTitle(row.id, title, sourceKey, now)) {
+            result.generated++;
+            result.titles.push({ id: row.id, title });
+        }
+    }
+    return result;
+}

package/dist/lib/session/tool-index.d.ts

@@ -31,6 +31,11 @@ export interface ToolSessionEvidence {
     cwd?: string;
     topic?: string;
     label?: string;
+    /** The daemon-generated headline (PHNX-3797). Carried so a consumer of this
+     * envelope names a session the same way every other surface does; a
+     * projection that drops it silently degrades `sessionHeadline` to
+     * `label || topic`. */
+    generatedTitle?: string;
     filePath?: string;
     calls: ToolCallEvidence[];
 }

package/dist/lib/session/tool-index.js

@@ -869,6 +869,7 @@ export function searchToolCalls(sessions, clauseSources, coverage, resultLimit =
             cwd: session.cwd,
             topic: session.topic,
             label: session.label,
+            generatedTitle: session.generatedTitle,
             calls: selected,
         });
         if (matched.length >= resultLimit)

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

@@ -412,6 +412,17 @@ export interface SessionMeta {
      * single-turn session; absent for rows indexed before this field shipped.
      */
     lastUserMessage?: string;
+    /**
+     * The daemon-generated session TITLE (PHNX-3797) — a short, descriptive
+     * ACTION + OBJECT headline ("Triage the AGI board") for what the session is
+     * doing, produced ONCE per session by the `session-title` daemon service from
+     * the user's own first message (never from the agent's latest turn) and
+     * persisted in the index. It is the second rung of
+     * the headline ladder (`deriveSessionRecap`): an explicit `/rename` {@link label}
+     * still wins, and a session the titler has not reached yet falls back to
+     * `firstUserMessage`/`topic`, never to the agent's last line.
+     */
+    generatedTitle?: string;
     /**
      * The session's human-readable name — one field, several sources with a plain
      * priority: an agent-generated title / Claude `/rename` wins; else the launch

package/dist/lib/startup/root-command.d.ts

@@ -18,3 +18,5 @@ import type { Command } from 'commander';
  * instead (renaming the colliding options), not with this global flag.
  */
 export declare function configureRootCommand(program: Command, name: string, version: string): Command;
+/** Resume takes one device; its parent listing command takes a variadic list. */
+export declare function normalizeResumeDeviceArgs(args: string[]): string[];

package/dist/lib/startup/root-command.js

@@ -26,3 +26,25 @@ export function configureRootCommand(program, name, version) {
         .helpOption('-h, --help', 'Show help')
         .addHelpCommand(false);
 }
+/** Resume takes one device; its parent listing command takes a variadic list. */
+export function normalizeResumeDeviceArgs(args) {
+    if (args[0] !== 'sessions' || args[1] !== 'resume')
+        return args;
+    let options = true;
+    return args.map((arg, index) => {
+        if (index < 2 || !options)
+            return arg;
+        if (arg === '--') {
+            options = false;
+            return arg;
+        }
+        if (arg === '--device' || arg === '--devices' || arg === '-D')
+            return '--resume-device';
+        if (arg.startsWith('--device=') || arg.startsWith('--devices=')) {
+            return `--resume-device=${arg.slice(arg.indexOf('=') + 1)}`;
+        }
+        if (arg.startsWith('-D'))
+            return `--resume-device=${arg.slice(arg[2] === '=' ? 3 : 2)}`;
+        return arg;
+    });
+}

package/dist/lib/traces/sync.js

@@ -237,6 +237,7 @@ export async function syncTraces(opts = {}) {
  */
 const UTILITY_PROMPT_SIGNATURES = [
     /generate a 3-4 word title/i, // title generation
+    /generate a concise session headline/i, // session-title daemon service (PHNX-3797)
     /you are a watchdog|watchdog monitoring/i, // watchdog tick
     /conventional[- ]commit/i, // commit-message writer
     /factory worker/i, // dispatched factory worker