lark-remote 0.1.13 → 0.2.1

package/dist/runner/types.d.ts

@@ -215,6 +215,10 @@ interface ToolUseContent {
     id: string;
     name: string;
     input: unknown;
+    /**
+     * 工具原始 title（ACP kind 映射后与 name 不同时保存；渲染层做面板副标题）。
+     */
+    summary?: string;
 }
 interface ToolResultContent {
     type: 'tool_result';
@@ -259,6 +263,8 @@ export interface ResultEvent {
         /** 当前模型 context window 上限（codex app-server tokenUsage.modelContextWindow
          *  透传）。仅 app-server 提供；缺省时卡片只显示绝对量、不显示百分比。 */
         context_limit?: number;
+        /** 推理 token（pi 提供）。缺省不展示。 */
+        reasoning_tokens?: number;
     };
     total_cost_usd?: number;
     errorMessage?: string;
@@ -275,6 +281,21 @@ export interface PlanEvent {
     plan: string;
     timestamp?: string;
 }
+/** 运行期通知（warning、模型重路由、压缩提示等）。translator 产出，公共层无分支渲染。 */
+export interface NoticeEvent {
+    type: 'notice';
+    level: 'info' | 'warn' | 'error';
+    code?: string;
+    text: string;
+    timestamp?: string;
+}
+/** 会话元信息（ACP session_info_update / current_mode_update）。字段缺省表示本次未变。 */
+export interface SessionInfoEvent {
+    type: 'session_info';
+    title?: string;
+    mode?: string;
+    timestamp?: string;
+}
 /** File change event — for agents that report file modifications (e.g. Codex). */
 export interface FileChangeEvent {
     type: 'file_change';
@@ -319,14 +340,30 @@ export interface TurnDiffEvent {
      * tool status ok, completedAt stamped. Never reorders blocks.
      */
     complete?: boolean;
+    /**
+     * Kimi ACP snapshot semantics: replace the existing block's anchor
+     * timestamp with THIS diff's timestamp on every update (text/reasoning).
+     * Kimi's `'text'`/`'thinking'` are whole-turn accumulators that keep
+     * receiving late deltas while tools run, so a first-sight timestamp makes
+     * the header (and its position after move-to-bottom) look stale. Other
+     * snapshot streams (codex app-server) keep the first-sight timestamp by
+     * contract — this flag stays false/undefined for them.
+     */
+    refreshTimestamp?: boolean;
     /** Authoritative tool status at completion (commandExecution item). */
     toolStatus?: 'ok' | 'error';
+    /** 工具身份（commandExecution/mcpToolCall 等 item 首次发出时携带）。 */
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    toolHint?: ToolHint;
     threadId: string;
     turnId: string;
     timestamp?: string;
 }
 export type RunnerLifetime = 'turn' | 'workspace';
-export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent;
+/** 工具渲染 hint：runner 自愿声明，渲染层只消费不推断。 */
+export type ToolHint = 'shell' | 'file' | 'search' | 'web' | 'patch';
+export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent | NoticeEvent | SessionInfoEvent;
 export interface SpawnOptions {
     cwd: string;
     sessionId?: string;

package/dist/session/claude/sessions.js

@@ -1,16 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findJsonlLine, readLastJsonlLine, scanJsonlLines, readJsonlLinesFromOffset, } from '../common/jsonl.js';
-import { STALE_MS } from '../common/constants.js';
-import { capEvents } from '../common/pagination.js';
+import { findJsonlLine, readLastJsonlLine } from '../common/jsonl.js';
+import { isStale } from '../common/constants.js';
+import { samePath, encodeProjectDirName } from '../../platform/path.js';
 import { extractContentBlocks } from '../common/content-blocks.js';
+import { scanJsonlOnce, tailOffsetAfter, scanTailEvents } from '../common/two-pass.js';
 import { UsageAccumulator, contextWindowOccupancy, cumulativeUsageFields, } from '../common/usage-accumulator.js';
 import { SessionIndex, extractText, isTaskNotificationText, CLAUDE_MAPPING, } from './session-index.js';
 /**
  * Directory Claude Code uses to store session transcripts for a given cwd.
  * Claude encodes the cwd by replacing `/` with `-` (e.g.
  * `/Users/x/proj` -> `-Users-x-proj`). Underscores are also replaced with `-`.
+ * win32 上 `\` 同样是分隔符、`:` 是非法文件名字符，一并归一为 `-`
+ * （`C:\Users\x\proj` -> `C--Users-x-proj`）；见 encodeProjectDirName。
  *
  * Note: this encoding is LOSSY (`disk_d/foo` and `disk-d/foo` both encode to
  * `disk-d-foo`). It is only safe to use the result to **locate** files; never
@@ -18,8 +21,7 @@ import { SessionIndex, extractText, isTaskNotificationText, CLAUDE_MAPPING, } fr
  * from the JSONL content (regression 2026-06-21 /resume & /cd 路径错乱).
  */
 function projectDirForCwd(cwd, projectsDir) {
-    const encoded = cwd.replace(/\//g, '-').replace(/_/g, '-');
-    return path.join(projectsDir, encoded);
+    return path.join(projectsDir, encodeProjectDirName(cwd));
 }
 /**
  * cwd guard for the index-miss fallback (readSessionContent /
@@ -35,7 +37,8 @@ function fileContainsCwd(filePath, cwd) {
     return (findJsonlLine(filePath, (l) => {
         try {
             const obj = JSON.parse(l);
-            return typeof obj.cwd === 'string' && obj.cwd === cwd;
+            // PathKit.samePath：darwin/win32 大小写不敏感 + 尾分隔符不敏感，linux 严格
+            return typeof obj.cwd === 'string' && samePath(obj.cwd, cwd);
         }
         catch {
             return false; // skip malformed line
@@ -111,7 +114,7 @@ export function listClaudeSessions(cwd, opts = {}) {
     const limit = opts.limit;
     const projectsDir = opts.projectsDir ?? defaultProjectsDir();
     const index = ensureSessionIndex(projectsDir);
-    // 首次调用延迟全量建索引；之后 5s 按需节流增量刷新（session-index-manual 拍板 3）。
+    // 首次调用延迟全量建索引；之后 5s 按需节流增量刷新（拍板 3）。
     index.refresh();
     // 统一 parser 的完整 cwd 集合 → A→B→C 任意中间 cwd 都可列出（核心 bug 修复）。
     // readdir 失败时索引保留旧快照（首次失败则为空），与旧扫描的 readdir 兜底等价。
@@ -144,7 +147,7 @@ export function getNewestSession(cwd, opts = {}) {
  */
 function isSessionActive(filePath, mtimeMs, now = Date.now()) {
     // Hard signal: file untouched for over an hour → can't be from a live process
-    if (now - mtimeMs > STALE_MS)
+    if (isStale(mtimeMs, now))
         return false;
     const lastLine = readLastJsonlLine(filePath);
     if (!lastLine)
@@ -239,14 +242,7 @@ function scalarScan(filePath) {
     let lastAiTitle;
     let lastRecap;
     let lastUserMessage;
-    scanJsonlLines(filePath, (line, offset) => {
-        let obj;
-        try {
-            obj = JSON.parse(line);
-        }
-        catch {
-            return;
-        }
+    scanJsonlOnce(filePath, (obj, line, offset) => {
         // --- usage aggregation (was aggregateSessionUsage) ---
         if (obj.type === 'assistant') {
             const msg = obj.message;
@@ -273,12 +269,11 @@ function scalarScan(filePath) {
         }
         // --- last user message offset ---
         // Record the byte offset where the tail should start: the beginning of
-        // the NEXT line after this user message. We compute it as this line's
-        // start offset + its byte length + 1 (the trailing '\n').
+        // the NEXT line after this user message (see tailOffsetAfter).
         if (obj.type === 'user') {
             const msg = obj.message;
             if (msg?.role === 'user') {
-                tailOffset = offset + Buffer.byteLength(line, 'utf-8') + 1;
+                tailOffset = tailOffsetAfter(line, offset);
             }
         }
         // --- ai-title extraction ---
@@ -358,47 +353,30 @@ function scalarScan(filePath) {
     };
 }
 /**
- * P2-2 + P2-5 second-pass: extract content-block events from the tail
- * (lines after the last user message), re-parsing only those lines.
- * `tailLines` is already the tail-only slice (read via
- * `readJsonlLinesFromOffset`), so both raw line-string memory and parsed-
- * object memory are O(tail), not O(whole file) — P3-1 + P2-5.
+ * P2-2 + P2-5 second-pass tail mapper: expand one parsed tail line into
+ * content-block events. Re-parses only tail lines (scanTailEvents does the
+ * offset re-read + line filtering), so both raw line-string memory and
+ * parsed-object memory are O(tail), not O(whole file) — P3-1 + P2-5.
  *
- * `maxEvents` (optional): when set, only the LAST `maxEvents` events are kept
- * (review P2-7 — unified "last N events" contract across all five readers,
- * matching codex/opencode/pi's `slice(-maxEvents)`). The whole tail is parsed
- * first (usage/title extraction above already scanned the file; this pass only
- * re-parses the short tail), then `slice(-maxEvents)` keeps the most recent
- * events. `maxEvents <= 0` returns `[]` (guards the `slice(-0) === slice(0)`
- * full-array trap).
+ * `maxEvents` capping (review P2-7 — unified "last N events" contract across
+ * all readers) is applied by scanTailEvents.
  */
-function extractEventsFromTail(tailLines, maxEvents) {
+function mapClaudeTailLine(obj) {
+    const message = obj.message;
+    // Expand all content blocks from this message into separate events.
+    const blocks = extractContentBlocks(message?.content, CLAUDE_MAPPING);
+    const role = message?.role ?? obj.type ?? 'unknown';
+    const timestamp = obj.timestamp;
     const events = [];
-    for (const line of tailLines) {
-        if (!line.trim())
-            continue;
-        let obj;
-        try {
-            obj = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        const message = obj.message;
-        // Expand all content blocks from this message into separate events.
-        const blocks = extractContentBlocks(message?.content, CLAUDE_MAPPING);
-        const role = message?.role ?? obj.type ?? 'unknown';
-        const timestamp = obj.timestamp;
-        for (const block of blocks) {
-            events.push({ type: block.type, content: block.content, timestamp });
-        }
-        // If message has no content blocks (e.g., metadata-only lines like last-prompt),
-        // still emit an event with the raw type so users see what happened
-        if (blocks.length === 0 && message?.role) {
-            events.push({ type: role, content: `(${role} event)`, timestamp });
-        }
+    for (const block of blocks) {
+        events.push({ type: block.type, content: block.content, timestamp });
+    }
+    // If message has no content blocks (e.g., metadata-only lines like last-prompt),
+    // still emit an event with the raw type so users see what happened
+    if (blocks.length === 0 && message?.role) {
+        events.push({ type: role, content: `(${role} event)`, timestamp });
     }
-    return capEvents(events, maxEvents);
+    return events;
 }
 export function readSessionContent(sessionId, cwd, opts = {}) {
     const { maxEvents } = opts;
@@ -458,8 +436,7 @@ export function readSessionContent(sessionId, cwd, opts = {}) {
     // only the tail. If no user message was found (tailOffset === -1), fall
     // back to re-reading the whole file so the card still has something to
     // show.
-    const tailLines = readJsonlLinesFromOffset(filePath, scan.tailOffset >= 0 ? scan.tailOffset : 0);
-    const events = extractEventsFromTail(tailLines, maxEvents);
+    const events = scanTailEvents(filePath, scan.tailOffset, mapClaudeTailLine, maxEvents);
     // Use aiTitle if available, otherwise fallback to last user message.
     // Truncation is deferred to the consumer (router card building).
     const displayTitle = scan.aiTitle ?? scan.lastUserMessage ?? undefined;

package/dist/session/codex/rollout-reader.d.ts

@@ -10,6 +10,16 @@
  * {"timestamp":"...","type":"response_item","payload":{"type":"message","role":"user|developer","content":[...]}}
  * ```
  *
+ * Event vocabulary drift (codex CLI ≥0.153.4, transitional from 0.147.0): the
+ * top-level `user_message` / `agent_message` events were removed; the same
+ * payloads now ride on `event_msg` → `item_completed` envelopes whose
+ * `item.type` is `UserMessage` / `AgentMessage` / `CommandExecution` / … .
+ * Both spellings stay readable — `extractRealUserText` adapts per file.
+ *
+ * Deprecation: if ~6 months pass (≈2027-03) with the legacy `user_message` /
+ * `agent_message` events still absent from every codex CLI and the old-codex
+ * session tail effectively gone, drop the legacy branch + its fixtures.
+ *
  * Note: This handles the **rollout file format** (historical logging), NOT the
  * `codex exec --json` stdout format（已随 exec 模式移除）。
  */

package/dist/session/codex/rollout-reader.js

@@ -10,6 +10,16 @@
  * {"timestamp":"...","type":"response_item","payload":{"type":"message","role":"user|developer","content":[...]}}
  * ```
  *
+ * Event vocabulary drift (codex CLI ≥0.153.4, transitional from 0.147.0): the
+ * top-level `user_message` / `agent_message` events were removed; the same
+ * payloads now ride on `event_msg` → `item_completed` envelopes whose
+ * `item.type` is `UserMessage` / `AgentMessage` / `CommandExecution` / … .
+ * Both spellings stay readable — `extractRealUserText` adapts per file.
+ *
+ * Deprecation: if ~6 months pass (≈2027-03) with the legacy `user_message` /
+ * `agent_message` events still absent from every codex CLI and the old-codex
+ * session tail effectively gone, drop the legacy branch + its fixtures.
+ *
  * Note: This handles the **rollout file format** (historical logging), NOT the
  * `codex exec --json` stdout format（已随 exec 模式移除）。
  */
@@ -17,6 +27,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonlLines, findJsonlLine } from '../common/jsonl.js';
 import { STALE_MS } from '../common/constants.js';
+import { samePath } from '../../platform/path.js';
 import { paginate, capEvents } from '../common/pagination.js';
 import { sortByRecencyDesc } from '../common/recency.js';
 import { getLogger } from '../../logger/index.js';
@@ -103,15 +114,23 @@ function scanCodexRollout(filePath, includeEvents) {
     const lines = readJsonlLines(filePath);
     const events = [];
     let sessionMeta = null;
-    // Real user input is identified by a paired `event_msg` whose
-    // payload.type === "user_message" - codex emits this ONLY for text the
-    // human actually typed. Injected scaffolding (project rules,
-    // <environment_context>, permissions) is also written as `role:"user"`
-    // response_items but has NO user_message event, so it must be excluded
-    // from displayTitle/recap/summary. Regression 2026-07-13: the first
-    // `role:user` message is the injected project rules, mistakenly shown as
-    // "最近输入".
+    // Real user input comes from the authoritative "human typed this" event —
+    // `user_message` on old codex, `item_completed`/UserMessage on new codex
+    // (see `extractRealUserText`). Injected scaffolding (project rules,
+    // <environment_context>, permissions) is written as `role:"user"`
+    // response_items but gets NEITHER event, so it stays excluded from
+    // displayTitle/recap/summary. Regression 2026-07-13: the first `role:user`
+    // message is the injected project rules, mistakenly shown as "最近输入".
     const realUserMessages = [];
+    // Which channel produced the last pushed message — used only to collapse a
+    // hypothetical double-write (same turn logged by both the legacy and the
+    // item channel), never to drop real consecutive input.
+    let lastUserMessageSource = null;
+    // Drift probe: count of `role:"user"` response_items (injected scaffolding
+    // included). If a file has those but yields zero real user messages, the
+    // event vocabulary changed again and displayTitle silently went empty —
+    // exactly the 0.153 compatibility incident shape.
+    let userResponseItemCount = 0;
     // token_count tracking: codex emits cumulative `total_token_usage` and an
     // incremental `last_token_usage`. We want the LAST turn's usage (matches
     // pi/opencode /resume "last turn" display semantics). When
@@ -148,13 +167,21 @@ function scanCodexRollout(filePath, includeEvents) {
                 sessionMeta = parsed.payload;
             }
             else if (parsed.type === 'event_msg' && parsed.payload) {
-                // user_message events carry the authoritative human-typed text.
                 const payload = parsed.payload;
-                if (payload.type === 'user_message') {
-                    const text = stringValue(payload.message);
-                    if (text) {
-                        realUserMessages.push(text.slice(0, 200));
+                const human = extractRealUserText(payload);
+                if (human) {
+                    const text = human.text.slice(0, 200);
+                    const prev = realUserMessages[realUserMessages.length - 1];
+                    // 过渡期防御：同一 turn 若被旧版 user_message 与新版 item_completed
+                    // 各写一次，会得到相邻重复。仅在「通道切换且文本与上一条完全相同」
+                    // 时跳过——同通道连续相同输入（真人连发两条一样的话）不受影响。
+                    const duplicateAcrossChannels = lastUserMessageSource !== null &&
+                        lastUserMessageSource !== human.source &&
+                        prev === text;
+                    if (!duplicateAcrossChannels) {
+                        realUserMessages.push(text);
                     }
+                    lastUserMessageSource = human.source;
                 }
                 else if (payload.type === 'token_count') {
                     const info = payload.info;
@@ -205,6 +232,8 @@ function scanCodexRollout(filePath, includeEvents) {
             else if (includeEvents && parsed.type === 'response_item' && parsed.payload) {
                 const payload = parsed.payload;
                 if (payload.type === 'message' && Array.isArray(payload.content)) {
+                    if (payload.role === 'user')
+                        userResponseItemCount++;
                     // Extract text content for display
                     const messages = extractMessageContent(payload);
                     for (const msg of messages) {
@@ -222,6 +251,14 @@ function scanCodexRollout(filePath, includeEvents) {
             continue;
         }
     }
+    // 兼容性漂移探针：文件里有 `role:"user"` 注入，却识别不出任何真人输入 ——
+    // 说明 codex 又换了 event_msg 词表，displayTitle 会静默变空（0.153 事故形态）。
+    // 只告警不兜底：误用注入文本当标题正是 2026-07-13 修掉的缺陷。
+    if (realUserMessages.length === 0 && userResponseItemCount > 0) {
+        getLogger().warn(`[codex-rollout-reader] no human user message recognised in ${filePath} ` +
+            `(${userResponseItemCount} role:"user" response_items seen) — codex rollout ` +
+            `event vocabulary may have changed; session title will be empty`);
+    }
     return {
         sessionMeta,
         events,
@@ -305,7 +342,7 @@ export function listCodexRollouts(opts = {}) {
         // session (main file missing) never pollutes the list or total.
         if (entry.isSubagent)
             continue;
-        if (filterCwd && entry.cwd !== filterCwd)
+        if (filterCwd && !samePath(entry.cwd, filterCwd))
             continue;
         matched.push(entry);
     }
@@ -323,6 +360,24 @@ export function listCodexRollouts(opts = {}) {
     }
     return { entries, total };
 }
+/**
+ * W2.6 单源：三处（readCodexSessionContent / readCodexSessionSummary /
+ * isCodexSessionActive）共用的「索引查找 + miss 强制刷新重查」。
+ * cwd 守卫与 subagent 过滤语义各异，留在调用方。
+ */
+function resolveRolloutEntry(sessionId, codexHome) {
+    // P2-4: Use session index for direct file lookup
+    let index = getSessionIndex(codexHome);
+    let entry = index.get(sessionId);
+    // P3-2: On miss, the index may be stale (a rollout file created after the
+    // cache was built but within the 5s TTL). Force a refresh and recheck so a
+    // brand-new session is found without waiting for TTL expiry.
+    if (!entry) {
+        index = getSessionIndex(codexHome, true);
+        entry = index.get(sessionId);
+    }
+    return entry;
+}
 /**
  * Read the full content of a specific session by its threadId.
  *
@@ -338,16 +393,7 @@ export function listCodexRollouts(opts = {}) {
  */
 export function readCodexSessionContent(sessionId, opts = {}) {
     const codexHome = resolveCodexHome(opts.codexHome);
-    // P2-4: Use session index for direct file lookup
-    let index = getSessionIndex(codexHome);
-    let entry = index.get(sessionId);
-    // P3-2: On miss, the index may be stale (a rollout file created after the
-    // cache was built but within the 5s TTL). Force a refresh and recheck so a
-    // brand-new session is found without waiting for TTL expiry.
-    if (!entry) {
-        index = getSessionIndex(codexHome, true);
-        entry = index.get(sessionId);
-    }
+    const entry = resolveRolloutEntry(sessionId, codexHome);
     if (!entry) {
         return { events: [] };
     }
@@ -357,7 +403,7 @@ export function readCodexSessionContent(sessionId, opts = {}) {
     // Codex has no relocation (no EnterWorktree equivalent), so a simple equality
     // check suffices — unlike claude which needs jsonlContainsCwd to handle
     // relocated sessions with multiple cwd values.
-    if (opts.cwd && entry.cwd !== opts.cwd) {
+    if (opts.cwd && !samePath(entry.cwd, opts.cwd)) {
         return { events: [] };
     }
     const rollout = readCodexRollout(entry.filePath);
@@ -387,18 +433,13 @@ export function readCodexSessionContent(sessionId, opts = {}) {
  */
 export function readCodexSessionSummary(sessionId, opts = {}) {
     const codexHome = resolveCodexHome(opts.codexHome);
-    let index = getSessionIndex(codexHome);
-    let entry = index.get(sessionId);
-    if (!entry) {
-        index = getSessionIndex(codexHome, true);
-        entry = index.get(sessionId);
-    }
+    const entry = resolveRolloutEntry(sessionId, codexHome);
     if (!entry) {
         return {};
     }
     // Cwd guard: same semantics as readCodexSessionContent — when a cwd is
     // provided, the session's working directory must match.
-    if (opts.cwd && entry.cwd !== opts.cwd) {
+    if (opts.cwd && !samePath(entry.cwd, opts.cwd)) {
         return {};
     }
     const summary = readCodexRolloutSummary(entry.filePath);
@@ -427,14 +468,7 @@ export function isCodexSessionActive(sessionId, opts = {}) {
     // all use STALE_MS). Previously codex used a divergent 10-minute default.
     const threshold = opts.activeThresholdMs ?? STALE_MS;
     // P2-4: Use session index for direct file lookup + mtime check
-    let index = getSessionIndex(codexHome);
-    let entry = index.get(sessionId);
-    // P3-2: On miss, refresh the index in case the session file was created
-    // after the cache was built (within the 5s TTL). See readCodexSessionContent.
-    if (!entry) {
-        index = getSessionIndex(codexHome, true);
-        entry = index.get(sessionId);
-    }
+    const entry = resolveRolloutEntry(sessionId, codexHome);
     if (!entry) {
         return false;
     }
@@ -446,7 +480,7 @@ export function isCodexSessionActive(sessionId, opts = {}) {
     }
     // Cwd guard: when a cwd is provided, the session's working directory must
     // match (align with claude/pi/opencode which validate cwd).
-    if (opts.cwd && entry.cwd !== opts.cwd) {
+    if (opts.cwd && !samePath(entry.cwd, opts.cwd)) {
         return false;
     }
     // Re-stat to get fresh mtime (index may be up to INDEX_TTL_MS stale)
@@ -594,6 +628,54 @@ function getSessionIndex(resolvedCodexHome, forceRefresh = false) {
 export function clearSessionIndexCache() {
     sessionIndexCache.clear();
 }
+/**
+ * Extract the human-typed text from a rollout `event_msg` payload, adapting to
+ * codex's two rollout event vocabularies.
+ *
+ * - Legacy (CLI ≤0.150.1): a dedicated `{"type":"user_message","message":…}`
+ *   event. Codex emitted it ONLY for text the human actually typed; injected
+ *   scaffolding (project rules, `<environment_context>`, permissions) is
+ *   written as `role:"user"` response_items but gets NO such event, so it stays
+ *   out of displayTitle/recap/summary. (Regression 2026-07-13: the first
+ *   `role:user` message is the injected project rules, once shown as 最近输入.)
+ * - Current (CLI ≥0.153.4, transitional from 0.147.0): the `user_message` /
+ *   `agent_message` events were removed; the same authoritative text now rides
+ *   on `{"type":"item_completed","item":{"type":"UserMessage","content":[…]}}`.
+ *   A UserMessage may bundle several content parts — `text` parts are the human
+ *   input, `skill` parts are injected skill files (e.g. a `$skill-name`
+ *   invocation) that must not leak into the title.
+ *
+ * Real-data note (2026-09): no rollout file observed carries BOTH spellings;
+ * 0.147–0.149 are transitional (either spelling per file), 0.153.4+/0.154.0 are
+ * item_completed-only. `source` reports which spelling matched so the scanner
+ * can collapse a hypothetical double-write of the same turn.
+ *
+ * TODO(2027-03-11): drop the legacy branch (and its fixtures) once ~6 months
+ * pass with the event still absent from every CLI and old-codex tails gone —
+ * mirrors the deprecation note in the module header.
+ */
+function extractRealUserText(payload) {
+    if (payload.type === 'user_message') {
+        const text = stringValue(payload.message);
+        return text ? { text, source: 'legacy' } : null;
+    }
+    if (payload.type === 'item_completed') {
+        const item = payload.item;
+        if (!isRecord(item) || item.type !== 'UserMessage' || !Array.isArray(item.content)) {
+            return null;
+        }
+        const texts = [];
+        for (const part of item.content) {
+            if (!isRecord(part) || part.type !== 'text')
+                continue;
+            const text = stringValue(part.text);
+            if (text)
+                texts.push(text);
+        }
+        return texts.length > 0 ? { text: texts.join('\n'), source: 'item' } : null;
+    }
+    return null;
+}
 function extractMessageContent(payload) {
     const result = [];
     const content = payload.content;

package/dist/session/common/constants.d.ts

@@ -9,3 +9,10 @@
  * mtime is older than this threshold cannot be from a running process.
  */
 export declare const STALE_MS: number;
+/**
+ * A session file is stale (cannot be from a running process) when its
+ * timestamp is older than STALE_MS. All readers share this single
+ * comparison — previously it was re-derived per reader as
+ * `Date.now() - mtimeMs > STALE_MS` (or its `< STALE_MS` negation).
+ */
+export declare function isStale(timestampMs: number, now?: number): boolean;

package/dist/session/common/constants.js

@@ -9,4 +9,13 @@
  * mtime is older than this threshold cannot be from a running process.
  */
 export const STALE_MS = 60 * 60 * 1000;
+/**
+ * A session file is stale (cannot be from a running process) when its
+ * timestamp is older than STALE_MS. All readers share this single
+ * comparison — previously it was re-derived per reader as
+ * `Date.now() - mtimeMs > STALE_MS` (or its `< STALE_MS` negation).
+ */
+export function isStale(timestampMs, now = Date.now()) {
+    return now - timestampMs > STALE_MS;
+}
 //# sourceMappingURL=constants.js.map

package/dist/session/common/two-pass.d.ts

@@ -0,0 +1,22 @@
+import type { AgentSessionContentEvent } from '../../runner/types.js';
+/**
+ * Byte offset where the tail begins: the start of the line AFTER `line`.
+ * `offset` is the byte offset of `line` itself; +1 accounts for the trailing
+ * '\n'.
+ */
+export declare function tailOffsetAfter(line: string, offset: number): number;
+/**
+ * Pass 1: stream the file once, parse each line exactly once (broken lines
+ * skipped), and feed the parsed object + raw line + byte offset to `handle`.
+ * `handle` may mutate closure state to collect scalars and track the tail
+ * offset (via tailOffsetAfter on user lines).
+ */
+export declare function scanJsonlOnce(filePath: string, handle: (obj: Record<string, unknown>, line: string, offset: number) => void): void;
+/**
+ * Pass 2: re-read only the tail (lines after `tailOffset`; the whole file
+ * when tailOffset is -1) and map each parsed line to content events via
+ * `mapLine` (return an array — possibly empty — of events; returning null
+ * skips the line entirely). `maxEvents` keeps the LAST N events
+ * (`maxEvents <= 0` → [], guarding the `slice(-0)` full-array trap).
+ */
+export declare function scanTailEvents(filePath: string, tailOffset: number, mapLine: (obj: Record<string, unknown>) => AgentSessionContentEvent[] | null, maxEvents?: number): AgentSessionContentEvent[];

package/dist/session/common/two-pass.js

@@ -0,0 +1,70 @@
+/**
+ * Two-pass scan skeleton shared by the claude / pi session readers (P2-2 +
+ * P2-5/P2-6 lineage): pass 1 STREAMS the whole file once via `scanJsonlLines`
+ * (no `string[]` materialized), parsing each line exactly once to collect
+ * scalars (usage, tail offset, title) while retaining NO parsed objects; pass
+ * 2 re-reads ONLY the tail from the recorded offset and re-parses it for
+ * content events — O(tail) memory for both raw line strings and parsed
+ * objects, instead of O(whole file).
+ *
+ * Parse ratio: ≈1.0–1.5× line count when a user message exists (streaming
+ * full-file scan + tail re-parse of the usually-short post-user lines). When
+ * the session has NO user message, tailOffset stays -1 and the tail IS the
+ * whole file → scan(N) + tail(N) = 2.0× — the known asymptotic upper bound of
+ * the two-phase design.
+ */
+import { scanJsonlLines, readJsonlLinesFromOffset } from './jsonl.js';
+import { capEvents } from './pagination.js';
+/**
+ * Byte offset where the tail begins: the start of the line AFTER `line`.
+ * `offset` is the byte offset of `line` itself; +1 accounts for the trailing
+ * '\n'.
+ */
+export function tailOffsetAfter(line, offset) {
+    return offset + Buffer.byteLength(line, 'utf-8') + 1;
+}
+/**
+ * Pass 1: stream the file once, parse each line exactly once (broken lines
+ * skipped), and feed the parsed object + raw line + byte offset to `handle`.
+ * `handle` may mutate closure state to collect scalars and track the tail
+ * offset (via tailOffsetAfter on user lines).
+ */
+export function scanJsonlOnce(filePath, handle) {
+    scanJsonlLines(filePath, (line, offset) => {
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        handle(obj, line, offset);
+    });
+}
+/**
+ * Pass 2: re-read only the tail (lines after `tailOffset`; the whole file
+ * when tailOffset is -1) and map each parsed line to content events via
+ * `mapLine` (return an array — possibly empty — of events; returning null
+ * skips the line entirely). `maxEvents` keeps the LAST N events
+ * (`maxEvents <= 0` → [], guarding the `slice(-0)` full-array trap).
+ */
+export function scanTailEvents(filePath, tailOffset, mapLine, maxEvents) {
+    const tailLines = readJsonlLinesFromOffset(filePath, tailOffset >= 0 ? tailOffset : 0);
+    const events = [];
+    for (const line of tailLines) {
+        if (!line.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const produced = mapLine(obj);
+        if (produced)
+            events.push(...produced);
+    }
+    return capEvents(events, maxEvents);
+}
+//# sourceMappingURL=two-pass.js.map