@wrongstack/core 0.313.1 → 0.316.2

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

@@ -82,6 +82,24 @@ export interface SubagentConfig {
      * caller input so a model cannot forge a shallower depth or larger budget.
      */
     spawnLineage?: SubagentSpawnLineage | undefined;
+    /**
+     * The conversation that ASKED for this spawn.
+     *
+     * The coordinator otherwise stamps a new worker with "which session is the
+     * host on right now", read from the host's own writer. In a single-session
+     * CLI those are the same answer. With four WebUI tabs sharing one process
+     * they are not: the host writer stays pinned to the boot tab, so every
+     * worker spawned from tabs 2-4 was filed under tab 1 — its lifecycle,
+     * budget and context events surfaced in the wrong roster, its spend was
+     * charged to the wrong conversation, and `stopSession` could not find it
+     * because nothing recorded who it belonged to.
+     *
+     * Set by the tools that spawn on an agent's behalf, from the run-pinned
+     * session of the caller. Absent (a host spawning for itself) the
+     * coordinator's live reading stands, which is what single-session hosts
+     * have always used.
+     */
+    originSessionId?: string | undefined;
     /**
      * Working directory for this subagent's tools. Defaults to the factory's
      * cwd. Goal sets this to a per-phase git worktree so parallel phases
@@ -116,6 +134,21 @@ export interface SubagentConfig {
      * → the factory's own default fallback behavior (usually the leader's config).
      */
     fallbackModels?: string[] | undefined;
+    /**
+     * Deterministic model tier for this subagent ('budget' | 'standard' |
+     * 'premium', or any user-defined level). Resolved at spawn time into a
+     * fallback profile, a budget, and runtime overrides. A tier only FILLS IN
+     * fields left unset — an explicit provider/model always wins over it.
+     */
+    tier?: string | undefined;
+    /**
+     * Budget field names the CALLER pinned explicitly (e.g. `delegate({ maxCostUsd })`).
+     * The tier layer never touches a pinned field: a number the user typed is a
+     * decision, while a roster default is just a default. Without this marker the
+     * two are indistinguishable at spawn time, because `applyRosterBudget` has
+     * already populated every budget field by then.
+     */
+    budgetPins?: readonly string[] | undefined;
     /**
      * Named live fallback profile for this subagent. Unlike `fallbackModels`, the
      * factory re-resolves this profile from ConfigStore on every provider attempt,
@@ -493,6 +526,16 @@ export interface SubagentRunContext {
     config: SubagentConfig;
     budget: SubagentBudget;
     signal: AbortSignal;
+    /**
+     * The session that spawned this subagent, fixed at spawn time.
+     *
+     * A worker belongs to one session for its whole life. Runners must stamp
+     * their events with THIS rather than re-reading the host's current session:
+     * with four tabs live, the host's session moves whenever the user switches
+     * tabs, and a late-firing event would then be filed under whichever tab
+     * happened to be in front.
+     */
+    sessionId?: string | undefined;
     /** Null until `setSubagentBridge` is called for this subagent. */
     bridge: AgentBridge | null;
     /** Publish a bounded in-memory snapshot that survives timeout races. */

package/dist/types/plugin.d.ts

@@ -1,7 +1,7 @@
 import type { Mailbox } from '../coordination/mailbox-types.js';
 import type { Notifier } from '../notifications/notifier.js';
 export type { Notifier };
-import type { ToolCallPipelinePayload } from '../core/agent.js';
+import type { ToolCallPipelinePayload } from '../core/agent-types.js';
 import type { AgentContext } from './context.js';
 import type { ExtensionRegistry } from '../extension/registry.js';
 import type { Container } from '../kernel/container.js';

package/dist/types/provider.d.ts

@@ -103,6 +103,21 @@ export interface Usage {
 export declare function effectiveInputTokens(usage: Usage): number;
 /** Prompt tokens that were not served by a cache read. */
 export declare function freshInputTokens(usage: Usage): number;
+/**
+ * Every token this request moved — the complete prompt the model loaded plus
+ * what it generated.
+ *
+ * The single definition of `SessionSummary.tokenTotal`. Three call sites
+ * compute that field (the live writer's tracker, the disk-rebuild summary
+ * builder, and the SQLite catalog's transcript summarizer) and they had
+ * drifted: two summed only `input + output` while the third also counted the
+ * cache buckets. With prompt caching on, `cacheRead` is the bulk of a real
+ * prompt, so the narrow reading under-reported long sessions by more than an
+ * order of magnitude — one measured session listed 118,719 tokens against an
+ * actual 2,466,978. Route every tokenTotal through here so the three cannot
+ * disagree again.
+ */
+export declare function totalUsageTokens(usage: Usage): number;
 /**
  * Cache-read share of the complete prompt context, normalized to [0, 1].
  *

package/dist/types/runtime-capability-manifest.d.ts

@@ -69,7 +69,7 @@ export declare const RUNTIME_CAPABILITY_MANIFEST: readonly [{
     readonly id: 'coordination.mailbox';
     readonly pack: 'fleet';
     readonly exposure: 'direct';
-    readonly tools: readonly ["mailbox", "mail_send", "mail_inbox", "fleet_status"];
+    readonly tools: readonly ["mailbox", "mail_send", "mail_inbox", "fleet_status", "session_note"];
 }, {
     readonly id: 'fleet.delegate';
     readonly pack: 'fleet';

package/dist/types/secret-scrubber.d.ts

@@ -1,5 +1,20 @@
 export interface SecretScrubber {
     scrub(text: string): string;
     scrubObject<T>(obj: T): T;
+    /**
+     * Same redaction as {@link scrubObject}, but the result MAY SHARE structure
+     * with the input: any subtree that needed no redaction is returned by
+     * reference instead of being rebuilt.
+     *
+     * Only call this on a graph you exclusively own and will not mutate — a
+     * freshly `JSON.parse`d journal line, say. On anything still referenced
+     * elsewhere (a live conversation message queued for an async write), the
+     * shared subtrees would alias state that can still change underneath the
+     * consumer; use {@link scrubObject} there.
+     *
+     * Optional so existing implementations (and the object literals tests hand
+     * in) stay valid; callers fall back to {@link scrubObject}.
+     */
+    scrubObjectShared?<T>(obj: T): T;
 }
 //# sourceMappingURL=secret-scrubber.d.ts.map

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

@@ -31,9 +31,40 @@ export interface SessionMarker {
     source: SessionEvent['type'];
     level: SessionMarkerLevel;
     text: string;
-    /** Set only for the `agent_*` sources. */
+    /** Set only for the `agent_*` and `delegate_*` sources. */
     agentId?: string | undefined;
+    /**
+     * The source event's own fields, for the sources a surface renders as
+     * something richer than a line of text.
+     *
+     * `text` stays the fallback every surface can always use. But the TUI draws
+     * a delegation as a labelled subagent row with its own icon, colour and
+     * compact stat line, and the WebUI as a two-line assistant message — both
+     * built from the structured payload, live. Handing replay only the rendered
+     * sentence would have forced those surfaces to show something they never
+     * showed while running, which is the exact divergence this module exists to
+     * prevent. Kept to the few sources that need it, and JSON-serializable so it
+     * survives the wire alongside the rest of the marker.
+     */
+    detail?: SessionMarkerDetail | undefined;
 }
+/** Structured payload for the marker sources whose surfaces render richly. */
+export type SessionMarkerDetail = {
+    kind: 'delegate_started';
+    target: string;
+    task: string;
+} | {
+    kind: 'delegate_completed';
+    target: string;
+    task: string;
+    ok: boolean;
+    status?: string | undefined;
+    summary: string;
+    durationMs: number;
+    iterations: number;
+    toolCalls: number;
+    costUsd?: number | undefined;
+};
 /**
  * Every event type that projects to a marker. Conversation-bearing events
  * (`user_input`, `llm_response`, `tool_*`) are deliberately excluded — those
@@ -41,15 +72,6 @@ export interface SessionMarker {
  * `message_appended` journal replay identically.
  */
 export declare const SESSION_MARKER_EVENT_TYPES: ReadonlySet<SessionEvent['type']>;
-/**
- * The subset chat-shaped surfaces (WebUI, SimpleUI, HQ Live Console) render.
- *
- * `checkpoint` is excluded: one is written per user prompt
- * (`agent-loop.ts` → `writeCheckpoint`), so in a chat transcript it would be a
- * line restating the user message immediately next to it. Dense timeline
- * surfaces like the TUI use {@link SESSION_MARKER_EVENT_TYPES} instead, where
- * the checkpoint marker doubles as a `/rewind` target hint.
- */
 export declare const CHAT_MARKER_SOURCES: ReadonlySet<SessionEvent['type']>;
 /**
  * Project one session event to a marker, or `null` when the event carries no
@@ -69,6 +91,11 @@ export declare function projectSessionMarkers(events: readonly SessionEvent[], s
  * as `user`/`system`-role messages by the agent loop at runtime (mailbox,
  * fleet pulse, loop detector, resume validation notices) but should NOT appear
  * in the human-facing chat history on session resume/replay.
+ *
+ * Also covers routing-noise error bubbles that the WebUI client has already
+ * swallowed live (`handleError` drops them) but that earlier turns may have
+ * persisted to the on-disk transcript — replay must not resurrect them into
+ * the human-visible chat.
  */
 export declare const SYSTEM_INJECTION_PREFIXES: readonly string[];
 /**

package/dist/types/session-markers.js

@@ -5,7 +5,7 @@ import {
   isSystemInjectedMessage,
   projectSessionMarkers,
   sessionEventToMarker
-} from "../chunk-KSJ5UTP7.js";
+} from "../chunk-ULMAQV3T.js";
 export {
   CHAT_MARKER_SOURCES,
   SESSION_MARKER_EVENT_TYPES,

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

@@ -0,0 +1,197 @@
+import type { Message } from './messages.js';
+import { type SessionMarker, type SessionMarkerDetail } from './session-markers.js';
+import type { SessionEvent } from './session.js';
+/** An image the user attached to a prompt, as it survives in the journal. */
+export interface SessionTimelineImage {
+    mediaType?: string | undefined;
+    /** Base64 payload, when the block carried one. */
+    data?: string | undefined;
+    /** Remote URL, when the block referenced one instead. */
+    url?: string | undefined;
+}
+/**
+ * Tool-call metadata that lives in `tool_call_end` events rather than in the
+ * conversation.
+ *
+ * The message journal records WHICH tool ran with WHICH arguments and WHAT it
+ * returned; how long it took and how much it produced is audit detail, in a
+ * separate event keyed by the same `tool_use` id. The TUI reads both because
+ * it holds the raw event array; the browser surfaces are handed a projection
+ * over the wire, so this is the shape that projection carries.
+ */
+export interface SessionToolMeta {
+    /** The `tool_use` id this describes. */
+    id: string;
+    name?: string | undefined;
+    durationMs?: number | undefined;
+    outputBytes?: number | undefined;
+    outputTokens?: number | undefined;
+    outputLines?: number | undefined;
+    ok?: boolean | undefined;
+    /** Subagent that ran the tool; absent = the session's leader. */
+    agentId?: string | undefined;
+}
+interface TimelineEntryBase {
+    ts: string;
+}
+export interface SessionTimelineUserEntry extends TimelineEntryBase {
+    kind: 'user';
+    text: string;
+    /** Present only when the prompt carried image blocks. */
+    images?: SessionTimelineImage[] | undefined;
+}
+export interface SessionTimelineAssistantEntry extends TimelineEntryBase {
+    kind: 'assistant';
+    text: string;
+    /**
+     * True when this prose ended its turn. A message carrying a `tool_use` block
+     * stopped for a tool call, so its text is mid-turn — the surfaces use this to
+     * decide whether a `<nextsteps>` panel may appear.
+     */
+    final: boolean;
+}
+/** A conversation message with `role: 'system'` — resume notices and the like. */
+export interface SessionTimelineSystemEntry extends TimelineEntryBase {
+    kind: 'system';
+    text: string;
+}
+export interface SessionTimelineThinkingEntry extends TimelineEntryBase {
+    kind: 'thinking';
+    text: string;
+    /** 1-based ordinal across the whole timeline; surfaces label iterations with it. */
+    index: number;
+}
+export interface SessionTimelineToolEntry extends TimelineEntryBase {
+    kind: 'tool';
+    /** The provider's `tool_use` id, or the `tool_result`'s id for an orphan result. */
+    toolUseId: string;
+    name: string;
+    input?: unknown;
+    /** Untruncated result body. Surfaces decide their own preview length. */
+    output?: string | undefined;
+    /**
+     * `undefined` while a call has no result in the journal — the run was still
+     * executing it when the process stopped. A surface renders that as "running"
+     * or "interrupted"; it is NOT a failure, and reporting it as one is what the
+     * SimpleUI replay used to do.
+     */
+    ok?: boolean | undefined;
+    durationMs?: number | undefined;
+    outputBytes?: number | undefined;
+    outputTokens?: number | undefined;
+    outputLines?: number | undefined;
+    agentId?: string | undefined;
+}
+export interface SessionTimelineMarkerEntry extends TimelineEntryBase {
+    kind: 'marker';
+    source: SessionEvent['type'];
+    level: SessionMarker['level'];
+    text: string;
+    agentId?: string | undefined;
+    /** See {@link SessionMarker.detail} — structured fields for rich sources. */
+    detail?: SessionMarkerDetail | undefined;
+}
+export type SessionTimelineEntry = SessionTimelineUserEntry | SessionTimelineAssistantEntry | SessionTimelineSystemEntry | SessionTimelineThinkingEntry | SessionTimelineToolEntry | SessionTimelineMarkerEntry;
+/**
+ * Where a message's thinking blocks land relative to its prose.
+ *
+ * Not a style choice — it is what the surface did LIVE, and resume has to
+ * match the surface it is resuming into:
+ *
+ * - `'inline'` — one entry per thinking block, before the prose, in provider
+ *   block order. The TUI and SimpleUI stream thinking as it arrives and leave
+ *   it where it fell.
+ * - `'merged-after'` — one entry per message, carrying every thinking block
+ *   joined, emitted after that message's prose and tool calls. The WebUI keeps
+ *   a transient thinking bubble during a run and only commits the archived log
+ *   when the iteration completes, which is after the prose is on screen.
+ */
+export type ThinkingPlacement = 'inline' | 'merged-after';
+/**
+ * How a message's text blocks relate to the tool calls between them.
+ *
+ * Again a record of what the surface did LIVE, not a preference:
+ *
+ * - `'split'` — a text run becomes its own entry wherever a tool interrupts
+ *   it, so prose that followed a tool stays after that tool. The TUI and the
+ *   WebUI render a fresh bubble per run.
+ * - `'join'` — every text block of a message becomes ONE entry, emitted before
+ *   the message's tool entries. The SimpleUI streams a whole iteration into a
+ *   single bubble and lists tool calls beside it, so splitting would invent
+ *   bubbles that were never on screen.
+ */
+export type TextBlockMode = 'split' | 'join';
+export interface ProjectSessionTimelineInput {
+    /** The reconstructed conversation, as `SessionStore.load()` rebuilds it. */
+    messages: readonly Message[];
+    /**
+     * Raw journal events. Callers holding the JSONL (the TUI, the servers) pass
+     * this and markers/toolMeta are projected from it.
+     */
+    events?: readonly SessionEvent[] | undefined;
+    /** Pre-projected markers, for callers that received them over the wire. */
+    markers?: readonly SessionMarker[] | undefined;
+    /** Pre-projected tool metadata, for callers that received it over the wire. */
+    toolMeta?: readonly SessionToolMeta[] | undefined;
+    /**
+     * Which event types project to markers. Defaults to the dense
+     * {@link SESSION_MARKER_EVENT_TYPES}; chat-shaped surfaces pass
+     * `CHAT_MARKER_SOURCES`. Ignored when `markers` is supplied — the sender
+     * already applied its own set.
+     */
+    markerSources?: ReadonlySet<SessionEvent['type']> | undefined;
+    /** See {@link ThinkingPlacement}. Defaults to `'inline'`. */
+    thinkingPlacement?: ThinkingPlacement | undefined;
+    /** See {@link TextBlockMode}. Defaults to `'split'`. */
+    textBlocks?: TextBlockMode | undefined;
+    /**
+     * Glue between adjacent text blocks of one run. Defaults to `''` — the
+     * provider already streamed them as one continuous body, and inserting a
+     * separator would put a break where the live render had none.
+     */
+    textSeparator?: string | undefined;
+    /**
+     * Drop conversation messages the agent loop injected for the model's benefit
+     * (mailbox, fleet pulse, loop detector, resume notices). Defaults to true —
+     * every surface hides them, and a surface that wants the raw journal should
+     * read the events instead.
+     */
+    hideSystemInjections?: boolean | undefined;
+}
+/** Project the `tool_call_end` records of an event stream, keyed by tool id. */
+export declare function projectSessionToolMeta(events: Iterable<SessionEvent>): SessionToolMeta[];
+/**
+ * Size of the LAST prompt this session sent, from its journal.
+ *
+ * This is the number the context-fill bar means: how full the window was when
+ * the conversation last went to the model. Live, `ctx.lastRequestTokens` holds
+ * exactly that (the pre-flight total). Every resume path instead reached for
+ * `SessionData.usage.input`, which is the SUM of every request the session has
+ * ever made — so a long session came back claiming a nine-million-token
+ * context on a one-million-token model. Cumulative totals belong in the cost
+ * and usage readouts; they are never a fill source.
+ *
+ * The last `llm_response` carries that request's own usage, and its prompt is
+ * everything the provider counted on the way in: fresh input plus whatever it
+ * served or wrote through the cache — `effectiveInputTokens` in `provider.ts`,
+ * inlined here because this module must stay importable from a browser bundle
+ * and that one pulls a value chain behind it. Scanned from the end, so a 100k-
+ * event journal costs one step. Returns `undefined` when the session never reached
+ * the model — the caller must then leave the estimate unset rather than
+ * publish a zero, which reads as "0% full" instead of "not known yet".
+ */
+export declare function projectLastRequestTokens(events: readonly SessionEvent[] | undefined): number | undefined;
+/**
+ * Merge a session's conversation and audit streams into one ordered timeline.
+ *
+ * Ordering is a two-pointer merge of two sequences that are each already
+ * chronological — the message backbone by construction, the markers by journal
+ * order — so the conversation is never reordered: markers are only inserted
+ * between existing turns, and a tie keeps the backbone entry first. That is
+ * deliberately NOT a sort over the union: message timestamps repeat (every
+ * block of one message shares its `ts`), and sorting a repeated key moves tool
+ * calls away from the prose they belong to.
+ */
+export declare function projectSessionTimeline(input: ProjectSessionTimelineInput): SessionTimelineEntry[];
+export {};
+//# sourceMappingURL=session-timeline.d.ts.map

package/dist/types/session-timeline.js

@@ -0,0 +1,12 @@
+import {
+  projectLastRequestTokens,
+  projectSessionTimeline,
+  projectSessionToolMeta
+} from "../chunk-3BDV7RL3.js";
+import "../chunk-ULMAQV3T.js";
+export {
+  projectLastRequestTokens,
+  projectSessionTimeline,
+  projectSessionToolMeta
+};
+//# sourceMappingURL=session-timeline.js.map

package/dist/types/session.d.ts

@@ -65,7 +65,28 @@ export interface SessionMetadata {
  * The only files that live inside the project tree are the committed
  * `.wrongstack/AGENTS.md` and `.wrongstack/skills/`.
  */
-export type SessionEvent = {
+export type SessionEvent = SessionEventVariant & SessionEventAttribution;
+/**
+ * Attribution stamped onto a journal event by the WRITER, never by the
+ * producer that built it.
+ *
+ * A leader's JSONL can carry events produced by its subagents: the
+ * parent-interleaved writer (`createParentSubagentSessionWriter`) forwards a
+ * subagent's appends into the leader's journal because that subagent has no
+ * journal of its own. Without a stamp those appends are indistinguishable
+ * from the leader's, so a transcript reader cannot say which agent ran which
+ * tool. `withAgentAttribution` sets this at the writer boundary — the one
+ * place that knows whose writer it is — so no emit site has to remember.
+ *
+ * Absent means "the session's own leader". Old journals have no stamp at all,
+ * which reads the same way and is correct: they predate subagent interleaving
+ * being attributable.
+ */
+export interface SessionEventAttribution {
+    /** Subagent that produced this event; absent = the session's leader. */
+    agentId?: string | undefined;
+}
+type SessionEventVariant = {
     type: 'session_start';
     ts: string;
     id: string;
@@ -105,6 +126,21 @@ export type SessionEvent = {
     content: ContentBlock[];
     stopReason: string;
     usage: Usage;
+    /**
+     * Model that produced this response and billed this `usage`.
+     *
+     * Optional because logs written before this field existed omit it —
+     * never because a live writer may skip it. `usage` is the only place
+     * token counts are journaled, so without these two fields the journal
+     * cannot answer "which model burned these tokens": `session_start`
+     * records only the model the session OPENED with (a mid-session switch
+     * or a fallback rotation leaves it stale), and `llm_request` carries
+     * `model` but no provider. Readers must still tolerate `undefined` and
+     * fall back to the nearest preceding `llm_request` / `session_start`.
+     */
+    model?: string | undefined;
+    /** Provider id that served this response. See {@link model}. */
+    provider?: string | undefined;
 } | {
     type: 'tool_use';
     ts: string;
@@ -250,26 +286,121 @@ export type SessionEvent = {
     ts: string;
     agentId: string;
     role: string;
+} | {
+    /**
+     * Binds a spawned agent to the transcript it writes into.
+     *
+     * Separate from `agent_spawned` because the two facts are learned in
+     * different places: the fleet layer emits `agent_spawned` once the
+     * coordinator hands back an id, while the writer is built one layer
+     * down in the subagent factory, which has no channel back to that emit
+     * site. Threading one would have changed five signatures for a fact
+     * that is naturally its own record — and would still be optional on
+     * `agent_spawned`, since an agent running on the parent-interleaved
+     * writer never gets a transcript of its own and emits no link at all.
+     *
+     * Readers join on `agentId` within the session.
+     */
+    type: 'agent_session_linked';
+    ts: string;
+    agentId: string;
+    /** The subagent journal's own session id. */
+    agentSessionId: string;
+    /**
+     * Absolute path of the subagent's JSONL at the time it was opened.
+     * Absent for in-memory writers (tests, ephemeral runs), which have a
+     * session id but no file.
+     */
+    transcriptPath?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    /** Set when this agent was spawned by another agent, not the leader. */
+    parentAgentId?: string | undefined;
 } | {
     type: 'agent_stopped';
     ts: string;
     agentId: string;
+    /** Why the agent ended. Absent in journals written before this field. */
+    reason?: 'completed' | 'aborted' | 'failed' | 'evicted' | undefined;
+    /** This agent's own cumulative spend, when the stopper knows it. */
+    usage?: Usage | undefined;
 } | {
     type: 'agent_error';
     ts: string;
     agentId: string;
     error: string;
 } | {
-    type: 'spec_parsed';
+    /**
+     * A `delegate` tool call handing work to a subagent.
+     *
+     * Distinct from `agent_spawned`, which records that an agent exists.
+     * This records that the LEADER stopped and waited on it, which is the
+     * thing the transcript shows: every surface renders a delegation line
+     * live (the TUI even suppresses the generic tool card in its favour),
+     * and none of it reached disk — so a resumed session showed a gap where
+     * minutes of delegated work had happened.
+     */
+    type: 'delegate_started';
+    ts: string;
+    /** Resolved roster role or free-form subagent name. */
+    target: string;
+    /** The instruction handed to the subagent. */
+    task: string;
+    subagentId?: string | undefined;
+} | {
+    type: 'delegate_completed';
+    ts: string;
+    target: string;
+    task: string;
+    ok: boolean;
+    /** `success` | `timeout` | `host_timeout` | `stopped` | … */
+    status?: string | undefined;
+    /** One-line human summary, as the live surfaces render it. */
+    summary: string;
+    durationMs: number;
+    iterations: number;
+    toolCalls: number;
+    costUsd?: number | undefined;
+    subagentId?: string | undefined;
+} | {
+    /**
+     * The loop detector acted on a repeating run.
+     *
+     * Only `action: 'cut'` is worth a record: a `steer` is an in-band nudge
+     * the model absorbs, while a cut ENDS the turn — and without this the
+     * run came back as a bare `max_iterations` with nothing saying why.
+     */
+    type: 'loop_detected';
     ts: string;
-    specId: string;
-    title: string;
-    completeness: number;
+    /** Comma-separated tool names, or empty for a pure message loop. */
+    tools: string;
+    repeatCount: number;
+    iteration: number;
+    kind?: 'tool' | 'message' | 'mixed' | undefined;
+    action?: 'steer' | 'cut' | undefined;
 } | {
-    type: 'spec_analyzed';
+    /**
+     * The active provider/model changed mid-session.
+     *
+     * `reason: 'fallback'` is the automatic switch after a provider failure;
+     * `'user'` is an explicit `/model` or UI change. Either way the rest of
+     * the transcript was produced by a different model than the one
+     * `session_start` names, and a reader with no record of the switch
+     * attributes it all to the first one.
+     */
+    type: 'model_switched';
     ts: string;
-    specId: string;
-    gaps: string[];
+    from?: {
+        providerId: string;
+        model: string;
+    } | undefined;
+    to: {
+        providerId: string;
+        model: string;
+    };
+    reason: 'fallback' | 'user';
+    /** HTTP status that triggered an automatic fallback, when there was one. */
+    status?: number | undefined;
 } | {
     type: 'skill_activated';
     ts: string;
@@ -530,7 +661,11 @@ export interface SessionData {
      * in flight (crash/interrupt). Computed during replay BEFORE adjacency
      * repair strips them. `resume()` surfaces this as an informational notice so
      * the user/model know work was interrupted; the tools are NOT re-executed.
-     * Undefined for events-only loads (no message reconstruction).
+     *
+     * Only present when at least one call was left open: **absent means none**,
+     * never zero (see `load-session-data.ts`). It is also absent for
+     * events-only loads, which reconstruct no messages to count. Read it as
+     * `data.pendingToolUseCount ?? 0` rather than testing for `undefined`.
      */
     pendingToolUseCount?: number | undefined;
     /**
@@ -561,9 +696,28 @@ export interface ForkedSession {
     /** Available for checkpoint forks captured by workspace-CAS-aware writers. */
     workspaceCheckpoint?: WorkspaceCheckpointRef | undefined;
 }
+/**
+ * Byte-level progress for a session JSONL load. `loadedBytes` counts raw
+ * source bytes consumed so far (newline-inclusive approximation) and
+ * `totalBytes` is the source file size at load start.
+ */
+export interface SessionLoadProgress {
+    loadedBytes: number;
+    totalBytes: number;
+}
 export interface SessionStore {
     create(meta: Omit<SessionMetadata, 'startedAt'>): Promise<SessionWriter>;
-    load(id: string): Promise<SessionData>;
+    /**
+     * Read a session without claiming it for writing.
+     *
+     * `onLoadProgress` mirrors {@link SessionStore.resume} — the implementation
+     * has always accepted it, but the interface did not declare it, so the only
+     * caller that can stream progress for a read-only view (a resume falling
+     * back to showing the transcript it could not attach to) had to drop it and
+     * leave the user staring at a frozen screen for the length of a 131 MB
+     * parse. Implementations may ignore it.
+     */
+    load(id: string, onLoadProgress?: (progress: SessionLoadProgress) => void): Promise<SessionData>;
     /**
      * Open an existing session for append, returning both a writer that
      * continues writing to the same JSONL file and the replayed state
@@ -571,8 +725,12 @@ export interface SessionStore {
      * `session_resumed` marker is appended for audit. New writers may also
      * persist the exact conversation journal (`message_*` events); legacy logs
      * containing only user/assistant/tool events remain replayable.
+     *
+     * Optional `onLoadProgress` streams byte-level parse progress for large
+     * journals so callers can surface a live indicator; implementations may
+     * ignore it, and a warm load cache reports a single completed event.
      */
-    resume(id: string): Promise<ResumedSession>;
+    resume(id: string, onLoadProgress?: (progress: SessionLoadProgress) => void): Promise<ResumedSession>;
     /**
      * Create a non-destructive child journal from a persisted parent boundary.
      * Parent file snapshots are intentionally not inherited as rewind authority;
@@ -654,6 +812,8 @@ export interface SessionStore {
 }
 export interface SessionWriter {
     readonly id: string;
+    /** Original session start timestamp, used by resumed surfaces to keep uptime stable. */
+    readonly startedAt?: string | undefined;
     /**
      * Session-level trace ID for correlating storage events with agent
      * iterations in observability pipelines. Generated once at Context
@@ -823,4 +983,5 @@ export interface SessionWriter {
      */
     clearInFlightMarker(reason: 'clean' | 'aborted' | 'recovered'): Promise<void>;
 }
+export {};
 //# sourceMappingURL=session.d.ts.map