@oh-my-pi/pi-coding-agent 15.8.2 → 15.9.0

package/dist/types/extensibility/custom-tools/types.d.ts

@@ -15,7 +15,7 @@ import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { HookUIContext } from "../../extensibility/hooks/types";
 import type { Theme } from "../../modes/theme/theme";
 import type { ReadonlySessionManager } from "../../session/session-manager";
-import type { TodoItem } from "../../tools/todo-write";
+import type { TodoItem } from "../../tools/todo";
 /** Alias for clarity */
 export type CustomToolUIContext = HookUIContext;
 export type { ExecOptions, ExecResult } from "../../exec/exec";

package/dist/types/extensibility/extensions/types.d.ts

@@ -59,6 +59,17 @@ export interface ExtensionUIDialogOptions {
     onExternalEditor?: () => void;
     /** Optional footer hint text rendered by interactive selector */
     helpText?: string;
+    /** Render a leading radio/checkbox marker before each markable option in
+     *  select dialogs (matches the ask transcript). "radio" fills the cursor row
+     *  for single-choice; "checkbox" reflects `checkedIndices` per row for
+     *  multi-select. Options beyond `markableCount` keep the plain cursor. */
+    selectionMarker?: "radio" | "checkbox";
+    /** For `selectionMarker: "checkbox"`: option indices currently checked. */
+    checkedIndices?: readonly number[];
+    /** Number of leading options that receive a selection marker; the remaining
+     *  trailing options (e.g. "Other"/"Done" actions) keep the plain cursor.
+     *  Defaults to all options when `selectionMarker` is set. */
+    markableCount?: number;
 }
 /** Raw terminal input listener for extensions. */
 export type TerminalInputHandler = (data: string) => {

package/dist/types/extensibility/shared-events.d.ts

@@ -18,7 +18,7 @@ import type { ImageContent, TextContent, ToolResultMessage } from "@oh-my-pi/pi-
 import type { Rule } from "../capability/rule";
 import type { Goal, GoalModeState } from "../goals/state";
 import type { BranchSummaryEntry, CompactionEntry, SessionEntry } from "../session/session-manager";
-import type { TodoItem } from "../tools/todo-write";
+import type { TodoItem } from "../tools/todo";
 /** Fired on initial session load */
 export interface SessionStartEvent {
     type: "session_start";

package/dist/types/index.d.ts

@@ -22,6 +22,7 @@ export * from "./modes/theme/theme";
 export * from "./sdk";
 export * from "./session/agent-session";
 export * from "./session/auth-storage";
+export * from "./session/indexed-session-storage";
 export * from "./session/messages";
 export * from "./session/redis-session-storage";
 export * from "./session/session-dump-format";

package/dist/types/mcp/transports/stdio.d.ts

@@ -12,15 +12,24 @@ interface FrameSink {
 }
 /**
  * Write a newline-delimited JSON-RPC frame to the subprocess's stdin sink,
- * swallowing synchronous errors so the caller can decide how to react.
+ * swallowing both synchronous throws and asynchronous rejections so the caller
+ * can decide how to react.
  *
- * Bun's `FileSink` may throw synchronously (most reliably on Windows) when
- * the read end of the pipe has been closed by a subprocess that exited
- * between read-loop ticks. Letting that throw escape an `async` method
- * surfaces as an unhandled promise rejection at the call site.
+ * Bun's `FileSink.write()`/`flush()` can fail two ways once the read end of the
+ * pipe has been closed by a subprocess that exited between read-loop ticks:
+ *   - a synchronous throw (most reliably observed on Windows), and
+ *   - a *rejected Promise* returned from `write()`/`flush()`, i.e. the EPIPE is
+ *     surfaced asynchronously (note the `processTicksAndRejections` frame in the
+ *     stack traces on #1710 and the follow-up report).
  *
- * Returns `true` when the frame was accepted by the sink, `false` when the
- * sink threw — callers signal transport closure on `false`.
+ * A sibling `async` method's `try/catch` only catches the synchronous case; an
+ * un-awaited rejected Promise escapes as a fatal unhandled rejection. So we both
+ * catch the throw and neutralize any returned promise's rejection.
+ *
+ * Returns `true` when the frame was accepted synchronously, `false` when the
+ * sink threw — callers signal transport closure on `false`. An asynchronous
+ * failure cannot be reflected in the return value; it is neutralized here and
+ * the dead transport is detected by the read loop / request timeout instead.
  */
 export declare function writeFrame(stdin: FrameSink, frame: string): boolean;
 /**

package/dist/types/modes/components/assistant-message.d.ts

@@ -1,5 +1,5 @@
 import type { AssistantMessage, ImageContent, Usage } from "@oh-my-pi/pi-ai";
-import { Container } from "@oh-my-pi/pi-tui";
+import { Container, type ImageBudget } from "@oh-my-pi/pi-tui";
 import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
 /**
  * Component that renders a complete assistant message
@@ -9,7 +9,8 @@ export declare class AssistantMessageComponent extends Container {
     private hideThinkingBlock;
     private readonly onImageUpdate?;
     private readonly thinkingRenderers;
-    constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, thinkingRenderers?: readonly AssistantThinkingRenderer[]);
+    private readonly imageBudget?;
+    constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, thinkingRenderers?: readonly AssistantThinkingRenderer[], imageBudget?: ImageBudget | undefined);
     invalidate(): void;
     setHideThinkingBlock(hide: boolean): void;
     setToolResultImages(toolCallId: string, images: ImageContent[]): void;

package/dist/types/modes/components/hook-selector.d.ts

@@ -44,6 +44,17 @@ export interface HookSelectorOptions {
     /** Indices into the original options that cannot be selected: they render
      *  dimmed, are skipped during navigation, and reject enter/timeout. */
     disabledIndices?: readonly number[];
+    /** Render a leading radio/checkbox marker before each markable option,
+     *  matching the ask transcript. "radio" fills the marker on the cursor row
+     *  (single-choice); "checkbox" reflects {@link checkedIndices} per row
+     *  (multi-select). Options at or beyond {@link markableCount} keep the plain
+     *  cursor prefix — used for trailing control rows like "Other"/"Done". */
+    selectionMarker?: "radio" | "checkbox";
+    /** For `selectionMarker: "checkbox"`: original-indices currently checked. */
+    checkedIndices?: readonly number[];
+    /** Number of leading options (original order) that receive a selection
+     *  marker. Defaults to every option when {@link selectionMarker} is set. */
+    markableCount?: number;
 }
 export interface HookSelectorOption {
     label: string;

package/dist/types/modes/components/todo-reminder.d.ts

@@ -1,5 +1,5 @@
 import { Container } from "@oh-my-pi/pi-tui";
-import type { TodoItem } from "../../tools/todo-write";
+import type { TodoItem } from "../../tools/todo";
 /**
  * Component that renders a todo completion reminder notification.
  * Shows when the agent stops with incomplete todos.

package/dist/types/modes/components/transcript-container.d.ts

@@ -0,0 +1,36 @@
+import { Container } from "@oh-my-pi/pi-tui";
+/**
+ * Transcript container that freezes the rendered output of every block except
+ * the bottom-most (live) one on terminals where committed native scrollback is
+ * immutable.
+ *
+ * On ED3-risk terminals with an unobservable viewport (ghostty/kitty/iTerm2/…)
+ * the renderer cannot clear saved lines (`\x1b[3J` may yank a reader) or query
+ * whether the user has scrolled, so any block that re-lays-out *after* it has
+ * scrolled past the viewport leaves a stale duplicate above the live region
+ * (a finalized assistant message re-wrapping, a tool preview collapsing to its
+ * compact result, a late async tool completion). The renderer's only safe move
+ * for such an offscreen edit is to not repaint — which is correct only if the
+ * committed region never changes underneath it.
+ *
+ * This container provides that guarantee: a block's render is snapshotted while
+ * it is the live (bottom-most) block, and once a newer block is appended it
+ * replays the snapshot instead of recomputing. Mutations after a block leaves
+ * live are intentionally deferred until the next checkpoint {@link thaw} (prompt
+ * submit → native-scrollback rebuild), where the whole transcript is replayed
+ * and any drift reconciles safely. On terminals that can rebuild history this
+ * freezing is unnecessary, so it renders every block live for full fidelity.
+ */
+export declare class TranscriptContainer extends Container {
+    #private;
+    invalidate(): void;
+    clear(): void;
+    /**
+     * Retire all frozen snapshots so the next render reflects each block's current
+     * state. Call at reconciliation checkpoints (prompt submit) where the whole
+     * transcript is replayed into native scrollback and any drift a frozen block
+     * accumulated is reconciled.
+     */
+    thaw(): void;
+    render(width: number): string[];
+}

package/dist/types/modes/interactive-mode.d.ts

@@ -23,6 +23,7 @@ import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
+import { TranscriptContainer } from "./components/transcript-container";
 import { type LoopLimitRuntime } from "./loop-limit";
 import { OAuthManualInputManager } from "./oauth-manual-input";
 import type { Theme } from "./theme/theme";
@@ -49,7 +50,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     agent: Agent;
     historyStorage?: HistoryStorage;
     ui: TUI;
-    chatContainer: Container;
+    chatContainer: TranscriptContainer;
     pendingMessagesContainer: Container;
     statusContainer: Container;
     todoContainer: Container;

package/dist/types/modes/rpc/rpc-types.d.ts

@@ -10,7 +10,7 @@ import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ContextUsage } from "../../extensibility/extensions/types";
 import type { SessionStats } from "../../session/agent-session";
-import type { TodoPhase } from "../../tools/todo-write";
+import type { TodoPhase } from "../../tools/todo";
 export type RpcCommand = {
     id?: string;
     type: "prompt";

package/dist/types/modes/theme/theme.d.ts

@@ -6,7 +6,7 @@ export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.
  */
-export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.agents" | "icon.cache" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.editing" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers";
+export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.agents" | "icon.cache" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.editing" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers";
 export type SpinnerType = "status" | "activity";
 export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
 /** Check if a string is a valid ThemeColor value */
@@ -17,7 +17,22 @@ export declare class Theme {
     #private;
     private readonly mode;
     private readonly symbolPreset;
+    /**
+     * Perceptual luma (0..1) of the status-line background — used to classify the
+     * theme light/dark. Undefined when it can't be resolved. Classified against the
+     * status line (the surface session accents render on) rather than the chat bubble
+     * (`userMessageBg`), which some themes (e.g. `porcelain`) style dark on an
+     * otherwise-light theme.
+     */
+    readonly statusLineLuminance: number | undefined;
     constructor(fgColors: Record<ThemeColor, string | number>, bgColors: Record<ThemeBg, string | number>, mode: ColorMode, symbolPreset: SymbolPreset, symbolOverrides: Partial<Record<SymbolKey, string>>, spinnerFramesOverrides?: Partial<Record<SpinnerType, string[]>>);
+    /** True when the active theme has a light status-line background. */
+    get isLight(): boolean;
+    /**
+     * Surface luminance to size session accents against on light themes; undefined on
+     * dark themes so accents stay vivid. Pass straight to `getSessionAccentHex`.
+     */
+    get accentSurfaceLuminance(): number | undefined;
     fg(color: ThemeColor, text: string): string;
     bg(color: ThemeBg, text: string): string;
     bold(text: string): string;
@@ -167,6 +182,10 @@ export declare class Theme {
         checked: string;
         unchecked: string;
     };
+    get radio(): {
+        selected: string;
+        unselected: string;
+    };
     get format(): {
         bullet: string;
         dash: string;

package/dist/types/plan-mode/plan-handoff.d.ts

@@ -0,0 +1,20 @@
+import { type LocalProtocolOptions } from "../internal-urls";
+/** The session's active plan, resolved for handoff into a subagent's context. */
+export interface OverallPlanReference {
+    /** The `local://` reference path (e.g. `local://my-feature.md`), kept for display. */
+    path: string;
+    /** The full plan markdown, as written to disk. */
+    content: string;
+}
+/**
+ * Load the session's active overall plan for subagent handoff.
+ *
+ * Returns the plan referenced by `planReferencePath` when it exists on disk with
+ * non-empty content, or `undefined` when there is no plan (the file is absent or
+ * empty). This mirrors `AgentSession.#buildPlanReferenceMessage`'s gating so a
+ * subagent sees exactly the plan the main agent treats as its active reference.
+ *
+ * Callers MUST skip this during plan mode itself — read-only plan exploration
+ * uses a different prompt and a draft plan should not be handed off as approved.
+ */
+export declare function loadOverallPlanReference(planReferencePath: string, localProtocolOptions: LocalProtocolOptions): Promise<OverallPlanReference | undefined>;

package/dist/types/plan-mode/plan-protection.d.ts

@@ -0,0 +1,12 @@
+import { type ProtectedToolContext } from "@oh-my-pi/pi-agent-core/compaction/tool-protection";
+/**
+ * Build a compaction protection matcher that keeps `read` results for the active
+ * plan file intact through prune/shake — the plan analog of skill-read
+ * protection. Matches both the canonical `local://PLAN.md` alias and the
+ * session's current plan reference path (e.g. a titled `local://<title>.md`), so
+ * the plan survives compaction whether the agent reads it by alias or by title.
+ *
+ * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
+ * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ */
+export declare function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean;

package/dist/types/session/agent-session.d.ts

@@ -43,7 +43,7 @@ import { type SecretObfuscator } from "../secrets/obfuscator";
 import { type ConfiguredThinkingLevel } from "../thinking";
 import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
 import type { CheckpointState } from "../tools/checkpoint";
-import { type TodoItem, type TodoPhase } from "../tools/todo-write";
+import { type TodoItem, type TodoPhase } from "../tools/todo";
 import type { ClientBridge } from "./client-bridge";
 import { type CustomMessage } from "./messages";
 import type { BranchSummaryEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";

package/dist/types/session/indexed-session-storage.d.ts

@@ -0,0 +1,59 @@
+import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from "./session-storage";
+export interface SessionStorageIndexEntry {
+    path: string;
+    size: number;
+    mtimeMs: number;
+}
+export interface SessionStorageBackend {
+    init(): Promise<void>;
+    loadIndex(): Promise<Iterable<SessionStorageIndexEntry>>;
+    readFull(path: string): Promise<string | null>;
+    readSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeFull(path: string, content: string, mtimeMs: number): Promise<void>;
+    append(path: string, line: string, mtimeMs: number): Promise<void>;
+    truncate(path: string, mtimeMs: number): Promise<void>;
+    remove(paths: string[]): Promise<void>;
+    move(src: string, dst: string, mtimeMs: number): Promise<void>;
+}
+export declare class IndexedSessionStorage implements SessionStorage {
+    #private;
+    constructor(backend: SessionStorageBackend);
+    initialize(): Promise<void>;
+    refresh(): Promise<void>;
+    drain(): Promise<void>;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(src: string, dst: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+    _writerClosed(writer: IndexedSessionStorageWriter): void;
+    _truncateForWriter(path: string): number;
+    _queueTruncate(path: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void>;
+    _appendForWriter(path: string, line: string): number;
+    _queueAppend(path: string, line: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void>;
+}
+declare class IndexedSessionStorageWriter implements SessionStorageWriter {
+    #private;
+    constructor(storage: IndexedSessionStorage, path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    });
+    writeLineSync(line: string): void;
+    writeLine(line: string): Promise<void>;
+    flush(): Promise<void>;
+    fsync(): Promise<void>;
+    close(): Promise<void>;
+    getError(): Error | undefined;
+}
+export {};

package/dist/types/session/redis-session-storage.d.ts

@@ -1,4 +1,4 @@
-import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from "./session-storage";
+import { IndexedSessionStorage } from "./indexed-session-storage";
 /**
  * Minimal subset of the `bun:redis` `RedisClient` surface used by
  * {@link RedisSessionStorage}. Keeping the contract narrow (and accepting any
@@ -7,6 +7,8 @@ import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from ".
  */
 export interface RedisSessionStorageClient {
     get(key: string): Promise<string | null>;
+    getrange(key: string, start: number, end: number): Promise<string>;
+    strlen(key: string): Promise<number>;
     set(key: string, value: string): Promise<unknown>;
     append(key: string, value: string): Promise<number>;
     del(...keys: string[]): Promise<number>;
@@ -26,7 +28,7 @@ export interface RedisSessionStorageOptions {
      */
     prefix?: string;
     /**
-     * Maximum number of keys returned per SCAN batch when warming the mirror.
+     * Maximum number of keys returned per SCAN batch when warming the metadata index.
      * Default 500.
      */
     scanCount?: number;
@@ -34,91 +36,16 @@ export interface RedisSessionStorageOptions {
 /**
  * Redis-backed implementation of {@link SessionStorage}. Each session JSONL
  * file maps to a Redis STRING key, with per-key metadata (mtime) tracked in a
- * single sibling HASH. An in-memory mirror is loaded on construction so the
- * interface's synchronous methods (`existsSync`, `statSync`, `listFilesSync`,
- * `readTextSync`, `writeTextSync`) keep their contracts — Bun's Redis client
- * is async only, and the persist hot path (`writer.writeLineSync`) cannot
- * wait on a network round-trip.
- *
- * Trade-offs vs `FileSessionStorage`:
- * - Mirror state is process-local. Two processes writing the same session key
- *   will diverge until one of them reloads via {@link refresh}. This matches
- *   `FileSessionStorage`'s existing single-writer assumption.
- * - `writeLineSync` updates the mirror synchronously and queues an async
- *   `APPEND`. The promise is awaited by `flush()` / `close()` / {@link drain}.
- *   A SIGKILL landing between the sync mirror update and the network round
- *   trip loses the last line; the file-backed implementation survives that
- *   window because bytes are handed to the kernel page cache before
- *   returning.
- * - Blobs (image data) and tool artifact files still live on disk via
- *   `BlobStore` / `ArtifactManager`. Those are out of scope for this storage.
+ * single sibling HASH. This process keeps only a metadata index (`size`,
+ * `mtimeMs`) in memory so synchronous `existsSync` / `statSync` /
+ * `listFilesSync` calls remain available without mirroring full content.
  */
-export declare class RedisSessionStorage implements SessionStorage {
-    #private;
-    private constructor();
+export declare class RedisSessionStorage extends IndexedSessionStorage {
     /**
-     * Warm the in-memory mirror with every existing session key under the
-     * configured prefix and return the ready-to-use storage. Must be awaited
-     * before passing the storage into `SessionManager.create()` so synchronous
-     * lookups (session resume, recent sessions, EPERM-backup recovery) see
-     * the existing keyspace.
+     * Warm the metadata index with every existing session key under the configured
+     * prefix and return the ready-to-use storage. Must be awaited before passing
+     * the storage into `SessionManager.create()` so synchronous lookups (session
+     * resume, recent sessions, EPERM-backup recovery) see the existing keyspace.
      */
     static create(options: RedisSessionStorageOptions): Promise<RedisSessionStorage>;
-    /**
-     * Re-scan Redis and replace the mirror's contents. Call this from a
-     * different process that took over a session keyspace, or after an
-     * out-of-band write made by another agent.
-     */
-    refresh(): Promise<void>;
-    /**
-     * Resolve once every pending background write (issued via `writeTextSync`
-     * or `writer.writeLineSync`) has been acknowledged by Redis. Throws if any
-     * background write failed since the last drain.
-     *
-     * Call this on graceful shutdown to avoid losing the last unflushed line.
-     * The session-manager's own `flush()` / `close()` already drain through
-     * the writer chain — this method exists for callers (test harnesses,
-     * subprocess-style consumers) that bypass the writer.
-     */
-    drain(): Promise<void>;
-    ensureDirSync(_dir: string): void;
-    existsSync(path: string): boolean;
-    writeTextSync(path: string, content: string): void;
-    readTextSync(path: string): string;
-    statSync(path: string): SessionStorageStat;
-    listFilesSync(dir: string, pattern: string): string[];
-    exists(path: string): Promise<boolean>;
-    readText(path: string): Promise<string>;
-    readTextPrefix(path: string, maxBytes: number): Promise<string>;
-    writeText(path: string, content: string): Promise<void>;
-    rename(src: string, dst: string): Promise<void>;
-    unlink(path: string): Promise<void>;
-    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
-    openWriter(path: string, options?: {
-        flags?: "a" | "w";
-        onError?: (err: Error) => void;
-    }): SessionStorageWriter;
-    _writerClosed(writer: RedisSessionStorageWriter): void;
-    /** Mirror-only mutation, no Redis call. Used by writers to update local state synchronously. */
-    _mirrorAppend(path: string, line: string): void;
-    /** Mirror-only mutation, no Redis call. Used by writers opened with `flags: "w"` to truncate. */
-    _mirrorTruncate(path: string): void;
-    _remoteTruncate(path: string): Promise<void>;
-    _remoteAppend(path: string, line: string): Promise<void>;
-    /** Record a writer's pending promise on the storage-level tail so `drain()` waits for it. */
-    _attachPending(promise: Promise<void>): void;
-}
-declare class RedisSessionStorageWriter implements SessionStorageWriter {
-    #private;
-    constructor(storage: RedisSessionStorage, path: string, options?: {
-        flags?: "a" | "w";
-        onError?: (err: Error) => void;
-    });
-    writeLineSync(line: string): void;
-    writeLine(line: string): Promise<void>;
-    flush(): Promise<void>;
-    fsync(): Promise<void>;
-    close(): Promise<void>;
-    getError(): Error | undefined;
 }
-export {};

package/dist/types/session/session-manager.d.ts

@@ -171,6 +171,21 @@ export interface SessionContext {
 }
 /** Lists session model strings to try when restoring, in fallback order. */
 export declare function getRestorableSessionModels(models: Readonly<Record<string, string>>, lastModelChangeRole: string | undefined): string[];
+/**
+ * Coarse lifecycle status of a session, derived from its last persisted message.
+ *
+ * - `complete` — the last assistant turn ended with no unanswered tool calls, i.e.
+ *   the agent yielded control back to the user.
+ * - `interrupted` — work was cut off mid-flight: a trailing assistant turn with
+ *   pending tool calls, a trailing tool result the agent never continued from, or
+ *   a length-truncated turn.
+ * - `aborted` — the last assistant turn was cancelled by the user.
+ * - `error` — the last assistant turn ended in an error.
+ * - `pending` — a trailing user message with no assistant reply persisted after it.
+ * - `unknown` — status could not be determined (empty/header-only session, or the
+ *   final message was larger than the tail window that was read).
+ */
+export type SessionStatus = "complete" | "interrupted" | "aborted" | "error" | "pending" | "unknown";
 export interface SessionInfo {
     path: string;
     id: string;
@@ -186,6 +201,11 @@ export interface SessionInfo {
     size: number;
     firstMessage: string;
     allMessagesText: string;
+    /**
+     * Coarse lifecycle status from the session's last persisted message. Optional:
+     * synthesized {@link SessionInfo}s (cross-project stubs, tests) leave it unset.
+     */
+    status?: SessionStatus;
 }
 export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getSessionName" | "getArtifactsDir" | "getArtifactManager" | "allocateArtifactPath" | "saveArtifact" | "getArtifactPath" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "getHeader" | "getEntries" | "getTree" | "getUsageStatistics" | "putBlob">;
 /** Exported for testing */

package/dist/types/session/session-storage.d.ts

@@ -22,12 +22,12 @@ export interface SessionStorage {
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
     writeTextSync(path: string, content: string): void;
-    readTextSync(path: string): string;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
-    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    /** Read the requested UTF-8 byte windows from the head and tail of the file. */
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
@@ -41,12 +41,11 @@ export declare class FileSessionStorage implements SessionStorage {
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
     writeTextSync(fpath: string, content: string): void;
-    readTextSync(fpath: string): string;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
-    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
@@ -70,13 +69,12 @@ export declare class MemorySessionStorage implements SessionStorage {
      * creates the entry. External callers should go through `openWriter()`
      * rather than touching the mirror directly.
      */
-    appendChunkSync(path: string, chunk: string): void;
-    readTextSync(path: string): string;
+    appendSync(path: string, chunk: string): void;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
-    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;