@phnx-labs/agents-cli 1.20.28 → 1.20.30

package/dist/lib/secrets/remote.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { type SshExecResult } from '../ssh-exec.js';
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export declare function resolveSshTarget(nameOrAlias: string): Promise<string>;
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export declare function parseHostsOption(opts: {
+    host?: string;
+    hosts?: string;
+}): string[];
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export declare function splitBundleRef(ref: string): {
+    bundle: string;
+    host?: string;
+};
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
+    tty?: boolean;
+    input?: string;
+}): SshExecResult;
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export declare function remoteResolveEnv(target: string, bundle: string): Promise<Record<string, string>>;

package/dist/lib/secrets/remote.js

@@ -0,0 +1,133 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { sshExec, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { resolveHost } from '../hosts/registry.js';
+import { sshTargetFor } from '../hosts/types.js';
+const REMOTE_TIMEOUT_MS = 30_000;
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export async function resolveSshTarget(nameOrAlias) {
+    const host = await resolveHost(nameOrAlias);
+    if (host)
+        return sshTargetFor(host);
+    assertValidSshTarget(nameOrAlias);
+    return nameOrAlias;
+}
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export function parseHostsOption(opts) {
+    const out = [];
+    const seen = new Set();
+    const push = (h) => {
+        const t = h.trim();
+        if (t && !seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    };
+    if (opts.host)
+        push(opts.host);
+    if (opts.hosts)
+        for (const h of opts.hosts.split(','))
+            push(h);
+    return out;
+}
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export function splitBundleRef(ref) {
+    const at = ref.indexOf('@');
+    if (at === -1)
+        return { bundle: ref };
+    const bundle = ref.slice(0, at);
+    const host = ref.slice(at + 1);
+    if (!bundle || !host) {
+        throw new Error(`Invalid remote bundle reference ${JSON.stringify(ref)}. Expected 'bundle@host'.`);
+    }
+    return { bundle, host };
+}
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export function remoteSecretsRaw(target, args, opts = {}) {
+    const inner = ['agents', 'secrets', ...args].map(shellQuote).join(' ');
+    const remoteCmd = `bash -lc ${shellQuote(inner)}`;
+    return sshExec(target, remoteCmd, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+        input: opts.input,
+        extraSshArgs: opts.tty ? ['-tt'] : undefined,
+    });
+}
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export async function remoteResolveEnv(target, bundle) {
+    assertValidSshTarget(target);
+    const exportCmd = `agents secrets export ${shellQuote(bundle)} --plaintext --format json`;
+    const res = sshExec(target, `bash -lc ${shellQuote(exportCmd)}`, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+    });
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+        throw new Error(`Failed to resolve '${bundle}' on ${target} (${why})${msg ? `: ${msg}` : ''}`);
+    }
+    // Tolerate login-shell banner noise on stdout: take the outer { … } object.
+    const raw = res.stdout;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    const jsonText = start >= 0 && end >= start ? raw.slice(start, end + 1) : raw.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        throw new Error(`Could not parse secrets JSON from '${bundle}' on ${target}. ` +
+            `Is the remote agents-cli new enough for 'secrets export --format json'?`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Unexpected payload resolving '${bundle}' on ${target}.`);
+    }
+    const env = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        env[k] = typeof v === 'string' ? v : String(v);
+    }
+    return env;
+}

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

@@ -1,3 +1,4 @@
+import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
 export interface ActiveSession {
@@ -12,6 +13,18 @@ export interface ActiveSession {
     label?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
+    /** Live preview: the latest turn (agent message or tool action), from the state engine. */
+    preview?: string;
+    /** Inferred activity: working / waiting_input / idle (from the transcript tail). */
+    activity?: SessionActivity;
+    /** Why the agent is waiting, when activity is waiting_input. */
+    awaitingReason?: AwaitingReason;
+    /** PR opened during the session. */
+    pr?: DetectedPr;
+    /** Worktree the session runs in. */
+    worktree?: DetectedWorktree;
+    /** Tracker ticket the session is tied to. */
+    ticket?: DetectedTicket;
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;

package/dist/lib/session/active.js

@@ -25,7 +25,10 @@ import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
 import { getTerminalsDir } from '../state.js';
 import { buildClaudeLabelMap } from './discover.js';
+import { latestSessionFileForCwd } from './db.js';
 import { extractSessionTopic } from './prompt.js';
+import { readSessionTail } from './tail.js';
+import { inferSessionState } from './state.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
 const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
@@ -42,6 +45,7 @@ const AGENT_CLI_NAMES = {
     gemini: 'gemini',
     'cursor-agent': 'cursor',
     opencode: 'opencode',
+    droid: 'droid',
 };
 function isPidAlive(pid) {
     if (!pid || pid < 1)
@@ -128,6 +132,66 @@ function classifyActivity(sessionFile) {
         return 'running';
     }
 }
+/**
+ * Locate the live transcript for an agent process. Claude files are keyed by
+ * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
+ * the newest indexed Codex session for the cwd instead.
+ */
+function findSessionFileForKind(kind, cwd, sessionId) {
+    if (!cwd)
+        return undefined;
+    if (kind === 'claude')
+        return findClaudeSessionFile(cwd, sessionId);
+    if (kind === 'codex')
+        return latestSessionFileForCwd('codex', cwd);
+    return undefined;
+}
+/** Recover the session UUID from a transcript filename (Claude `<uuid>.jsonl`, Codex `rollout-…-<uuid>.jsonl`). */
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+function sessionIdFromFile(file) {
+    if (!file)
+        return undefined;
+    return path.basename(file).match(UUID_RE)?.[0];
+}
+/** Infer live state from a session file's tail (Claude/Codex). Undefined when unreadable. */
+function computeLiveState(kind, sessionFile, cwd, pidAlive) {
+    if (!sessionFile)
+        return undefined;
+    const agent = kind === 'codex' ? 'codex' : 'claude';
+    const events = readSessionTail(sessionFile, agent);
+    if (events.length === 0)
+        return undefined;
+    let mtimeMs;
+    try {
+        mtimeMs = fs.statSync(sessionFile).mtimeMs;
+    }
+    catch { /* vanished between calls */ }
+    return inferSessionState(events, { cwd, pidAlive, mtimeMs, activeWindowMs: ACTIVE_MTIME_WINDOW_MS });
+}
+/** Map inferred activity onto the coarse ActiveStatus used by the renderer and counts. */
+function statusFromActivity(activity) {
+    return activity === 'working' ? 'running' : activity === 'waiting_input' ? 'input_required' : 'idle';
+}
+/**
+ * Fold a computed SessionState onto an active-session row: rich status +
+ * preview + PR/worktree/ticket badges. With no state (unreadable/non-Claude/
+ * Codex file) it degrades to the mtime-only classification.
+ */
+function applyState(base, state, fallbackFile) {
+    if (!state)
+        return { ...base, status: classifyActivity(fallbackFile) };
+    return {
+        ...base,
+        status: statusFromActivity(state.activity),
+        activity: state.activity,
+        awaitingReason: state.awaitingReason,
+        // Prefer the live preview (latest turn); keep the first-prompt topic as a fallback.
+        preview: state.preview ?? base.preview,
+        pr: state.pr,
+        worktree: state.worktree,
+        ticket: state.ticket,
+    };
+}
 /**
  * Extract the first user message's content from a Claude JSONL file.
  * Reads only the first ~50 lines for speed, since the user message is
@@ -207,24 +271,22 @@ export async function listTeamsActive() {
     const running = await mgr.listRunning();
     return running.map((a) => {
         const sessionId = a.parentSessionId ?? a.remoteSessionId ?? undefined;
-        const sessionFile = a.agentType === 'claude' && a.cwd
-            ? findClaudeSessionFile(a.cwd, sessionId ?? undefined)
-            : undefined;
+        const sessionFile = findSessionFileForKind(a.agentType, a.cwd ?? undefined, sessionId ?? undefined);
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
-        return {
+        const state = computeLiveState(a.agentType, sessionFile, a.cwd ?? undefined, a.pid ? isPidAlive(a.pid) : true);
+        return applyState({
             context: 'teams',
             kind: a.agentType,
             pid: a.pid ?? undefined,
-            sessionId,
+            sessionId: sessionId ?? sessionIdFromFile(sessionFile),
             cwd: a.cwd ?? undefined,
             label: a.name ?? undefined,
             topic,
             sessionFile,
             startedAtMs: a.startedAt.getTime(),
-            status: classifyActivity(sessionFile),
             teamName: a.taskName,
             agentId: a.agentId,
-        };
+        }, state, sessionFile);
     });
 }
 /** Live editor-terminal agents across every IDE window. */
@@ -240,27 +302,25 @@ export async function listTerminalsActive() {
     // Build label map from Claude's sessions/*.json for /rename support
     const labelMap = buildClaudeLabelMap();
     return entries.map((t) => {
-        const sessionFile = t.kind === 'claude' && t.cwd
-            ? findClaudeSessionFile(t.cwd, t.sessionId)
-            : undefined;
+        const sessionFile = findSessionFileForKind(t.kind, t.cwd ?? undefined, t.sessionId);
         // Prefer label from live terminal, fall back to Claude's session label
         const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
         // Extract topic from session file (first meaningful user message)
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
-        return {
+        const state = computeLiveState(t.kind, sessionFile, t.cwd ?? undefined, isPidAlive(t.pid));
+        return applyState({
             context: 'terminal',
             kind: t.kind,
             host: detectHost(t.pid, procByPid),
             pid: t.pid,
-            sessionId: t.sessionId,
+            sessionId: t.sessionId ?? sessionIdFromFile(sessionFile),
             cwd: t.cwd ?? undefined,
             label,
             topic,
             sessionFile,
             startedAtMs: t.startedAtMs,
-            status: classifyActivity(sessionFile),
             windowId: t.windowId,
-        };
+        }, state, sessionFile);
     });
 }
 /** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */
@@ -439,20 +499,21 @@ export async function listUnattributedActive(attributed) {
     for (let i = 0; i < candidates.length; i++) {
         const { pid, kind } = candidates[i];
         const cwd = cwds[i];
-        const sessionFile = kind === 'claude' && cwd ? findClaudeSessionFile(cwd) : undefined;
+        const sessionFile = findSessionFileForKind(kind, cwd);
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const host = detectHost(pid, procByPid);
         const context = host && UI_HOSTS.has(host) ? 'terminal' : 'headless';
-        out.push({
+        const state = computeLiveState(kind, sessionFile, cwd, true);
+        out.push(applyState({
             context,
             kind,
             host,
             pid,
             cwd,
+            sessionId: sessionIdFromFile(sessionFile),
             topic,
             sessionFile,
-            status: classifyActivity(sessionFile),
-        });
+        }, state, sessionFile));
     }
     return out;
 }

package/dist/lib/session/cloud.js

@@ -44,6 +44,8 @@ function agentToFormat(agent) {
         return 'codex';
     if (agent === 'rush')
         return 'rush';
+    if (agent === 'droid')
+        return 'droid';
     return null;
 }
 export function assertContained(candidate, rootDir) {

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

@@ -30,11 +30,16 @@ export interface SessionRow {
     file_size: number | null;
     scanned_at: number | null;
     is_team_origin: number;
+    pr_url: string | null;
+    pr_number: number | null;
+    worktree_slug: string | null;
+    ticket_id: string | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
     fileMtimeMs: number;
     fileSize: number;
+    scannedAt?: number;
 }
 /** Filter and pagination options for querying the sessions table. */
 export interface QueryOptions {
@@ -132,6 +137,13 @@ export declare function syncLabels(labelMap: Map<string, string | null>): number
  * Returns the number of rows updated.
  */
 export declare function syncTopics(topicMap: Map<string, string>): number;
+/**
+ * Newest indexed session file for an agent working in `cwd`. Lets the live
+ * `--active` scanner locate a Codex transcript (whose files are date-partitioned,
+ * not cwd-keyed like Claude's) by reusing the index. Returns undefined if the
+ * session hasn't been scanned yet — the caller degrades to no live state.
+ */
+export declare function latestSessionFileForCwd(agent: SessionAgentId, cwd: string): string | undefined;
 /** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 6;
+const SCHEMA_VERSION = 7;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -59,7 +59,11 @@ CREATE TABLE IF NOT EXISTS sessions (
   file_mtime_ms INTEGER,
   file_size INTEGER,
   scanned_at INTEGER,
-  is_team_origin INTEGER DEFAULT 0
+  is_team_origin INTEGER DEFAULT 0,
+  pr_url TEXT,
+  pr_number INTEGER,
+  worktree_slug TEXT,
+  ticket_id TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -157,6 +161,21 @@ function migrateSchema(db, fromVersion) {
         }
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 7) {
+        // v6 → v7: the session-state engine now persists durable signals (PR opened,
+        // worktree, tracker ticket) at scan time. Add the columns and force a full
+        // rescan so every existing session gets them populated.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'pr_url'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN pr_url TEXT`);
+        if (!cols.some(c => c.name === 'pr_number'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN pr_number INTEGER`);
+        if (!cols.some(c => c.name === 'worktree_slug'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN worktree_slug TEXT`);
+        if (!cols.some(c => c.name === 'ticket_id'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN ticket_id TEXT`);
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -290,9 +309,9 @@ export function getDBPath() {
 export function getScanStampByPath(filePath) {
     const db = getDB();
     const row = db
-        .prepare(`SELECT file_mtime_ms, file_size FROM scan_ledger WHERE file_path = ? LIMIT 1`)
+        .prepare(`SELECT file_mtime_ms, file_size, scanned_at FROM scan_ledger WHERE file_path = ? LIMIT 1`)
         .get(canonicalLedgerKey(filePath));
-    return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size } : null;
+    return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, scannedAt: row.scanned_at } : null;
 }
 /**
  * Bulk-load the stamp ledger for a set of file paths in a single SQL query.
@@ -324,13 +343,13 @@ export function getScanStampsForPaths(filePaths) {
         const placeholders = chunk.map(() => '?').join(',');
         const rows = db
             .prepare(`
-        SELECT file_path, file_mtime_ms, file_size
+        SELECT file_path, file_mtime_ms, file_size, scanned_at
         FROM scan_ledger
         WHERE file_path IN (${placeholders})
       `)
             .all(...chunk);
         for (const row of rows) {
-            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size };
+            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, scannedAt: row.scanned_at };
             for (const original of canonicalToOriginals.get(row.file_path) || []) {
                 result.set(original, stamp);
             }
@@ -367,12 +386,14 @@ const upsertSessionStmt = (db) => db.prepare(`
     id, short_id, agent, version, account, timestamp,
     project, cwd, git_branch, topic, label, message_count, token_count,
     cost_usd, duration_ms,
-    file_path, file_mtime_ms, file_size, scanned_at, is_team_origin
+    file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
+    pr_url, pr_number, worktree_slug, ticket_id
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @cost_usd, @duration_ms,
-    @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin
+    @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
+    @pr_url, @pr_number, @worktree_slug, @ticket_id
   )
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
@@ -393,7 +414,11 @@ const upsertSessionStmt = (db) => db.prepare(`
     file_mtime_ms = excluded.file_mtime_ms,
     file_size = excluded.file_size,
     scanned_at = excluded.scanned_at,
-    is_team_origin = excluded.is_team_origin
+    is_team_origin = excluded.is_team_origin,
+    pr_url = excluded.pr_url,
+    pr_number = excluded.pr_number,
+    worktree_slug = excluded.worktree_slug,
+    ticket_id = excluded.ticket_id
 `);
 const deleteTextStmt = (db) => db.prepare(`DELETE FROM session_text WHERE session_id = ?`);
 const insertTextStmt = (db) => db.prepare(`INSERT INTO session_text (session_id, label, topic, project, content) VALUES (?, ?, ?, ?, ?)`);
@@ -436,6 +461,10 @@ export function upsertSession(meta, content, scan) {
         file_size: scan?.fileSize ?? null,
         scanned_at: Date.now(),
         is_team_origin: meta.isTeamOrigin ? 1 : 0,
+        pr_url: meta.prUrl ?? null,
+        pr_number: meta.prNumber ?? null,
+        worktree_slug: meta.worktreeSlug ?? null,
+        ticket_id: meta.ticketId ?? null,
     };
     const txn = db.transaction(() => {
         upsert.run(row);
@@ -511,6 +540,10 @@ export function upsertSessionsBatch(entries) {
                 file_size: scan?.fileSize ?? null,
                 scanned_at: now,
                 is_team_origin: meta.isTeamOrigin ? 1 : 0,
+                pr_url: meta.prUrl ?? null,
+                pr_number: meta.prNumber ?? null,
+                worktree_slug: meta.worktreeSlug ?? null,
+                ticket_id: meta.ticketId ?? null,
             });
             delText.run(meta.id);
             insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
@@ -621,8 +654,32 @@ function rowToMeta(row) {
         topic: row.topic ?? undefined,
         label: row.label ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
+        prUrl: row.pr_url ?? undefined,
+        prNumber: row.pr_number ?? undefined,
+        worktreeSlug: row.worktree_slug ?? undefined,
+        ticketId: row.ticket_id ?? undefined,
     };
 }
+/**
+ * Newest indexed session file for an agent working in `cwd`. Lets the live
+ * `--active` scanner locate a Codex transcript (whose files are date-partitioned,
+ * not cwd-keyed like Claude's) by reusing the index. Returns undefined if the
+ * session hasn't been scanned yet — the caller degrades to no live state.
+ */
+export function latestSessionFileForCwd(agent, cwd) {
+    if (!cwd)
+        return undefined;
+    let normalized = cwd;
+    try {
+        normalized = fs.realpathSync(cwd);
+    }
+    catch { /* use as-is */ }
+    const db = getDB();
+    const row = db
+        .prepare(`SELECT file_path FROM sessions WHERE agent = ? AND cwd = ? ORDER BY timestamp DESC LIMIT 1`)
+        .get(agent, normalized);
+    return row?.file_path;
+}
 /** Build a parameterized WHERE clause from query options. */
 function buildSessionWhere(options) {
     const where = [];

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

@@ -7,6 +7,7 @@
  * subsequent queries are served entirely from the cache.
  */
 import type { SessionAgentId, SessionMeta } from './types.js';
+import { type ScanStamp } from './db.js';
 /** Options controlling which sessions to discover and how to report progress. */
 export interface DiscoverOptions {
     agent?: SessionAgentId;
@@ -56,6 +57,11 @@ interface ClaudeSessionScan {
     entrypoint?: string;
     /** Concatenated user message text, ready to hand to FTS5. */
     contentText?: string;
+    /** Durable state signals persisted to the index by the session-state engine. */
+    prUrl?: string;
+    prNumber?: number;
+    worktreeSlug?: string;
+    ticketId?: string;
 }
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
@@ -85,6 +91,7 @@ export declare function resolveSessionById(sessions: SessionMeta[], idQuery: str
  * preserving the existing SessionMeta[] contract so sessions.ts is unchanged.
  */
 export declare function searchContentIndex(sessions: SessionMeta[], query: string): Map<string, SessionMeta>;
+export declare function shouldDeferRecentAppend(prev: ScanStamp, current: ScanStamp, nowMs: number, debounceMs?: number): boolean;
 /**
  * Collect all directories to scan for an agent's sessions. Deduplicates by
  * realpath to avoid double-counting symlinked version homes.