@phnx-labs/agents-cli 1.22.109 → 1.22.110

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.22.110
+
+- **Session rows are named by what YOU asked for, not by the agent's latest
+  message (PHNX-3797).** Every headline in `agents sessions`, the picker, and the
+  AGI EXT Sessions/Fleet list used to be the agent's last transcript line
+  ("Both seams verified on the real shipped artifacts…") — verbose, rolling, and
+  unrecognizable. The headline ladder is now `/rename` label → a
+  daemon-generated title → your own first message; the agent's live line stays in
+  the separate preview slot where a rolling status belongs. The new
+  `session-title` daemon service generates a short, descriptive **action + object
+  headline** ("Triage the AGI board", not just "Triage") with a cheap model
+  through a swappable `SessionTitleProvider` (cloud default; a local ollama-style
+  backend can be dropped in later without touching the tick), read-only plan mode,
+  **once** per session and
+  persists it in the session index against a hash of the message it came from, so
+  a titled session costs no further model calls and only re-titles when that first
+  message changes. Nothing generates per client or per tick: the value rides the
+  existing `sessions watch --json` stream and the fleet session mirror, so a
+  remote box's rows show the same title with no per-row SSH. Until the titler
+  reaches a session it shows your own words — never an agent line.
+  `agents sessions backfill titles [--session <id>] [--refresh]` runs it on
+  demand; `agents daemon services` can turn the service off.
+- **Session rows carry a ranked secondary line (PHNX-3797).** Beside the bold
+  headline, every live row now folds on `importantMessage` — the single most
+  important recent agent message, ranked so a pending **question** or a
+  **needs-you** block (plan review, permission, input-required) beats generic
+  current activity. It rides the same `sessions watch --json` / mirror feed as the
+  title (via the row spread), so AGI EXT renders a bold title over a dim secondary
+  line with no extra query; `agents sessions --active` prints the question /
+  needs-you line dim beneath the row.
+  Source: `src/lib/session/title.ts`, `src/lib/daemon/session-title-service.ts`,
+  `src/lib/session/active.ts`, `src/lib/session/db.ts`, `src/lib/session/mirror.ts`,
+  `src/commands/sessions.ts`, `src/commands/sessions-backfill.ts`.
+
+- Codex account sessions record their originating account after hook sync, including macOS homes relocated for Unix socket limits. Registration refreshes trust for the runtime home and removes the obsolete builtin tracker that could overwrite account metadata; unrelated hooks and explicit disabled states are preserved.
+
+- **Session resume preserves device and picker filters (PHNX-3940).** `sessions resume --device <host> <id>` and the equivalent device-after-ID form now open on the selected origin device. Agent, account, directory, time, and limit filters reach the shared picker; an unspecified limit remains 200. Repeated different devices produce an error.
+
+- **Usage snapshots stay fresh enough for balanced to auto-pick (PHNX-3940 W3).** A headed box polls only the accounts it holds native logins for; a setup-token-only worker never hits the usage endpoint. A changed snapshot is published immediately (statusline ingest or poll) instead of waiting for the 15-minute tick. `isUsageVerified` trusts a row that arrived via sync from the account's poller for that 15-minute cadence, and keeps the 5-minute bar for a local capture. `auth-sync` and `usage-sync` take the shared-repo lock on different offsets so they no longer starve each other. Source: `cli/src/lib/usage-refresh.ts`, `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/accounting/usage-sync.ts`.
+
 ## 1.22.109
 
 - **`agents sessions backup-setup` provisions the managed session-backup endpoint (PHNX-3726).** The operator command that deploys `sessions.agents-cli.sh` — the Cloudflare Worker + R2 bucket a signed-in user's `agents sessions export --to-r2` backs up to with no `r2.backups` bucket of their own. Mirrors `agents traces setup`: reads Cloudflare credentials from the `cloudflare` secrets bundle (`agents secrets exec cloudflare -- agents sessions backup-setup`), idempotent (re-running redeploys the current Worker template in place). It is NOT a per-user step — signing in with `agents auth login` is all a user does; this is how the first-party endpoint itself is deployed. The Worker it deploys is Phoenix-only with no static token (PHNX-3726). Source: `cli/src/commands/sessions-backup-setup.ts`, `cli/src/lib/session/sync/provision.ts` (+ `provision.test.ts`), `cli/docs/sessions.md`.
