@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/session/parse.js

@@ -9,6 +9,7 @@ import * as fs from 'fs';
 import { truncate } from '../format.js';
 import * as path from 'path';
 import Database from '../sqlite.js';
+import { isSyntheticUserMessage } from './prompt.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -156,9 +157,17 @@ export function parseSession(filePath, agent) {
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
-    // safely splat values into chalk/console output.
-    for (const e of events)
+    // safely splat values into chalk/console output. Same pass flags
+    // harness-injected `role=user` scaffolding (Claude `<bash-input>`/`<bash-stdout>`
+    // from `!`-prefix runs, `<system-reminder>`, etc.) as `_synthetic` so turn
+    // slicing and `--include user` count only genuine user intent — one place,
+    // every harness, instead of per-consumer regex.
+    for (const e of events) {
         sanitizeEvent(e);
+        if (e.type === 'message' && e.role === 'user' && isSyntheticUserMessage(e.content)) {
+            e._synthetic = true;
+        }
+    }
     return events;
 }
 /** Infer the agent type from a session file path using known directory conventions. */
@@ -1014,44 +1023,144 @@ export function parseAntigravity(dbPath) {
  * Messages have role (user/assistant) and metadata.
  * Parts contain the actual content: text, tool, reasoning, patch, step-start/finish.
  */
+/**
+ * Parse a Grok (xAI CLI) session into normalized events.
+ *
+ * A Grok session dir holds several files; the conversation transcript is
+ * `chat_history.jsonl`, one JSON object per line with a `type`:
+ *   - `system`       — the system prompt (skipped; not conversational)
+ *   - `user`         — `content` is an array of `{ type: 'text', text }` blocks
+ *   - `assistant`    — `content` is a string, plus a `tool_calls[]` array of
+ *                      `{ id, name, arguments }` (arguments is a JSON string)
+ *   - `reasoning`    — chain-of-thought; text (when present) lives in `summary`
+ *   - `tool_result`  — `{ tool_call_id, content }`, correlated back to the call
+ *
+ * The scanner records `summary.json` as the session's filePath (see
+ * `readGrokMeta` in discover.ts), so resolve `chat_history.jsonl` from the same
+ * dir; also accept being handed the transcript file directly. Per-line
+ * timestamps aren't stored, so every event carries the session's `created_at`
+ * (from summary.json), falling back to the transcript's mtime.
+ */
 export function parseGrok(filePath) {
-    // Grok sessions are rich (summary.json + events.jsonl + chat_history.jsonl + updates.jsonl)
-    // This is a minimal stub for now so grok appears in `agents sessions`.
-    // Full parser (with subagents, tool calls, etc.) can be expanded later.
+    const sessionDir = path.dirname(filePath);
+    const historyPath = filePath.endsWith('chat_history.jsonl')
+        ? filePath
+        : path.join(sessionDir, 'chat_history.jsonl');
+    if (!fs.existsSync(historyPath))
+        return [];
+    let timestamp;
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        // If it's a summary.json, create a basic event
-        if (filePath.endsWith('summary.json')) {
-            const summary = JSON.parse(content);
-            return [{
-                    timestamp: summary.created_at || new Date().toISOString(),
-                    type: 'session_start',
-                    content: summary.session_summary || 'Grok session',
-                    agent: 'grok',
-                    metadata: { sessionId: summary.id, cwd: summary.cwd },
-                }];
+        const summaryPath = filePath.endsWith('summary.json')
+            ? filePath
+            : path.join(sessionDir, 'summary.json');
+        if (fs.existsSync(summaryPath)) {
+            const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf-8'));
+            if (typeof summary?.created_at === 'string')
+                timestamp = summary.created_at;
         }
-        // For JSONL files (events, chat_history, updates), return basic parsed lines
-        if (filePath.endsWith('.jsonl')) {
-            const lines = content.trim().split('\n').filter(Boolean);
-            return lines.slice(0, 50).map((line, i) => {
-                try {
-                    const obj = JSON.parse(line);
-                    return {
-                        timestamp: obj.timestamp || obj.ts || new Date().toISOString(),
-                        type: obj.type || obj.method || 'grok_event',
-                        content: typeof obj.content === 'string' ? obj.content : JSON.stringify(obj).slice(0, 200),
-                        agent: 'grok',
-                    };
+    }
+    catch { /* fall back to mtime below */ }
+    if (!timestamp) {
+        let mtime = null;
+        try {
+            mtime = fs.statSync(historyPath).mtime;
+        }
+        catch {
+            mtime = null;
+        }
+        timestamp = (mtime ?? new Date()).toISOString();
+    }
+    const content = safeReadSessionFile(historyPath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    const toolCallMap = new Map();
+    // Grok text is either a plain string (assistant) or an array of typed blocks
+    // (user: `{ type: 'text', text }`; reasoning summary: `{ text | summary_text }`).
+    const extractText = (raw) => {
+        if (typeof raw === 'string')
+            return raw.trim();
+        if (Array.isArray(raw)) {
+            return raw
+                .map((part) => typeof part?.text === 'string'
+                ? part.text
+                : typeof part?.summary_text === 'string'
+                    ? part.summary_text
+                    : '')
+                .join('')
+                .trim();
+        }
+        return '';
+    };
+    for (const line of lines) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = msg?.type;
+        if (type === 'user') {
+            const text = extractText(msg.content);
+            if (text)
+                events.push({ type: 'message', agent: 'grok', timestamp, role: 'user', content: text });
+        }
+        else if (type === 'assistant') {
+            const text = extractText(msg.content);
+            if (text)
+                events.push({ type: 'message', agent: 'grok', timestamp, role: 'assistant', content: text });
+            const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+            for (const call of calls) {
+                const toolName = typeof call?.name === 'string' ? call.name : 'unknown';
+                let args = {};
+                if (call?.arguments && typeof call.arguments === 'object') {
+                    args = call.arguments;
                 }
-                catch {
-                    return { timestamp: new Date().toISOString(), type: 'raw', content: line.slice(0, 200), agent: 'grok' };
+                else if (typeof call?.arguments === 'string') {
+                    try {
+                        args = JSON.parse(call.arguments);
+                    }
+                    catch {
+                        args = { _raw: call.arguments };
+                    }
                 }
+                if (typeof call?.id === 'string')
+                    toolCallMap.set(call.id, toolName);
+                events.push({
+                    type: 'tool_use',
+                    agent: 'grok',
+                    timestamp,
+                    tool: toolName,
+                    args,
+                    path: args.path || args.file_path || undefined,
+                    command: typeof args.command === 'string' ? args.command : undefined,
+                });
+            }
+        }
+        else if (type === 'reasoning') {
+            const text = extractText(msg.summary);
+            if (text)
+                events.push({ type: 'thinking', agent: 'grok', timestamp, content: text });
+        }
+        else if (type === 'tool_result') {
+            const callId = typeof msg.tool_call_id === 'string' ? msg.tool_call_id : undefined;
+            const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
+            const output = typeof msg.content === 'string' ? msg.content : extractText(msg.content);
+            const isError = typeof output === 'string' && output.startsWith('Error:');
+            events.push({
+                type: isError ? 'error' : 'tool_result',
+                agent: 'grok',
+                timestamp,
+                tool: toolName,
+                success: !isError,
+                output: output.length > 500 ? output.slice(0, 497) + '...' : output,
             });
+            if (callId)
+                toolCallMap.delete(callId);
         }
+        // `system` lines are the system prompt — intentionally skipped.
     }
-    catch { }
-    return [];
+    return events;
 }
 export function parseOpenCode(filePath) {
     const [dbPath, sessionId] = filePath.split('#');

package/dist/lib/session/pid-registry.d.ts

@@ -4,6 +4,23 @@ export interface PidSessionEntry {
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;
+    /**
+     * The launch id minted by `ag run` and exported to the child as
+     * `AGENT_LAUNCH_ID`. The agent's SessionStart hook records the SAME id in its
+     * own state file (`terminals/sessions/<pid>.json`, `launch_id`), so the two
+     * records reconcile by this key even when the hook runs under a DIFFERENT pid
+     * (tmux pane leaf, cmd.exe wrapper) — see resolveHookSessionId in
+     * session/hook-sessions.ts. This
+     * is how a non-Claude launch (whose id we don't know at spawn) gets an exact
+     * session id at listing time instead of the newest-jsonl heuristic.
+     */
+    launchId?: string;
+    /**
+     * `AGENT_TERMINAL_ID` when the launch inherited one (a Factory VS Code tab).
+     * A secondary join key to the hook's `terminal_id`, for agents the extension
+     * spawned. Best-effort — undefined outside the extension.
+     */
+    terminalId?: string;
     /**
      * `$TMUX_PANE` at launch — stored for diagnostics and possible future
      * disambiguation. NOT currently consulted on read: the listing path keys
@@ -18,5 +35,20 @@ export declare function extractSessionIdArg(args: string[]): string | undefined;
 export declare function writePidSessionEntry(entry: PidSessionEntry): void;
 /** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
 export declare function readPidSessionEntry(pid: number): PidSessionEntry | undefined;
-/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
-export declare function prunePidSessionRegistry(isAlive: (pid: number) => boolean): void;
+/**
+ * Every recorded launch, one entry per live-or-dead pid. Used to index launches
+ * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
+ * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
+ * the caller filters to live pids. Best-effort: unreadable/corrupt files are
+ * skipped, a missing dir yields `[]`.
+ */
+export declare function listPidSessionEntries(): PidSessionEntry[];
+/**
+ * Remove entries whose pid is no longer alive. Best-effort housekeeping.
+ *
+ * `isAlive` receives the entry's recorded `startedAtMs` so it can reject a pid
+ * that a newer process recycled (a "zombie" registry entry), not just one that
+ * no longer exists. An unreadable/corrupt entry falls back to the pid-only
+ * check.
+ */
+export declare function prunePidSessionRegistry(isAlive: (pid: number, startedAtMs?: number) => boolean): void;

package/dist/lib/session/pid-registry.js

@@ -81,7 +81,43 @@ export function readPidSessionEntry(pid) {
     }
     return undefined;
 }
-/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
+/**
+ * Every recorded launch, one entry per live-or-dead pid. Used to index launches
+ * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
+ * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
+ * the caller filters to live pids. Best-effort: unreadable/corrupt files are
+ * skipped, a missing dir yields `[]`.
+ */
+export function listPidSessionEntries() {
+    let files;
+    try {
+        files = fs.readdirSync(pidRegistryDir()).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(pidRegistryDir(), f), 'utf8'));
+            if (parsed && typeof parsed === 'object' && typeof parsed.pid === 'number') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            /* raced with a writer/pruner, or corrupt — skip */
+        }
+    }
+    return out;
+}
+/**
+ * Remove entries whose pid is no longer alive. Best-effort housekeeping.
+ *
+ * `isAlive` receives the entry's recorded `startedAtMs` so it can reject a pid
+ * that a newer process recycled (a "zombie" registry entry), not just one that
+ * no longer exists. An unreadable/corrupt entry falls back to the pid-only
+ * check.
+ */
 export function prunePidSessionRegistry(isAlive) {
     let files;
     try {
@@ -92,7 +128,18 @@ export function prunePidSessionRegistry(isAlive) {
     }
     for (const f of files) {
         const pid = Number(f.slice(0, -'.json'.length));
-        if (!Number.isInteger(pid) || isAlive(pid))
+        if (!Number.isInteger(pid))
+            continue;
+        let startedAtMs;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(pidRegistryDir(), f), 'utf8'));
+            if (typeof parsed?.startedAtMs === 'number')
+                startedAtMs = parsed.startedAtMs;
+        }
+        catch {
+            /* unreadable/corrupt — fall back to the pid-only liveness check */
+        }
+        if (isAlive(pid, startedAtMs))
             continue;
         try {
             fs.unlinkSync(path.join(pidRegistryDir(), f));

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

@@ -5,6 +5,13 @@
  * wrapper tags, team-spawn boilerplate) so that only the real user intent
  * remains. Used by the session picker to show a human-readable topic line.
  */
+/**
+ * True when a `role=user` message is harness-injected scaffolding, not a genuine
+ * user turn. Text-based so it is cross-harness by construction (the markers are
+ * the same wrappers across Claude/Codex/etc.); harnesses that already drop their
+ * own scaffolding at parse time simply never reach here.
+ */
+export declare function isSyntheticUserMessage(raw: string | undefined): boolean;
 export declare const HEADLESS_PLAN_MODE_PREFIX = "You are running in HEADLESS PLAN MODE.";
 /** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export declare function cleanSessionPrompt(raw: string): string;

package/dist/lib/session/prompt.js

@@ -26,6 +26,43 @@ const NOISE_LINE_PATTERNS = [
 ];
 /** XML tag prefix used by local-command messages. */
 const LOCAL_COMMAND_PREFIX = '<local-command-caveat>';
+/**
+ * Patterns that mark a whole `role=user` message as harness-injected scaffolding
+ * rather than a genuine user turn: the `!`-prefix shell echo and its output,
+ * slash-command wrappers, injected reminders / task-notifications, the local
+ * caveat, the interrupt marker, skill bodies, and hook feedback. This is the
+ * single cross-harness list — `isSyntheticUserMessage` is consumed by the parser
+ * (`parseSession`) to flag such events `_synthetic`, so `--include user` and the
+ * `--first`/`--last` turn split see only real intent, and every consumer (the
+ * session picker, `session-recall`, external hooks) gets clean user turns without
+ * re-implementing the stripping. Extend this list, not each caller.
+ */
+const SYNTHETIC_USER_MESSAGE_PATTERNS = [
+    /^\s*<\/?(?:bash-input|bash-stdout|bash-stderr)>/i,
+    /^\s*<\/?(?:command-name|command-message|command-args|command-contents)>/i,
+    /^\s*<\/?(?:local-command-stdout|local-command-stderr|local-command-caveat)>/i,
+    /^\s*<\/?system-reminder>/i,
+    /^\s*<\/?task-notification>/i,
+    /^\s*<\/?user-prompt-submit-hook>/i,
+    /^\s*<\/?persisted-output>/i,
+    /^\s*<permissions instructions>/i,
+    /^\s*<collaboration_mode>/i,
+    /^\s*Caveat: The messages below were generated by the user while running/i,
+    /^\s*\[Request interrupted/i,
+    /^\s*Base directory for this skill:/i,
+    /^\s*[A-Za-z][A-Za-z-]* hook feedback:/,
+];
+/**
+ * True when a `role=user` message is harness-injected scaffolding, not a genuine
+ * user turn. Text-based so it is cross-harness by construction (the markers are
+ * the same wrappers across Claude/Codex/etc.); harnesses that already drop their
+ * own scaffolding at parse time simply never reach here.
+ */
+export function isSyntheticUserMessage(raw) {
+    if (!raw)
+        return false;
+    return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
+}
 // Prefix prepended to every Claude-in-plan-mode team spawn prompt.
 // Ends at a blank line before the real user task.
 export const HEADLESS_PLAN_MODE_PREFIX = 'You are running in HEADLESS PLAN MODE.';

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

@@ -37,6 +37,13 @@ export interface SessionProvenance {
     mux?: MuxLocation;
     /** Whether an existing rail can type back into this session (see module doc). */
     reply: ReplyRail;
+    /** The initiating device, resolved at query time from ssh.clientIp against the
+     * device registry (ssh transport only). Answers "who launched this and from
+     * where" without scraping ps/who/tailscale. */
+    origin?: {
+        device: string;
+        user?: string;
+    };
 }
 /** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
 export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY", "ITERM_SESSION_ID"];

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

@@ -12,10 +12,15 @@ import type { SessionEvent, SessionMeta } from './types.js';
  */
 export declare function relativeToCwd(absPath: string, cwd?: string): string;
 /**
- * Wrap label in an OSC 8 hyperlink when the terminal supports it.
- * Degrades to plain label otherwise.
+ * Wrap a filesystem path label in an OSC 8 `file://` hyperlink when the terminal
+ * supports it. Degrades to the plain label otherwise.
  */
 export declare function linkPath(absPath: string, label: string): string;
+/**
+ * Wrap a label in an OSC 8 hyperlink to an arbitrary URL (a PR on GitHub, a Linear
+ * issue, …) when the terminal supports it. Degrades to the plain label otherwise.
+ */
+export declare function linkUrl(url: string, label: string): string;
 /**
  * Unwrap wrapper prefixes to find the actual executable.
  */

package/dist/lib/session/render.js

@@ -13,6 +13,7 @@ import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
 import { redactSecrets } from '../redact.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from './digest.js';
+import { extractTodoProgressFromEvents } from './state.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
@@ -28,19 +29,31 @@ export function relativeToCwd(absPath, cwd) {
     }
     return absPath;
 }
-/**
- * Wrap label in an OSC 8 hyperlink when the terminal supports it.
- * Degrades to plain label otherwise.
- */
-export function linkPath(absPath, label) {
-    if (process.stdout.isTTY &&
+/** Best-effort feature-detect for OSC 8 hyperlink support in the current TTY. */
+function supportsHyperlinks() {
+    return Boolean(process.stdout.isTTY &&
         (process.env.TERM_PROGRAM ||
             process.env.WT_SESSION ||
             process.env.KITTY_WINDOW_ID ||
-            process.env.WEZTERM_PANE)) {
-        return `\x1b]8;;file://${absPath}\x1b\\${label}\x1b]8;;\x1b\\`;
-    }
-    return label;
+            process.env.WEZTERM_PANE));
+}
+/** Wrap `label` in an OSC 8 hyperlink to `target`. Callers gate on {@link supportsHyperlinks}. */
+function osc8(target, label) {
+    return `\x1b]8;;${target}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
+/**
+ * Wrap a filesystem path label in an OSC 8 `file://` hyperlink when the terminal
+ * supports it. Degrades to the plain label otherwise.
+ */
+export function linkPath(absPath, label) {
+    return supportsHyperlinks() ? osc8(`file://${absPath}`, label) : label;
+}
+/**
+ * Wrap a label in an OSC 8 hyperlink to an arbitrary URL (a PR on GitHub, a Linear
+ * issue, …) when the terminal supports it. Degrades to the plain label otherwise.
+ */
+export function linkUrl(url, label) {
+    return supportsHyperlinks() ? osc8(url, label) : label;
 }
 // ── Command grouping ──────────────────────────────────────────────────────────
 /**
@@ -516,7 +529,7 @@ export function renderSummary(events, cwd) {
     // Commands with timestamps
     const cmdList = [];
     // Plan items
-    const todoItems = [];
+    const todoItems = extractTodoProgressFromEvents(events)?.items.map(item => item.content) ?? [];
     let exitPlanContent = null;
     let planFilePath = null;
     // Subagent spawns
@@ -557,19 +570,6 @@ export function renderSummary(events, cwd) {
                     recentActivity.push({ kind: 'cmd', label: cmd, ts });
                 }
             }
-            // Plan items: TodoWrite items + TaskCreate descriptions (project's task tracker)
-            if (tool === 'TodoWrite' && Array.isArray(args.todos)) {
-                for (const item of args.todos) {
-                    const text = item.content || item.text || String(item);
-                    if (text && !todoItems.includes(text))
-                        todoItems.push(text);
-                }
-            }
-            if (tool === 'TaskCreate' && (args.description || args.prompt)) {
-                const text = String(args.description || args.prompt || '').slice(0, 140);
-                if (text && !todoItems.includes(text))
-                    todoItems.push(text);
-            }
             if (tool === 'ExitPlanMode') {
                 exitPlanContent = args.result || args.plan || args.content || null;
             }
@@ -784,6 +784,9 @@ export function parseRoleList(raw, flag) {
     return parts;
 }
 function roleOfEvent(e) {
+    // Synthetic scaffolding still maps to 'user' here so `--exclude user` drops it
+    // like any other user-role event (pre-flag behavior). `--include user`'s
+    // "genuine intent only" carve-out lives in applyRoleFilter, not here.
     if (e.type === 'message' && e.role === 'user')
         return 'user';
     if (e.type === 'message' && e.role === 'assistant')
@@ -805,7 +808,14 @@ function applyRoleFilter(events, opts) {
         const set = new Set(opts.include);
         return events.filter(e => {
             const role = roleOfEvent(e);
-            return role !== null && set.has(role);
+            if (role === null)
+                return false;
+            // `--include user` means genuine user intent, so drop harness-injected
+            // `_synthetic` scaffolding (bash-input, system-reminder) even though it
+            // carries role=user. `--exclude user` still drops it via roleOfEvent.
+            if (role === 'user' && e._synthetic)
+                return false;
+            return set.has(role);
         });
     }
     if (opts.exclude && opts.exclude.length > 0) {
@@ -833,7 +843,11 @@ function applyTurnSlice(events, opts) {
     if (!Number.isFinite(n) || n <= 0) {
         throw new Error(`Turn count must be a positive integer, got ${n}`);
     }
-    const isTurnStart = (e) => e.type === 'message' && e.role === 'user';
+    // A turn starts at a GENUINE user message — harness-injected `_synthetic`
+    // scaffolding (`<bash-input>`/`<bash-stdout>`, etc.) does not start a turn,
+    // so `--first N` / `--last N` count real asks, not the jump command that
+    // opened the session and its shell output.
+    const isTurnStart = (e) => e.type === 'message' && e.role === 'user' && !e._synthetic;
     const turnStartIdx = [];
     for (let i = 0; i < events.length; i++)
         if (isTurnStart(events[i]))

package/dist/lib/session/short-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical derivation of a session's 8-char `shortId`.
+ *
+ * Every session parser used to inline `id.slice(0, 8)` — some with a
+ * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
+ * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
+ * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
+ * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
+ * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
+ * corrupt index row.
+ *
+ * This helper is the single source of truth: it strips the optional prefix, takes
+ * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
+ * falling back to the unstripped id when the strip empties it, so a row always
+ * stays addressable by its shortId.
+ */
+export declare function deriveShortId(id: string, stripPrefix?: RegExp): string;

package/dist/lib/session/short-id.js

@@ -0,0 +1,20 @@
+/**
+ * Canonical derivation of a session's 8-char `shortId`.
+ *
+ * Every session parser used to inline `id.slice(0, 8)` — some with a
+ * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
+ * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
+ * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
+ * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
+ * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
+ * corrupt index row.
+ *
+ * This helper is the single source of truth: it strips the optional prefix, takes
+ * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
+ * falling back to the unstripped id when the strip empties it, so a row always
+ * stays addressable by its shortId.
+ */
+export function deriveShortId(id, stripPrefix) {
+    const stripped = stripPrefix ? id.replace(stripPrefix, '') : id;
+    return stripped.slice(0, 8) || id.slice(0, 8) || id;
+}

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

@@ -126,6 +126,10 @@ export interface StateContext {
  * list, so a session with no plan carries no `todos` field.
  */
 export declare function extractTodoProgress(args?: Record<string, any>): TodoProgress | undefined;
+/** Fold snapshot checklist tools and Claude TaskCreate/TaskUpdate event logs. */
+export declare function extractTodoProgressFromEvents(events: SessionEvent[]): TodoProgress | undefined;
+/** Derive a recency-ordered, de-duplicated list of directories touched by tools. */
+export declare function extractRecentDirectoriesTouched(events: SessionEvent[], cwd?: string): string[] | undefined;
 /** Detect a worktree from the session cwd, per the `.agents/worktrees/<slug>/` convention. */
 export declare function detectWorktree(cwd?: string, branch?: string): DetectedWorktree | undefined;
 /** Detect a tracker ticket from free text (prompt/topic) then a branch name. */