@phnx-labs/agents-cli 1.22.82 → 1.22.84

package/dist/lib/session/db.js

@@ -22,13 +22,14 @@ import { extractBackgroundShells, extractSkills, extractSlashCommands, harnessTr
 import { resolveResource } from '../resources.js';
 import { discoverPlugins } from '../plugins/plugins.js';
 import { machineId } from '../machine-id.js';
-import { firstUserMessageFromEvents } from './prompt.js';
+import { firstUserMessageFromEvents, lastUserMessageFromEvents } from './prompt.js';
+import { emptyTimelineState, TIMELINE_EXTRACTOR_VERSION } from './timeline.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 47;
+export const SCHEMA_VERSION = 48;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -103,6 +104,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   git_branch TEXT,
   topic TEXT,
   first_user_message TEXT,
+  last_user_message TEXT,
   label TEXT,
   message_count INTEGER,
   token_count INTEGER,
@@ -420,6 +422,27 @@ CREATE TABLE IF NOT EXISTS session_summaries (
   summary_json TEXT NOT NULL
 );
 
+-- Daemon-computed narration-anchored timeline (PHNX-3939). Same lazy,
+-- stamp-validated cache shape as session_summaries, with one addition: the fold
+-- is INCREMENTAL, so the row carries both the bounded projection the display
+-- path reads and the resume state the pass folds the next appended bytes onto.
+--
+-- Two columns rather than one on purpose. projection_json is small and bounded
+-- (8 steps + counters + the tidied request + 8 file rows) and is what a session
+-- row merges on the read path; state_json holds the whole TimelineState (byte
+-- offset, open step, pending call ids, per-path file ledger) and is read ONLY by
+-- the daemon pass. Folding one blob would make every row merge parse the resume
+-- state it has no use for.
+CREATE TABLE IF NOT EXISTS session_timelines (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  projection_json TEXT NOT NULL,
+  state_json TEXT NOT NULL
+);
+
 -- Durable metadata for one browser task (RUSH-2549). The browser daemon's
 -- tasks.json is LIVE state: saveTaskState writes the in-memory task map, so
 -- stopping a task drops its entry and a daemon restart empties the file. That is
@@ -1286,6 +1309,25 @@ function migrateSchema(db, fromVersion) {
         // The idx_sessions_mirror_synced index is created unconditionally after this
         // block (fresh DBs skip migrations), alongside idx_sessions_last_activity.
     }
+    if (fromVersion < 48) {
+        // v47 -> v48: retain the LATEST genuine user turn beside the first
+        // (PHNX-3939). For a /continue, a redirect, or an interrupted-and-restated
+        // session the operative request is the last thing the user said, and the row
+        // title / sidebar Request card show that.
+        //
+        // Deliberately WITHOUT a CONTENT_INDEX_VERSION bump, unlike the v45
+        // first_user_message column. That bump forces a re-parse of every indexed
+        // transcript on the next scan; measured on this fleet it pinned the daemon
+        // long enough to blow the session-index and session-state tick deadlines and
+        // park both services. It also buys nothing here: the value can only CHANGE
+        // when the transcript changes, so the ordinary incremental scan fills it in
+        // for exactly the sessions where it matters, and the sidebar's request comes
+        // from the daemon-folded `session_timelines` projection rather than this
+        // column. An old row simply keeps NULL until its next write.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('last_user_message'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN last_user_message TEXT`);
+    }
     if (fromVersion < 47) {
         // v46 -> v47: carry the actor's Phoenix id (PHNX-3798). Additive, write-once
         // launch metadata joined from the actor sidecar — never transcript-derived,
@@ -1842,7 +1884,7 @@ const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, harness, origin, routine_name, routine_run_id,
     version, account, account_key, account_org, mode, timestamp, last_activity,
-    project, cwd, git_branch, topic, first_user_message, label, message_count, token_count,
+    project, cwd, git_branch, topic, first_user_message, last_user_message, label, message_count, token_count,
     output_tokens, input_tokens, cache_read_tokens, cache_write_tokens,
     cost_usd, cost_usd_nocache, duration_ms, model, tool_call_count,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
@@ -1853,7 +1895,7 @@ const upsertSessionStmt = (db) => db.prepare(`
   ) VALUES (
     @id, @short_id, @agent, @harness, @origin, @routine_name, @routine_run_id,
     @version, @account, @account_key, @account_org, @mode, @timestamp, @last_activity,
-    @project, @cwd, @git_branch, @topic, @first_user_message, @label, @message_count, @token_count,
+    @project, @cwd, @git_branch, @topic, @first_user_message, @last_user_message, @label, @message_count, @token_count,
     @output_tokens, @input_tokens, @cache_read_tokens, @cache_write_tokens,
     @cost_usd, @cost_usd_nocache, @duration_ms, @model, @tool_call_count,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
@@ -1891,6 +1933,10 @@ const upsertSessionStmt = (db) => db.prepare(`
     git_branch = excluded.git_branch,
     topic = excluded.topic,
     first_user_message = COALESCE(excluded.first_user_message, sessions.first_user_message),
+    -- Unlike the first turn, the LATEST one moves: a new turn must replace the
+    -- stored value, so this is excluded-wins with a COALESCE only to keep a
+    -- known value when a rescan cannot re-derive one.
+    last_user_message = COALESCE(excluded.last_user_message, sessions.last_user_message),
     -- Never let an empty/placeholder incoming label clobber a good stored one.
     -- A real incoming label (non-empty after trim) still wins; a blank one keeps
     -- the label seeded by --name (seedLabelsFromNames) or refined by an agent
@@ -2110,6 +2156,7 @@ function enrichMetaFromEvents(meta, events) {
     return {
         ...meta,
         firstUserMessage: meta.firstUserMessage ?? firstUserMessageFromEvents(events),
+        lastUserMessage: meta.lastUserMessage ?? lastUserMessageFromEvents(events),
         todos: extractTodoProgressFromEvents(events),
         recentDirectoriesTouched: extractRecentDirectoriesTouched(events, meta.cwd),
         ...fanOutCounts(events, meta.agent),
@@ -2201,6 +2248,7 @@ export function upsertSession(meta, content, scan, assistantContent = '') {
         git_branch: meta.gitBranch ?? null,
         topic: meta.topic ?? null,
         first_user_message: meta.firstUserMessage ?? null,
+        last_user_message: meta.lastUserMessage ?? null,
         label: meta.label ?? null,
         message_count: meta.messageCount ?? null,
         token_count: meta.tokenCount ?? null,
@@ -2441,6 +2489,7 @@ export function upsertSessionsBatch(entries) {
                     git_branch: meta.gitBranch ?? null,
                     topic: meta.topic ?? null,
                     first_user_message: meta.firstUserMessage ?? null,
+                    last_user_message: meta.lastUserMessage ?? null,
                     label: meta.label ?? null,
                     message_count: meta.messageCount ?? null,
                     token_count: meta.tokenCount ?? null,
@@ -2690,6 +2739,7 @@ function rowToMeta(row) {
         mode: isSessionRunMode(row.mode) ? row.mode : undefined,
         topic: row.topic ?? undefined,
         firstUserMessage: row.first_user_message ?? undefined,
+        lastUserMessage: row.last_user_message ?? undefined,
         label: row.label ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
         prUrl: row.pr_url ?? undefined,
@@ -3417,6 +3467,68 @@ export function writeSessionSummary(entry) {
       summary_json = excluded.summary_json
   `).run(entry.id, entry.fileMtimeMs, entry.fileSize, SESSION_SUMMARY_EXTRACTOR_VERSION, Date.now(), JSON.stringify(entry.summary));
 }
+function parseTimelineProjection(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the projection AND the resume state for one session, whatever the
+ * transcript stamp — the daemon pass's read, which needs the state to continue
+ * from and re-stats the file itself.
+ */
+export function readSessionTimelineEntry(id) {
+    const row = getDB().prepare(`
+    SELECT projection_json AS projectionJson, state_json AS stateJson, computed_at AS computedAt
+    FROM session_timelines
+    WHERE session_id = ? AND extractor_version = ?
+  `).get(id, TIMELINE_EXTRACTOR_VERSION);
+    if (!row)
+        return undefined;
+    const projection = parseTimelineProjection(row.projectionJson);
+    if (!projection)
+        return undefined;
+    try {
+        return { ...projection, state: JSON.parse(row.stateJson), computedAt: row.computedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read only the bounded projection for one session — the display merge, on the
+ * read path. Deliberately does NOT parse the resume state: a live row needs the
+ * 8 steps and the request, never the fold's bookkeeping.
+ */
+export function readSessionTimelineAny(id) {
+    const row = getDB().prepare(`
+    SELECT projection_json AS projectionJson
+    FROM session_timelines
+    WHERE session_id = ? AND extractor_version = ?
+  `).get(id, TIMELINE_EXTRACTOR_VERSION);
+    if (!row)
+        return undefined;
+    return parseTimelineProjection(row.projectionJson);
+}
+/** Persist a folded timeline against the exact transcript bytes it was folded to. */
+export function writeSessionTimeline(entry) {
+    const { state, ...projection } = entry.timeline;
+    getDB().prepare(`
+    INSERT INTO session_timelines
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, projection_json, state_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      projection_json = excluded.projection_json,
+      state_json = excluded.state_json
+  `).run(entry.id, entry.fileMtimeMs, entry.fileSize, TIMELINE_EXTRACTOR_VERSION, entry.computedAtMs ?? Date.now(), JSON.stringify(projection), JSON.stringify(state));
+}
 /**
  * The most-recently-active sessions whose transcript is genuinely local to this
  * box — a real `file_path`, not a peer mirror — for publishing to the fleet
@@ -3444,6 +3556,7 @@ export function queryLocalOriginSessionsForMirror(self, limit) {
         // Ride the daemon-computed summary alongside the digest so a peer renders it
         // without a transcript (PHNX-3939); only a summarized session carries one.
         summary: readSessionSummaryAny(r.id) ?? null,
+        timeline: readSessionTimelineAny(r.id) ?? null,
     }));
 }
 /**
@@ -3525,6 +3638,18 @@ export function upsertMirrorSession(row, source, syncedAt) {
     if (row.summary) {
         writeSessionSummary({ id: row.id, fileMtimeMs: null, fileSize: null, summary: row.summary });
     }
+    // Same for the peer's folded timeline (PHNX-3939): the projection is what a row
+    // renders, and the resume state is deliberately EMPTY — this box never folds a
+    // peer's transcript (it does not have one), so storing a foreign byte offset
+    // would be a resume point into a file that is not here.
+    if (row.timeline) {
+        writeSessionTimeline({
+            id: row.id,
+            fileMtimeMs: null,
+            fileSize: null,
+            timeline: { ...row.timeline, state: emptyTimelineState() },
+        });
+    }
     return true;
 }
 /**
@@ -3542,12 +3667,14 @@ export function pruneMirrorSessions(cutoffMs) {
     const delText = db.prepare(`DELETE FROM session_text WHERE session_id = ?`);
     const delPreview = db.prepare(`DELETE FROM session_preview_cache WHERE session_id = ?`);
     const delSummary = db.prepare(`DELETE FROM session_summaries WHERE session_id = ?`);
+    const delTimeline = db.prepare(`DELETE FROM session_timelines WHERE session_id = ?`);
     const txn = db.transaction(() => {
         for (const { id } of stale) {
             delRow.run(id);
             delText.run(id);
             delPreview.run(id);
             delSummary.run(id);
+            delTimeline.run(id);
         }
     });
     txn();

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

@@ -26,6 +26,11 @@ export declare const SESSION_MIRROR_MAX_ROWS = 200;
 export declare const SESSION_MIRROR_SNIPPET_MAX = 280;
 /** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
 export declare const SESSION_MIRROR_MAX_AGE_MS: number;
+/** Caps for the timeline block on a published mirror row. */
+export declare const SESSION_MIRROR_MAX_STEPS = 8;
+export declare const SESSION_MIRROR_STEP_TEXT_MAX = 160;
+export declare const SESSION_MIRROR_REQUEST_MAX = 2000;
+export declare const SESSION_MIRROR_MAX_FILES = 8;
 export interface PublishSessionMirrorOptions {
     userAgentsDir?: string;
     device?: string;

package/dist/lib/session/mirror.js

@@ -30,6 +30,43 @@ export const SESSION_MIRROR_MAX_ROWS = 200;
 export const SESSION_MIRROR_SNIPPET_MAX = 280;
 /** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
 export const SESSION_MIRROR_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
+/** Caps for the timeline block on a published mirror row. */
+export const SESSION_MIRROR_MAX_STEPS = 8;
+export const SESSION_MIRROR_STEP_TEXT_MAX = 160;
+export const SESSION_MIRROR_REQUEST_MAX = 2_000;
+export const SESSION_MIRROR_MAX_FILES = 8;
+function cap(value, max) {
+    return value.length > max ? value.slice(0, max) : value;
+}
+/** Bound the tidied request: prose capped, chips capped, never re-derived. */
+function boundedRequest(request) {
+    return {
+        ...request,
+        text: cap(request.text, SESSION_MIRROR_REQUEST_MAX),
+        headline: cap(request.headline, SESSION_MIRROR_STEP_TEXT_MAX),
+        ...(request.command ? { command: cap(request.command, 120) } : {}),
+        attachments: request.attachments.slice(0, SESSION_MIRROR_MAX_FILES)
+            .map((a) => ({ kind: a.kind, name: cap(a.name, 120) })),
+    };
+}
+/** Bound the step list. Counters are kept exact — only text is truncated. */
+function boundedTimeline(timeline) {
+    const steps = timeline.steps.slice(-SESSION_MIRROR_MAX_STEPS).map((step) => ({
+        ...step,
+        text: cap(step.text, SESSION_MIRROR_STEP_TEXT_MAX),
+        ...(step.now ? { now: cap(step.now, SESSION_MIRROR_STEP_TEXT_MAX) } : {}),
+        ...(step.marks ? { marks: step.marks.slice(0, 4).map((mark) => cap(mark, 40)) } : {}),
+    }));
+    return { ...timeline, steps, ...(timeline.reason ? { reason: cap(timeline.reason, 200) } : {}) };
+}
+/** Bound the file rows; `total` still reports the real count. */
+function boundedFiles(files) {
+    return {
+        ...files,
+        changes: files.changes.slice(0, SESSION_MIRROR_MAX_FILES)
+            .map((change) => ({ ...change, path: cap(change.path, 400) })),
+    };
+}
 function snippet(value, max = SESSION_MIRROR_SNIPPET_MAX) {
     if (!value)
         return undefined;
@@ -83,6 +120,12 @@ export async function publishSessionMirrorToSharedStore(options = {}) {
             }
             : {}),
         ...(s.summary?.summaryState ? { summaryState: s.summary.summaryState } : {}),
+        // Same bound-on-publish discipline as the summary above: the fleet state file
+        // is git-synced, so the request text, the step list, and the file rows are
+        // capped here rather than shipped raw (PHNX-3939).
+        ...(s.timeline?.request ? { request: boundedRequest(s.timeline.request) } : {}),
+        ...(s.timeline?.timeline ? { timeline: boundedTimeline(s.timeline.timeline) } : {}),
+        ...(s.timeline?.files ? { files: boundedFiles(s.timeline.files) } : {}),
         capturedAt,
     }));
     try {
@@ -133,8 +176,131 @@ function toUpsert(raw) {
         ticketId: cap(r.ticketId, 64),
         prUrl: cap(r.prUrl, 512),
         summary: toMirrorSummary(r),
+        timeline: toMirrorTimeline(r),
     };
 }
+/**
+ * Validate an untrusted peer's published request/timeline/files into the bounded
+ * projection the local cache stores (PHNX-3939). Bounds mirror the publish side,
+ * so a hostile or oversized peer cannot bloat this box's cache. Only a row that
+ * carries a well-formed timeline is kept; a malformed one is dropped whole
+ * rather than partially trusted.
+ */
+function toMirrorTimeline(r) {
+    const timeline = toMirrorTimelineBlock(r.timeline);
+    if (!timeline)
+        return undefined;
+    return {
+        timeline,
+        ...(toMirrorRequest(r.request) ? { request: toMirrorRequest(r.request) } : {}),
+        ...(toMirrorFiles(r.files) ? { files: toMirrorFiles(r.files) } : {}),
+    };
+}
+function isRecord(v) {
+    return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+function count(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+}
+/** The verb keys a peer's `mix` may carry — anything else is dropped, not trusted. */
+const MIRROR_VERB_CLASSES = [
+    'read', 'edit', 'run', 'git', 'test', 'browser', 'agent', 'other',
+];
+/** A peer's per-verb breakdown, whitelisted by key and clamped by value. */
+function toMirrorMix(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const mix = {};
+    for (const verb of MIRROR_VERB_CLASSES) {
+        const n = count(raw[verb]);
+        if (n > 0)
+            mix[verb] = n;
+    }
+    return Object.keys(mix).length ? mix : undefined;
+}
+function toMirrorTimelineBlock(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const state = raw.state;
+    if (state !== 'ready' && state !== 'partial' && state !== 'unavailable')
+        return undefined;
+    const steps = (Array.isArray(raw.steps) ? raw.steps : [])
+        .filter(isRecord)
+        .filter((step) => isString(step.text) && isString(step.at))
+        .slice(0, SESSION_MIRROR_MAX_STEPS)
+        .map((step) => ({
+        text: String(step.text).slice(0, SESSION_MIRROR_STEP_TEXT_MAX),
+        at: String(step.at).slice(0, 40),
+        ...(isString(step.endedAt) ? { endedAt: step.endedAt.slice(0, 40) } : {}),
+        source: (step.source === 'thinking' || step.source === 'derived' || step.source === 'user'
+            ? step.source : 'narration'),
+        tools: count(step.tools),
+        failed: count(step.failed),
+        blocked: count(step.blocked),
+        ...(isString(step.now) ? { now: step.now.slice(0, SESSION_MIRROR_STEP_TEXT_MAX) } : {}),
+        // `mix` and `live` are what the sidebar renders a step WITH ("6 run ·
+        // 2 blocked", the amber now-line). Dropping them here made a remote row
+        // disagree with the local one about what a live step even is, while `now`
+        // survived — so they ride through, whitelisted like every other field.
+        ...(step.live === true ? { live: true } : {}),
+        ...(() => {
+            const mix = toMirrorMix(step.mix);
+            return mix ? { mix } : {};
+        })(),
+        ...(Array.isArray(step.marks)
+            ? { marks: step.marks.filter(isString).slice(0, 4).map((mark) => mark.slice(0, 40)) }
+            : {}),
+    }));
+    const earlier = isRecord(raw.earlier) ? raw.earlier : {};
+    return {
+        steps,
+        earlier: { steps: count(earlier.steps), tools: count(earlier.tools), failed: count(earlier.failed) },
+        tools: count(raw.tools),
+        failed: count(raw.failed),
+        blocked: count(raw.blocked),
+        spanMs: count(raw.spanMs),
+        state,
+        ...(isString(raw.reason) ? { reason: raw.reason.slice(0, 200) } : {}),
+    };
+}
+function toMirrorRequest(raw) {
+    if (!isRecord(raw) || !isString(raw.headline))
+        return undefined;
+    const kind = raw.kind;
+    return {
+        text: isString(raw.text) ? raw.text.slice(0, SESSION_MIRROR_REQUEST_MAX) : '',
+        headline: raw.headline.slice(0, SESSION_MIRROR_STEP_TEXT_MAX),
+        kind: kind === 'image' || kind === 'command' || kind === 'skill' ? kind : 'text',
+        ...(isString(raw.command) ? { command: raw.command.slice(0, 120) } : {}),
+        attachments: (Array.isArray(raw.attachments) ? raw.attachments : [])
+            .filter(isRecord)
+            .filter((a) => isString(a.name))
+            .slice(0, SESSION_MIRROR_MAX_FILES)
+            .map((a) => ({
+            kind: a.kind === 'image' || a.kind === 'dir' ? a.kind : 'file',
+            name: String(a.name).slice(0, 120),
+        })),
+        pastedLines: count(raw.pastedLines),
+        ...(typeof raw.turns === 'number' ? { turns: count(raw.turns) } : {}),
+    };
+}
+function toMirrorFiles(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const changes = (Array.isArray(raw.changes) ? raw.changes : [])
+        .filter(isRecord)
+        .filter((change) => isString(change.path))
+        .slice(0, SESSION_MIRROR_MAX_FILES)
+        .map((change) => ({
+        path: String(change.path).slice(0, 400),
+        op: (change.op === 'created' || change.op === 'deleted' ? change.op : 'modified'),
+        edits: count(change.edits),
+        at: isString(change.at) ? change.at.slice(0, 40) : '',
+    }));
+    if (!changes.length)
+        return undefined;
+    return { changes, total: count(raw.total) || changes.length, source: raw.source === 'harness' ? 'harness' : 'tools' };
+}
 /** One published summary state, validated back into the union or undefined. */
 function toSummaryState(v) {
     return v === 'pending' || v === 'ready' || v === 'skipped' ? v : undefined;

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

@@ -33,6 +33,14 @@ export interface ParseSessionOptions {
     maxToolOutputChars?: number;
     /** Opt-in because interrupts are not user messages and would change the published event stream. */
     includeInterrupts?: boolean;
+    /**
+     * Opt-in `file_change` events from the harness's own file ledger (Claude
+     * `file-history-delta`). Opt-in for the same reason as
+     * {@link includeInterrupts}: they are not tool calls, and emitting them by
+     * default would change every published event stream (message counts, digests,
+     * trajectories) for a signal only the timeline fold consumes.
+     */
+    includeFileHistory?: boolean;
 }
 export declare function parseSession(filePath: string, agent?: SessionAgentId, opts?: ParseSessionOptions): SessionEvent[];
 /** Infer the agent type from a session file path using known directory conventions. */
@@ -75,6 +83,28 @@ export declare function applyPatchTargets(input: string): Array<{
     op: 'Add' | 'Update' | 'Delete';
 }>;
 export declare function applyPatchTargetPaths(input: string): string[];
+/**
+ * Codex writes its turn TWICE in one rollout: the raw `response_item` records
+ * the model exchanged, and a parallel `event_msg` / `item_completed` stream of
+ * typed, already-classified items. The two overlap — on a 6,244-line rollout on
+ * zion (2026-09-06) the same turn appears as 648 `custom_tool_call` +
+ * 60 `function_call` records AND as 1,038 `CommandExecution` items — so the two
+ * MUST NOT be merged into one event list: every consumer that counts tool calls
+ * (digest, trajectory, insights, the tool index) would double-count.
+ *
+ * {@link parseCodexContent} therefore keeps reading `response_item` and this is
+ * a SEPARATE reader over the item stream, for consumers that want the harness's
+ * own classification instead of re-deriving it: the command as Codex parsed it
+ * (`parsed_cmd.type`), its `exit_code`/`status`, the per-path `FileChange`
+ * ledger, `AgentMessage.phase` (`commentary` is the narration between calls),
+ * web searches, sub-agent activity and compactions. The timeline fold is the
+ * consumer; `parseSession` is untouched.
+ *
+ * Version-tolerant by construction: an item type this does not know folds to a
+ * generic `other` tool_use rather than throwing, so a Codex release that adds an
+ * item type degrades to a counted step instead of an empty timeline.
+ */
+export declare function parseCodexItemsContent(content: string): SessionEvent[];
 /**
  * Parse Codex JSONL *content* (already read into a string) into normalized
  * events. Split from `parseCodex` so the tail reader can parse just the last
@@ -142,6 +172,25 @@ export declare function sessionFilePathContainer(filePath: string): string;
  * timestamps aren't stored, so every event carries the session's `created_at`
  * (from summary.json), falling back to the transcript's mtime.
  */
+/**
+ * Counters Grok writes beside its transcript in `signals.json` — the only place
+ * a Grok session records milestones and failures, since `chat_history.jsonl`
+ * carries no timestamps and no exit codes. Read by the timeline fold to mark a
+ * session that committed / opened / merged a PR and to report a tool-failure
+ * count the event stream cannot supply.
+ */
+export interface GrokSessionSignals {
+    gitCommitCount: number;
+    prCreatedCount: number;
+    prMergedCount: number;
+    toolFailureCount: number;
+}
+/**
+ * Read `signals.json` next to a Grok transcript. Returns `undefined` when the
+ * file is absent or unreadable — a Grok session simply has no signals then, and
+ * the fold reports what it does have rather than inventing zeros.
+ */
+export declare function readGrokSignals(filePath: string): GrokSessionSignals | undefined;
 export declare function parseGrok(filePath: string): SessionEvent[];
 /**
  * The transcript query {@link parseOpenCode} runs, exported so a test can assert