@@ -39,6 +79,10 @@
 
 - **`agents view` shows OpenCode's real model, account, plan, and last-active (PHNX-3982).** The OpenCode row was the only one in the table with nothing usable in it — `1.18.15 (default)  default  id:meta+openai+opencode-go` — while every other harness showed a model, an email, and a plan. Three separate reads were pointed at the wrong place. (1) The model came from `<home>/.opencode/settings.json`, which is agents-cli's own plugin-enablement file; OpenCode reads `~/.config/opencode/opencode.{jsonc,json}`, and ships no catalog default, so the row fell through to the literal placeholder `default`. Both spellings are now read comment-tolerantly, and when nothing is configured the row shows the model OpenCode itself will start with, from the selection it persists to `$XDG_STATE_HOME/opencode/model.json`. (2) The account showed only the provider join because the code asserted OpenCode's `auth.json` carries no identity — it does, for `type: 'oauth'` providers, in the same namespaced JWT claims `case 'codex'` already decodes, so the email and plan now render (secrets are never read out, only claims). (3) `lastActive` was blank because the per-file session walk finds nothing for a harness that keeps every session in one sqlite file; it now dates from `opencode.db`. Live usage *windows* remain unavailable for OpenCode — it records no rate-limit state locally and each provider would need its own reader. Source: `cli/src/lib/agent-spec/agents.ts`, `cli/src/lib/models.ts`.
 
+- **Codex trace error rates now reflect failed tool calls (PHNX-3761).** The tool-call index recognizes Codex's script completion and failure markers, preserves text across input blocks, and re-indexes older rows instead of reporting failed calls as unknown.
+
+- **`agents sessions --cloud <id>` and `agents cloud view` open OpenCode cloud transcripts (PHNX-3845).** Cloud discovery and fetch accept OpenCode sessions, and normalized cloud transcripts are parsed separately from local SQLite sessions. Both `bash` and `shell` tool names appear as command events.
+
 ## 1.22.108
 
 - Account sync now refreshes the native session-tracking hook in every account home, replacing stale registrations from previous CLI installations so new sessions retain their account identity. Codex tracker installation also refreshes hook trust so headless runs can execute the registered hook.

package/dist/bootstrap.js

@@ -19,7 +19,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { detectDevBuild } from './lib/startup/dev-build.js';
-import { configureRootCommand } from './lib/startup/root-command.js';
+import { configureRootCommand, normalizeResumeDeviceArgs } from './lib/startup/root-command.js';
 import { bootMark } from './lib/boot-profile.js';
 // `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
 // modules are imported dynamically at their use sites: they are needed only on
