@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/lib/devices/doctor-findings.js

@@ -27,7 +27,7 @@
  *              fleet-resource-gap · hook-runtime-visibility-unavailable · orphan · duplicate-hook ·
  *              duplicate-hook-drift · host-cli-missing · host-cli-invalid ·
  *              rc-secret-export · env-secret-export · auth-bundle-wrong-backend · exec-policy · stale-cli ·
- *              binary-shadow.
+ *              binary-shadow · leaked-daemon.
  *   (RUSH-2162 moved never-synced and duplicate-hook-drift to WARNING: both are
  *   stale-sync states one `agents sync` resolves, not "needs you now".)
  *
@@ -38,6 +38,7 @@
  * format, so the layout is unit-tested against fixtures with no live fleet.
  */
 import chalk from 'chalk';
+import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, supportsAccountInspection } from '../agents.js';
 import { blocksLocalScripts } from '../platform/winpath.js';
 import { loginHint } from '../signin-badge.js';
@@ -126,6 +127,7 @@ export const ALL_FINDING_KINDS = [
     'stale-cli',
     'binary-shadow', // another agents binary on PATH or in a well-known dir shadows the running copy
     'owner-sink-unreachable', // the feed/notify owner-delivery lane can't reach the owner from this box
+    'leaked-daemon', // a `__daemon-run` process no owner record names (not the unit main PID, not daemon.pid)
 ];
 /**
  * The severity each kind is emitted with - the SINGLE source of truth, read by
@@ -174,6 +176,12 @@ export const FINDING_SEVERITY = {
     'ssh-key-enrollment': 'critical',
     'stale-cli': 'warning',
     'binary-shadow': 'warning',
+    // A stray `__daemon-run` under its own (usually temp) HOME: it shares nothing
+    // with this install's state, so it cannot double-fire the real box's work —
+    // but it is a leak nothing owns and it outlives whatever launched it (W4,
+    // PHNX-3736). A human reads its HOME/start time and kills it; nothing is
+    // blocked right now.
+    'leaked-daemon': 'warning',
 };
 function agentName(agent) {
     return AGENT_NAMES[agent] || agent;
@@ -305,6 +313,11 @@ export function remediationFor(finding) {
             return 'upgrade';
         case 'binary-shadow':
             return 'remove or repoint the shadowing agents install(s)';
+        case 'leaked-daemon':
+            // The builder emits the concrete `kill <pid>` — the pid is a property of
+            // the row it builds, not of anything remediationFor can see. This is the
+            // shape only, for a kind constructed through finding() by a future caller.
+            return 'kill <pid>';
         case 'owner-sink-unreachable':
             // The lane delivers over the rush-backed owner channel, which needs rush on
             // PATH AND a usable session in THIS context. Non-interactive shells miss a
@@ -579,6 +592,24 @@ export function buildLocalFindings(input) {
                 : `${shadows.length} agents binaries may shadow the running copy (incl. ${examples})`,
         }));
     }
+    // Leaked daemons (warning) — a `__daemon-run` no owner record names. One row
+    // per pid: the remediation is pid-specific, and the HOME + start time are
+    // what let the operator tell a leaked test fixture from something they meant
+    // to run before they kill it (W4, PHNX-3736). Built directly, not through
+    // finding(): the remediation carries this row's own pid.
+    for (const d of input.leakedDaemons ?? []) {
+        const home = d.home ?? 'unknown HOME';
+        const started = d.startedAt ? `, started ${d.startedAt}` : '';
+        // The launch entry names WHICH install leaked the daemon — part of what
+        // the operator judges before killing. Only a real path: for a stand-in
+        // (`node -e '<code>' __daemon-run`) the token is the code blob.
+        const entry = d.entry && path.isAbsolute(d.entry) ? ` · ${d.entry}` : '';
+        out.push({
+            severity: FINDING_SEVERITY['leaked-daemon'], kind: 'leaked-daemon', device,
+            message: `stray agents daemon (pid ${d.pid}) no unit or pid file owns — HOME=${home}${started}${entry}`,
+            remediation: `kill ${d.pid}`,
+        });
+    }
     return collapseAcrossVersions(out, new Set(input.isolatedVersions ?? []));
 }
 /**

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
@@ -2256,12 +2257,73 @@ 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 = {};
+    if (fs.existsSync(configPath)) {
+        tomlConfig = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
+        tomlConfig.features = {};
+    }
+    // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
+    // an unrecognized key that triggers a deprecation error and is ignored).
+    const features = tomlConfig.features;
+    delete features.codex_hooks;
+    features.hooks = true;
+    // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
+    // exactly as Codex resolves it (the absolute CODEX_HOME path), the
+    // snake_case event label, and the per-event group/handler indices — which
+    // must match Codex's parse order, so we iterate the just-written
+    // hooksFile structure in array order.
+    if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
+        tomlConfig.hooks = {};
+    }
+    const hooksTable = tomlConfig.hooks;
+    const existingState = hooksTable.state && typeof hooksTable.state === 'object'
+        ? hooksTable.state
+        : {};
+    const hookState = {};
+    for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
+        const eventKeyLabel = CODEX_EVENT_KEY_LABELS[event];
+        if (!eventKeyLabel)
+            continue;
+        eventGroups.forEach((group, groupIdx) => {
+            if (!group.hooks)
+                return;
+            group.hooks.forEach((handler, handlerIdx) => {
+                if (handler.type !== 'command')
+                    return;
+                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 entry = { trusted_hash: trustedHash };
+                if (keys.some((key) => existingState[key]?.enabled === false)) {
+                    entry.enabled = false;
+                }
+                for (const key of keys)
+                    hookState[key] = entry;
+            });
+        });
+    }
+    // Carry forward trust state for any hooks we did not (re)register this
+    // pass — e.g. user-added hooks under a different command path.
+    for (const [key, entry] of Object.entries(existingState)) {
+        if (!(key in hookState)) {
+            hookState[key] = entry;
+        }
+    }
+    hooksTable.state = hookState;
+    fs.writeFileSync(configPath, TOML.stringify(tomlConfig), 'utf-8');
+}
 function registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, '.codex');
     const hooksPath = path.join(configDir, 'hooks.json');
-    const configPath = path.join(configDir, 'config.toml');
     // Read existing hooks.json — must have top-level "hooks" wrapper key
     let hooksFile = { hooks: {} };
     if (fs.existsSync(hooksPath)) {
@@ -2373,66 +2435,7 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     // them, so an untrusted hook is silently dropped. We compute the same
     // trust hash Codex would and persist it under [hooks.state].
     try {
-        let tomlConfig = {};
-        if (fs.existsSync(configPath)) {
-            try {
-                tomlConfig = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
-            }
-            catch { /* start fresh if corrupt */ }
-        }
-        if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
-            tomlConfig.features = {};
-        }
-        // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
-        // an unrecognized key that triggers a deprecation error and is ignored).
-        const features = tomlConfig.features;
-        delete features.codex_hooks;
-        features.hooks = true;
-        // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
-        // exactly as Codex resolves it (the absolute CODEX_HOME path), the
-        // snake_case event label, and the per-event group/handler indices — which
-        // must match Codex's parse order, so we iterate the just-written
-        // hooksFile structure in array order.
-        if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
-            tomlConfig.hooks = {};
-        }
-        const hooksTable = tomlConfig.hooks;
-        const existingState = hooksTable.state && typeof hooksTable.state === 'object'
-            ? hooksTable.state
-            : {};
-        const hookState = {};
-        for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
-            const eventKeyLabel = CODEX_EVENT_KEY_LABELS[event];
-            if (!eventKeyLabel)
-                continue;
-            eventGroups.forEach((group, groupIdx) => {
-                if (!group.hooks)
-                    return;
-                group.hooks.forEach((handler, handlerIdx) => {
-                    if (handler.type !== 'command')
-                        return;
-                    const key = `${hooksPath}:${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) {
-                        entry.enabled = false;
-                    }
-                    hookState[key] = entry;
-                });
-            });
-        }
-        // Carry forward trust state for any hooks we did not (re)register this
-        // pass — e.g. user-added hooks under a different command path.
-        for (const [key, entry] of Object.entries(existingState)) {
-            if (!(key in hookState)) {
-                hookState[key] = entry;
-            }
-        }
-        hooksTable.state = hookState;
-        fs.writeFileSync(configPath, TOML.stringify(tomlConfig), 'utf-8');
+        trustCodexHooks(hooksPath);
     }
     catch (err) {
         errors.push(`Failed to update config.toml: ${err.message}`);
@@ -3283,10 +3286,13 @@ export async function installSessionTrackerHook(agent, version, home) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
     try {
+        const env = sessionTrackerInstallEnv(agent, version, home);
         await execFileAsync(invocation.command, invocation.args, {
-            env: sessionTrackerInstallEnv(agent, version, home),
+            env,
             encoding: 'utf8',
         });
+        if (agent === 'codex')
+            trustCodexHooks(path.join(env.HOME ?? os.homedir(), '.codex', 'hooks.json'));
         return { installed: true };
     }
     catch (err) {
@@ -3325,11 +3331,14 @@ export function installSessionTrackerHookSync(agent, version, home) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
     try {
+        const env = sessionTrackerInstallEnv(agent, version, home);
         execFileSync(invocation.command, invocation.args, {
-            env: sessionTrackerInstallEnv(agent, version, home),
+            env,
             stdio: ['ignore', 'pipe', 'pipe'],
             encoding: 'utf8',
         });
+        if (agent === 'codex')
+            trustCodexHooks(path.join(env.HOME ?? os.homedir(), '.codex', 'hooks.json'));
         return { installed: true };
     }
     catch (err) {
@@ -3339,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/models.js

@@ -13,7 +13,8 @@ import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { getVersionDir, getVersionHomePath, getBinaryPath } from './installations/versions.js';
 import { getModelsCachePath } from './state.js';
-import { agentConfigDirName } from './agents.js';
+import { agentConfigDirName, resolveOpenCodeXdgPath } from './agents.js';
+import { stripJsonComments } from './permissions-registry.js';
 import { resolveRunDefaults } from './run-defaults.js';
 import { getModelPricing } from './pricing/index.js';
 const CACHE_PATH = getModelsCachePath();
@@ -1014,6 +1015,12 @@ export function resolveConfiguredModel(agent, version, home) {
     const nativeModel = readNativeConfigModel(agent, version, home);
     if (nativeModel)
         return { model: nativeModel, source: 'config' };
+    // The agent's own persisted selection, for a runtime that stores one instead
+    // of flagging a catalog default. Ranks below `config` (an explicit setting
+    // wins) and above the catalog, whose `isDefault` OpenCode never sets.
+    const selected = readNativeSelectedModel(agent, version);
+    if (selected)
+        return { model: selected, source: 'cli-default' };
     const catalog = getModelCatalog(agent, version);
     if (catalog) {
         const flagged = catalog.models.find((m) => m.isDefault);
@@ -1022,15 +1029,79 @@ export function resolveConfiguredModel(agent, version, home) {
     return null;
 }
 /**
- * Best-effort read of the agent's own `model` from its native settings.json
+ * Where each agent keeps its OWN `model` setting, when that is not the
+ * `<configDir>/settings.json` every Claude-shaped harness uses.
+ *
+ * OpenCode reads `~/.config/opencode/opencode.{jsonc,json}` and puts `model` at
+ * its top level as `"<provider>/<model-id>"`. Its `~/.opencode/settings.json`
+ * DOES exist, but that is agents-cli's own plugin-enablement file, which
+ * OpenCode never reads a model from — so the default path found nothing and
+ * every OpenCode row rendered the placeholder `default`. Comments are stripped
+ * for BOTH spellings because OpenCode's loader accepts them in both, which is
+ * also how the MCP writer treats the same file (`format: 'opencode-jsonc'`).
+ */
+const NATIVE_MODEL_CONFIGS = {
+    opencode: {
+        paths: (home) => [
+            path.join(home, '.config', 'opencode', 'opencode.jsonc'),
+            path.join(home, '.config', 'opencode', 'opencode.json'),
+        ],
+        jsonc: true,
+    },
+};
+/**
+ * Best-effort read of the agent's own `model` from its native config
  * (e.g. `~/.agents/.history/versions/claude/<ver>/home/.claude/settings.json`).
  * A missing/malformed file is a fall-through, not an error.
  */
 function readNativeConfigModel(agent, version, home) {
+    const resolvedHome = home ?? getVersionHomePath(agent, version);
+    const native = NATIVE_MODEL_CONFIGS[agent];
+    const candidates = native?.paths(resolvedHome)
+        ?? [path.join(resolvedHome, agentConfigDirName(agent), 'settings.json')];
+    for (const configPath of candidates) {
+        try {
+            const raw = fs.readFileSync(configPath, 'utf8');
+            const parsed = JSON.parse(native?.jsonc ? stripJsonComments(raw) : raw);
+            if (typeof parsed.model === 'string' && parsed.model.trim() !== '')
+                return parsed.model;
+        }
+        catch {
+            /* absent or malformed — try the next spelling */
+        }
+    }
+    return null;
+}
+/**
+ * The model the agent's OWN runtime will start with, for a harness that persists
+ * its selection rather than flagging a catalog default.
+ *
+ * OpenCode is the case that needs it: it ships no default model, so its catalog
+ * has no `isDefault` and `agents view` fell through to the literal `default` —
+ * a placeholder, not something the user could act on. OpenCode instead records
+ * the model picked in its TUI to `$XDG_STATE_HOME/opencode/model.json` as
+ * `{ recent: [{ providerID, modelID }, …] }`, newest first, and reuses
+ * `recent[0]` for the next session. That entry is the real answer to "what model
+ * is this install on", rendered the same `<provider>/<model-id>` way OpenCode's
+ * own config spells it.
+ *
+ * Returns null for every other agent, and for OpenCode when nothing has been
+ * selected yet — the catalog fallback still applies.
+ */
+function readNativeSelectedModel(agent, version) {
+    if (agent !== 'opencode')
+        return null;
+    const statePath = resolveOpenCodeXdgPath(getVersionHomePath(agent, version), 'state', 'model.json');
+    if (!statePath)
+        return null;
     try {
-        const settingsPath = path.join(home ?? getVersionHomePath(agent, version), agentConfigDirName(agent), 'settings.json');
-        const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-        return typeof parsed.model === 'string' && parsed.model.trim() !== '' ? parsed.model : null;
+        const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        const current = parsed.recent?.[0];
+        const provider = typeof current?.providerID === 'string' ? current.providerID : '';
+        const model = typeof current?.modelID === 'string' ? current.modelID : '';
+        if (!model)
+            return null;
+        return provider ? `${provider}/${model}` : model;
     }
     catch {
         return null;

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;
 /**