@@ -877,7 +877,8 @@ program.on('command:*', (operands) => {
 // Parse the invocation shape up front: the first non-flag token is the command,
 // and the doc flags (--version/--help/-h) drive both the registration strategy
 // and whether the update check + background sync run at all.
-const passedArgs = process.argv.slice(2);
+const passedArgs = normalizeResumeDeviceArgs(process.argv.slice(2));
+process.argv.splice(2, process.argv.length - 2, ...passedArgs);
 // Commander owns `--version` on the root command and otherwise intercepts it
 // even after `sessions`, before the subcommand can parse its version filter.
 // Rewrite only that value-taking nested form; bare `agents --version` and every

package/dist/commands/browser-sessions-picker.js

@@ -18,6 +18,7 @@ import { buildPreview } from './sessions-picker.js';
 import { createSessionsPickerCommand } from './sessions-picker-factory.js';
 import { runBrowserSessions, buildBrowserSessionRows, matchesBrowserSessionRow, formatBytes, } from '../lib/browser/sessions-list.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
+import { sessionHeadline } from '../lib/session/title.js';
 const KIND_LABEL = {
     screenshot: 'shots',
     pdf: 'pdf',
@@ -37,7 +38,7 @@ function rowLinkSummary(row) {
         return '';
     if (row.linkStatus === 'linked' && row.linkedSession) {
         const s = row.linkedSession;
-        return chalk.cyan(s.agent) + ' — ' + (s.label || s.topic || s.shortId);
+        return chalk.cyan(s.agent) + ' — ' + (sessionHeadline(s) || s.shortId);
     }
     if (row.linkStatus === 'unresolved') {
         return chalk.yellow(`owner ${row.owner ?? 'unknown'} (session not indexed here)`);

package/dist/commands/computer-sessions-picker.js

@@ -21,10 +21,11 @@ import { buildPreview } from './sessions-picker.js';
 import { createSessionsPickerCommand } from './sessions-picker-factory.js';
 import { runComputerSessions, printComputerSessionRows, buildComputerSessionRows, matchesComputerSessionRow, formatRowActions, } from '../lib/computer/sessions-list.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
+import { sessionHeadline } from '../lib/session/title.js';
 function rowLinkSummary(row) {
     if (row.linkStatus === 'linked' && row.linkedSession) {
         const s = row.linkedSession;
-        return chalk.cyan(s.agent) + ' — ' + (s.label || s.topic || s.shortId);
+        return chalk.cyan(s.agent) + ' — ' + (sessionHeadline(s) || s.shortId);
     }
     if (row.linkStatus === 'unresolved') {
         return chalk.yellow(`owner ${row.agent ?? 'unknown'} (session not indexed here)`);

package/dist/commands/cost.js

@@ -5,6 +5,7 @@ import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Register `agents insights cost` under the insights parent. */
 export function registerCostCommand(insightsCmd) {
     addHostOption(insightsCmd.command('cost'))
@@ -99,7 +100,7 @@ async function costAction(options) {
         for (const t of top) {
             const cost = formatUsd(t.costUsd).padStart(costW);
             const dur = t.durationMs > 0 ? formatDuration(t.durationMs) : '—';
-            const label = (t.meta.label || t.meta.topic || '(untitled)').replace(/\s+/g, ' ').trim();
+            const label = (sessionHeadline(t.meta) || '(untitled)').replace(/\s+/g, ' ').trim();
             const proj = showProject && t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
             const prefix = `  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} `;
             const suffix = proj + chalk.gray(`  ${dur}`);

package/dist/commands/fork.js

@@ -97,10 +97,12 @@ export async function runFork(sessionArg, options, deps = defaultDeps()) {
         return;
     }
     const digest = data?.preview ?? undefined;
-    // Most sessions have no explicit --name label; fall back to the auto-derived
-    // topic the rest of the CLI shows, not the raw short id (forkLabelFor is the
-    // shared 3-tier resolver, and preview's --json now carries `topic`).
-    const label = forkLabelFor({ label: source.label, topic: source.topic, shortId: source.shortId });
+    // Most sessions have no explicit --name label; fall back to the shared headline
+    // ladder the rest of the CLI shows, not the raw short id. Pass `source` whole
+    // rather than re-listing fields: an object literal that omits `generatedTitle`
+    // still type-checks (the key is optional) and would silently drop the
+    // daemon-generated title rung — the PHNX-3797 bug shape.
+    const label = forkLabelFor(source);
     const recap = buildForkRecap({
         agent: source.agent,
         label,

package/dist/commands/logs.js

@@ -29,6 +29,7 @@ import { listTasks } from '../lib/hosts/tasks.js';
 import { itemPicker } from '../lib/picker.js';
 import { stats, getLogsPath, rotate, } from '../lib/feed/events.js';
 import { addEventsReadOptions, runEventsCommand } from './events.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Compact one-line label used by both the picker and the non-TTY list. */
 function candidateLabel(c) {
     if (c.kind === 'task') {
@@ -40,7 +41,7 @@ function candidateLabel(c) {
     }
     const s = c.session;
     const ver = s.version ? chalk.gray(`@${s.version}`) : '';
-    const title = s.label || s.topic || '';
+    const title = sessionHeadline(s) || '';
     return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
 }
 /** Emit a host-dispatch task's log as JSON: `{ kind, task, log }`. */

package/dist/commands/sessions-backfill.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import { type ToolIndexCoverage } from '../lib/session/tool-index.js';
+import { type SessionTitleRunner } from '../lib/session/title.js';
 export interface ToolBackfillMachineResult {
     machine: string;
     indexedFiles: number;
@@ -61,5 +62,34 @@ export interface ResourceBackfillEnvelope {
  * resource_scan_ledger so reruns skip completed transcripts.
  */
 export declare function runResourceBackfill(options: ResourceBackfillOptions): Promise<ResourceBackfillEnvelope>;
+interface TitleBackfillOptions {
+    session?: string;
+    limit?: string;
+    refresh?: boolean;
+    json?: boolean;
+    /** The injectable model call (`SessionTitleRunner`); not a CLI flag — tests pass it. */
+    run?: SessionTitleRunner;
+}
+export interface TitleBackfillEnvelope {
+    schemaVersion: 1;
+    kind: 'titles-backfill';
+    generatedAt: string;
+    machine: string;
+    scanned: number;
+    cached: number;
+    generated: number;
+    failed: number;
+    titles: Array<{
+        id: string;
+        title: string;
+    }>;
+}
+/**
+ * Generate session headlines NOW instead of waiting for the daemon's sweep — the
+ * explicit-refresh half of PHNX-3797. Same code path the `session-title` service
+ * ticks, so there is one generator: this only changes when it runs, how many it
+ * does, and (with `--refresh`) whether an already-current title is regenerated.
+ */
+export declare function runTitlesBackfill(options: TitleBackfillOptions): Promise<TitleBackfillEnvelope>;
 export declare function registerSessionsBackfillCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-backfill.js

@@ -7,6 +7,7 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
 import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { backfillResourceUsage } from '../lib/session/db.js';
+import { runSessionTitleTick, SESSION_TITLE_MAX_PER_TICK } from '../lib/session/title.js';
 const BACKFILL_REMOTE_TIMEOUT_MS = 10 * 60_000;
 function parseAgent(value) {
     if (!value)
@@ -181,6 +182,31 @@ export async function runResourceBackfill(options) {
         ...result,
     };
 }
+/**
+ * Generate session headlines NOW instead of waiting for the daemon's sweep — the
+ * explicit-refresh half of PHNX-3797. Same code path the `session-title` service
+ * ticks, so there is one generator: this only changes when it runs, how many it
+ * does, and (with `--refresh`) whether an already-current title is regenerated.
+ */
+export async function runTitlesBackfill(options) {
+    const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : undefined;
+    if (options.limit !== undefined && (!Number.isFinite(parsedLimit) || parsedLimit < 1)) {
+        throw new Error(`--limit must be a positive integer (got "${options.limit}")`);
+    }
+    const result = await runSessionTitleTick({
+        ...(options.session ? { id: options.session } : {}),
+        ...(options.run ? { run: options.run } : {}),
+        limit: parsedLimit ?? (options.session ? 1 : SESSION_TITLE_MAX_PER_TICK * 5),
+        force: Boolean(options.refresh),
+    });
+    return {
+        schemaVersion: 1,
+        kind: 'titles-backfill',
+        generatedAt: new Date().toISOString(),
+        machine: machineId(),
+        ...result,
+    };
+}
 export function registerSessionsBackfillCommand(sessionsCmd) {
     const backfill = sessionsCmd.command('backfill').description('Populate derived session data explicitly.');
     const tools = backfill.command('tools').description('Parse historical tool calls once into the local SQLite index.');
@@ -265,4 +291,50 @@ export function registerSessionsBackfillCommand(sessionsCmd) {
             process.exitCode = 1;
         }
     });
+    const titles = backfill
+        .command('titles')
+        .description('Generate the session-row headline (a short technical title) now, instead of waiting for the daemon.')
+        .option('--session <id>', 'Title one session (full or short id), even if it is old or already titled')
+        .option('--limit <n>', 'Maximum titles to generate in this run')
+        .option('--refresh', 'Regenerate even when the stored title still matches the session\'s first user message')
+        .option('--json', 'Emit the machine-readable result');
+    setHelpSections(titles, {
+        examples: `
+      # Catch this machine up now (the daemon otherwise does a couple every 2 min)
+      agents sessions backfill titles
+
+      # Re-title one session after correcting its first message
+      agents sessions backfill titles --session 6fc1db18 --refresh
+
+      # Machine-readable
+      agents sessions backfill titles --limit 20 --json
+    `,
+        notes: `
+      - The headline ladder is: \`/rename\` label > this generated title > the user's first message. It is never the agent's latest turn.
+      - One cheap-model call per session (\`--model cheap\`, read-only plan mode), generated ONCE and persisted; a session whose first message has not changed is a pure cache hit.
+      - Local-only: each box titles its own sessions and publishes them to the fleet via the session mirror, so a peer's rows already carry their titles.
+      - Best-effort. With no signed-in harness nothing is generated and rows keep showing the user's own words.
+    `,
+    });
+    titles.action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        try {
+            const envelope = await runTitlesBackfill(options);
+            if (options.json)
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            else {
+                console.log(`${envelope.machine}: generated ${envelope.generated.toLocaleString()} title${envelope.generated === 1 ? '' : 's'}; ` +
+                    `${envelope.cached.toLocaleString()} already current, ${envelope.scanned.toLocaleString()} scanned.`);
+                for (const { id, title } of envelope.titles)
+                    console.log(`  ${chalk.cyan(id.slice(0, 8))}  ${title}`);
+                if (envelope.failed > 0) {
+                    console.log(chalk.yellow(`${envelope.failed.toLocaleString()} session${envelope.failed === 1 ? '' : 's'} produced no usable title; rerun to retry.`));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/commands/sessions-inject.d.ts

@@ -43,9 +43,9 @@ export declare function matchInjectSelector(session: ActiveSession, token: strin
  * merges the parent `sessions` command's variadic `-D, --device <target...>` over
  * this subcommand's scalar `--device`, so a single `--device box` arrives as
  * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
- * several, since inject delivers to exactly one terminal (a fan-out spelling is a
- * user error, not a first-of-list guess).
+ * `host.startsWith` (PHNX-3688). Delegates to the shared
+ * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
+ * PHNX-3940) rather than re-implementing the array/scalar coercion here.
  */
 export declare function normalizeInjectDevice(value: string | string[] | undefined): string | undefined;
 /**

package/dist/commands/sessions-inject.js

@@ -19,6 +19,7 @@ import { sshExec, shellQuote } from '../lib/ssh-exec.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { setHelpSections } from '../lib/help.js';
+import { normalizeSingleDeviceOption } from './utils.js';
 /**
  * Whether an active session is the one `sessions inject <token>` means. Matches
  * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
@@ -47,19 +48,12 @@ export function matchInjectSelector(session, token) {
  * merges the parent `sessions` command's variadic `-D, --device <target...>` over
  * this subcommand's scalar `--device`, so a single `--device box` arrives as
  * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
- * several, since inject delivers to exactly one terminal (a fan-out spelling is a
- * user error, not a first-of-list guess).
+ * `host.startsWith` (PHNX-3688). Delegates to the shared
+ * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
+ * PHNX-3940) rather than re-implementing the array/scalar coercion here.
  */
 export function normalizeInjectDevice(value) {
-    const list = value == null ? [] : Array.isArray(value) ? value : [value];
-    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
-    if (hosts.length === 0)
-        return undefined;
-    if (hosts.length > 1) {
-        throw new Error(`sessions inject targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
-    }
-    return hosts[0];
+    return normalizeSingleDeviceOption(value, 'sessions inject');
 }
 /**
  * The `agents sessions inject` argv to re-run ON a device (its tmux panes live

package/dist/commands/sessions-picker.js

@@ -106,6 +106,7 @@ function sanitizeMeta(s) {
         topic: clean(s.topic),
         firstUserMessage: clean(s.firstUserMessage),
         label: clean(s.label),
+        generatedTitle: clean(s.generatedTitle),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),
         // A remote row's meta is peer-supplied JSON that parseRemoteList hands over
@@ -303,6 +304,7 @@ function previewCacheKey(session, remote) {
     // independently (label/ticket/PR/live scanner enrichment) also rides the key.
     return JSON.stringify([
         remote ?? '', remoteDigestState, session.id, fileStamp, session.lastActivity, session.label,
+        session.generatedTitle,
         session.topic, session.ticketId, session.prUrl, session.messageCount,
         session.tokenCount, session.model, session.todos, session.plan,
         session.recentDirectoriesTouched, session.skillsUsed,
@@ -489,13 +491,14 @@ function formatHeader(session, events) {
         line4.push(chalk.blue(linkUrl(session.prUrl, label)));
     }
     // Lead with the session's human title: `session.label` — an agent-generated
-    // name / `/rename`, else the `--name` launch handle. NOT `session.topic`: the
-    // topic is the derived first-prompt, already shown on the `Prompt:` line, so
-    // using it here too would print the same text twice. Unlabelled sessions keep
-    // that `Prompt:` line as their topic indicator and simply lead with the agent
-    // line. Wrapped to the pane (the header sits at column 0, full terminal width);
-    // nothing renders when there is no label.
-    const title = (session.label || '').trim();
+    // name / `/rename`, else the `--name` launch handle — else the daemon-generated
+    // title (PHNX-3797), which is a short technical NAME, not a restatement of the
+    // prompt. NOT `session.topic`: the topic is the derived first-prompt, already
+    // shown on the `Prompt:` line, so using it here too would print the same text
+    // twice. A session with neither keeps that `Prompt:` line as its topic
+    // indicator and simply leads with the agent line. Wrapped to the pane (the
+    // header sits at column 0, full terminal width).
+    const title = (session.label || session.generatedTitle || '').trim();
     const titleLines = title
         ? wrapToWidth(title, terminalWidth()).map(l => chalk.bold.white(l))
         : [];

package/dist/commands/sessions-resume.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 import { type SessionMeta } from '../lib/session/types.js';
 import { type Backend, type SurfaceItem, type EngineContext, type Packing } from '../lib/terminal/index.js';
 import { type StrictResumeOptions } from './resume.js';
@@ -24,6 +24,8 @@ export interface ResumeOptions extends StrictResumeOptions {
     runArgs?: string[];
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+/** Keep explicit parent options without replacing resume's own defaults. */
+export declare function resolveResumeOptions(cmd: Command, local: ResumeOptions): ResumeOptions;
 export declare function sessionsResumeAction(query: string | undefined, prompt: string | undefined, options: ResumeOptions): Promise<void>;
 /** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export declare function buildSelectedResumeArgs(id: string, prompt: string | undefined, options: ResumeOptions): string[];

package/dist/commands/sessions-resume.js

@@ -12,6 +12,7 @@
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
+import { Option } from 'commander';
 import { isAgentTmuxAlias } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
@@ -20,7 +21,7 @@ import { buildPreview } from './sessions-picker.js';
 import { formatPickerLabel, pickerColumnsFor, resolveSessionMetadataValue, parseAgentFilter, } from './sessions.js';
 import { sessionMatchesQuery } from './sessions-browser.js';
 import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, shellQuote, } from '../lib/terminal/index.js';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { isInteractiveTerminal, isPromptCancelled, normalizeSingleDeviceOption } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { confirm } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
@@ -30,6 +31,7 @@ import { sessionOriginDevice, sessionRecoveryDestinationMatches, sessionRecovery
 import { buildResumeRemoteArgs, runStrictResume, wantsStrictResume } from './resume.js';
 import { toRemotePortable } from '../lib/project-root.js';
 import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
@@ -45,6 +47,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
+        .addOption(new Option('--resume-device <alias>').hideHelp()
+        .argParser((value, previous = []) => [...previous, value]))
         .option('--device <alias>', 'Open on the session origin device over SSH; the device must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
@@ -104,9 +108,34 @@ export function registerSessionsResumeCommand(sessionsCmd) {
     `,
     });
     cmd.action(async (query, prompt, options) => {
-        await sessionsResumeAction(query, prompt, options);
+        await sessionsResumeAction(query, prompt, resolveResumeOptions(cmd, options));
     });
 }
+/** Flag names `sessions resume` declares that also exist on its parent `sessions`
+ *  command. Booleans and strings only — `device` collides too but needs its own
+ *  array-merge handling below, so it is not in this list. */
+const RESUME_PARENT_COLLISION_FLAGS = ['agent', 'all', 'teams', 'since', 'limit', 'local'];
+/** Keep explicit parent options without replacing resume's own defaults. */
+export function resolveResumeOptions(cmd, local) {
+    const parent = cmd.parent;
+    const { resumeDevice, ...resolved } = local;
+    const parentOpts = parent?.opts();
+    for (const key of RESUME_PARENT_COLLISION_FLAGS) {
+        if (parent?.getOptionValueSource(key) === 'cli') {
+            resolved[key] = parentOpts?.[key];
+        }
+    }
+    const rawDeviceTargets = [
+        ...(resumeDevice ?? []),
+        ...(local.device ? [local.device] : []),
+        ...(parentOpts?.device ?? []),
+        ...(parentOpts?.devices ?? []),
+    ];
+    if (rawDeviceTargets.length > 0) {
+        resolved.device = normalizeSingleDeviceOption(rawDeviceTargets, 'sessions resume');
+    }
+    return resolved;
+}
 export async function sessionsResumeAction(query, prompt, options) {
     if (options.attachOnly && (prompt !== undefined || options.agent || options.account || options.model || options.mode || options.interactive || options.headless || options.cwd || options.here)) {
         throw new Error('--attach-only cannot be combined with --agent, a follow-up prompt, or options that change the running session. Pass the session ID without filters.');
@@ -285,7 +314,7 @@ export async function sessionsResumeAction(query, prompt, options) {
         command: it.command,
         agent: it.session.agent || undefined,
         sessionId: it.session.id || undefined,
-        title: it.session.label || it.session.topic || undefined,
+        title: sessionHeadline(it.session),
     })), { backend, host: options.device, packing });
     let opened = 0;
     results.forEach((r, i) => {

package/dist/commands/sessions.js

@@ -37,6 +37,7 @@ import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
+import { sessionHeadline } from '../lib/session/title.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -351,6 +352,7 @@ export function buildSessionDescription(s) {
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.
+    // ladder-exempt: the compact --active preview BASE (a live snippet), not the row's headline title.
     const base = s.preview || s.label || s.topic || '';
     return cleanPreview([todo, base].filter(Boolean).join(' · '));
 }
@@ -759,22 +761,39 @@ export function renderActiveRowLines(s, indent, termW) {
     // Line 2: label/topic + checklist (the identity, no longer buried) then the
     // jump locator. Skipped entirely when there is nothing to say. desc may carry a
     // clickable project link, so it also goes through fitCell.
+    const contIndent = indent + ' '.repeat(ROW_ID_W);
     const desc = formatActiveRowDescription(s);
     const loc = locatorBadge(s);
-    if (!desc && !loc)
-        return lines;
-    const contIndent = indent + ' '.repeat(ROW_ID_W);
-    const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
-    const locCell = fitCell(loc, room2);
-    const locW = stringWidth(locCell);
-    const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
-    const descCell = chalk.white(fitCell(desc || '-', descRoom));
-    let line2 = contIndent + chalk.dim('└ ') + descCell;
-    if (locCell)
-        line2 += '  ' + locCell;
-    if (stringWidth(line2) > termW)
-        line2 = truncateToWidth(line2, termW);
-    lines.push(line2);
+    if (desc || loc) {
+        const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
+        const locCell = fitCell(loc, room2);
+        const locW = stringWidth(locCell);
+        const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
+        const descCell = chalk.white(fitCell(desc || '-', descRoom));
+        let line2 = contIndent + chalk.dim('└ ') + descCell;
+        if (locCell)
+            line2 += '  ' + locCell;
+        if (stringWidth(line2) > termW)
+            line2 = truncateToWidth(line2, termW);
+        lines.push(line2);
+    }
+    // Secondary line (PHNX-3797 owner feedback): surface the most important recent
+    // agent message when it is a pending QUESTION or a NEEDS-YOU block — the urgency
+    // a rolling activity preview buries. Plain `activity` is already the preview on
+    // line 2, so it earns no extra line here; the full ranked message still rides
+    // the JSON/mirror feed for AGI EXT via `s.importantMessage`.
+    const important = s.importantMessage;
+    if (important && (important.kind === 'question' || important.kind === 'needs_you')) {
+        const glyph = important.kind === 'question' ? '? ' : '! ';
+        const room3 = Math.max(0, termW - stringWidth(contIndent) - 2 - glyph.length);
+        const msgCell = fitCell(cleanPreview(important.text), room3);
+        if (msgCell) {
+            let line3 = contIndent + chalk.dim(glyph + msgCell);
+            if (stringWidth(line3) > termW)
+                line3 = truncateToWidth(line3, termW);
+            lines.push(line3);
+        }
+    }
     return lines;
 }
 /** Render a single agent-session row inside an already-printed group header. */
@@ -2200,7 +2219,7 @@ export function printToolSearch(envelope) {
             ? truncate(sanitizeForTerminal(session.machine).replace(/\s+/g, ' '), 80)
             : '';
         const machine = machineName ? ` @ ${machineName}` : '';
-        const rawHeading = session.label || session.topic || session.project || session.shortId;
+        const rawHeading = sessionHeadline(session) || session.project || session.shortId;
         const heading = truncate(sanitizeForTerminal(rawHeading).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 20));
         console.log(`${chalk.cyan(session.shortId)}${chalk.gray(machine)}  ${heading}`);
         for (const call of session.calls) {
@@ -3374,7 +3393,7 @@ function printTeamsView(pool, liveIndex, hiddenUnmanaged = 0) {
     // degradation the --active teams rows use (active.ts resolveOrchestratorLabels).
     const labelById = new Map();
     for (const s of pool) {
-        const label = s.label || s.topic;
+        const label = sessionHeadline(s);
         if (label)
             labelById.set(s.id, cleanPreview(label));
     }
@@ -3504,7 +3523,7 @@ function renderArchivedSession(session, mode, options = {}) {
     const shown = sessionDisplayAgent(session);
     const agentColor = colorAgent(shown);
     const absTime = formatAbsoluteTime(session.timestamp);
-    const title = session.label || session.topic;
+    const title = sessionHeadline(session);
     console.log('');
     if (title)
         console.log(chalk.bold.white(title));
@@ -3562,9 +3581,10 @@ async function renderSession(session, mode, filters, options = {}) {
         const modelStr = stats.models.length > 0 ? chalk.yellow(`  ${stats.models.join(', ')}`) : '';
         const branchStr = session.gitBranch ? chalk.gray(` (${session.gitBranch})`) : '';
         const absTime = formatAbsoluteTime(session.timestamp);
-        // Auto-inferred title headline (user /rename > Claude ai-title > first-prompt
-        // topic) — the fastest way to recognize which task this session is.
-        const title = session.label || session.topic;
+        // Auto-inferred title headline (user /rename > Claude ai-title >
+        // daemon-generated title > first-prompt topic) — the fastest way to
+        // recognize which task this session is.
+        const title = sessionHeadline(session);
         if (title) {
             const badges = signalBadges(metaSignals(session));
             console.log(chalk.bold.white(title) + (badges ? '  ' + badges : ''));
@@ -4456,7 +4476,7 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
             spinner.stop();
             console.error(chalk.red(`Multiple sessions match "${query}":`));
             for (const m of queryMatches.slice(0, 10)) {
-                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
+                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${sessionHeadline(m) ?? ''}`));
             }
             console.error(chalk.gray(ambiguityHint(byId, completeId)));
             process.exit(1);
@@ -4613,7 +4633,7 @@ async function renderOneSession(query, mode, scope) {
                 spinner.stop();
                 console.error(chalk.red(`Multiple sessions match "${query}":`));
                 for (const match of queryMatches.slice(0, 10)) {
-                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${match.label ?? match.topic ?? ''}`));
+                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${sessionHeadline(match) ?? ''}`));
                 }
                 console.error(chalk.gray(ambiguityHint(byId, completeId)));
                 process.exit(1);
@@ -5067,7 +5087,7 @@ export async function resolveSessionMetadata(selector, scope, deps = { gatherRem
         for (const candidate of outcome.candidates) {
             const session = candidate.hits[0].session;
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
-            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${session.label ?? session.topic ?? ''}`));
+            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${sessionHeadline(session) ?? ''}`));
         }
         console.error(chalk.gray(looksLikeSessionId(selector) ? 'Pass a longer ID to narrow it down.' : 'Narrow the keywords to one session.'));
         process.exit(1);
@@ -5107,7 +5127,7 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
         console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
         for (const candidate of candidates) {
             const s = candidate.hits[0].session;
-            const label = s.label ?? s.topic ?? '';
+            const label = sessionHeadline(s) ?? '';
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
             console.error(chalk.cyan(`  ${s.shortId}  ${s.id}`) + chalk.gray(`  ${machines}  ${s.agent}${s.version ? ` ${s.version}` : ''}  ${label}`));
         }