@wrongstack/core 0.313.0 → 0.316.1

package/dist/storage/input-history-store.d.ts

@@ -46,10 +46,8 @@ export declare class InputHistoryStore {
     private scrubAndFilter;
     /**
      * Heuristic: did the scrubber actually redact anything? DefaultSecretScrubber
-     * replaces matches with "***REDACTED***", so a residual marker means a secret
-     * was detected. Subclasses of SecretScrubber that use a different sentinel
-     * can be accommodated by widening this check in the future; for now the
-     * marker check covers the shipped scrubber.
+     * replaces matches with "[REDACTED:<type>]" (and legacy mocks with
+     * "***REDACTED***"), so a residual marker means a secret was detected.
      */
     private looksRedacted;
 }

package/dist/storage/memory-curator.d.ts

@@ -0,0 +1,133 @@
+import type { OneShotOrchestrator } from '../execution/one-shot-llm.js';
+import type { AfterRunHook, AgentExtension } from '../extension/extension-points.js';
+import type { MemoryStore } from '../types/memory.js';
+import type { Provider } from '../types/provider.js';
+export type CuratorSageKind = 'fact' | 'decision' | 'convention' | 'preference' | 'anti_pattern' | 'warning' | 'workflow' | 'bug_root_cause' | 'file_note' | 'symbol_note' | 'command_note';
+export interface CuratorMemoryAnchor {
+    type: 'file' | 'directory' | 'symbol' | 'package' | 'command' | 'test' | 'git';
+    path?: string | undefined;
+    symbol?: string | undefined;
+    command?: string | undefined;
+}
+export interface CuratorSageRecord {
+    id: string;
+    text: string;
+    scope?: string | undefined;
+    kind?: string | undefined;
+    status?: string | undefined;
+    importance?: number | undefined;
+    confidence?: number | undefined;
+    freshness?: number | undefined;
+    tags?: string[] | undefined;
+    anchors?: CuratorMemoryAnchor[] | undefined;
+    persistence?: 'permanent' | 'long_lived' | 'short_lived' | undefined;
+    contradicts?: string[] | undefined;
+    supersedes?: string[] | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+}
+export interface CuratorSageCandidate {
+    id: string;
+    memoryId?: string | undefined;
+    reason?: string | undefined;
+    suggestedAction?: string | undefined;
+}
+export interface CuratorSage {
+    rememberSage(input: {
+        text: string;
+        scope?: string | undefined;
+        kind?: CuratorSageKind | undefined;
+        tags?: string[] | undefined;
+        importance?: number | undefined;
+        confidence?: number | undefined;
+        persistence?: 'permanent' | 'long_lived' | 'short_lived' | undefined;
+        anchors?: CuratorMemoryAnchor[] | undefined;
+        sources?: Array<{
+            type: string;
+            sessionId?: string | undefined;
+        }> | undefined;
+        supersedes?: string[] | undefined;
+        contradicts?: string[] | undefined;
+    }): Promise<{
+        id?: string;
+    } | unknown>;
+    getSage?(id: string): Promise<CuratorSageRecord | null>;
+    updateSage?(id: string, patch: Partial<CuratorSageRecord>): Promise<unknown>;
+    deleteSage?(id: string, reason?: string): Promise<void>;
+    listCandidates?(includeResolved?: boolean): Promise<CuratorSageCandidate[]>;
+    retrieveForPath?(opts: {
+        path: string;
+        limit?: number;
+        includeStatuses?: string[];
+    }): Promise<CuratorSageRecord[]>;
+    searchSage?(query: string, opts?: {
+        limit?: number;
+        scope?: 'project';
+        includeStatuses?: string[];
+    }): Promise<unknown[]>;
+}
+export type CuratorOperation = {
+    action: 'supersede';
+    targetId: string;
+    reason: string;
+    supersededBy?: string | undefined;
+} | {
+    action: 'contradict';
+    targetId: string;
+    reason: string;
+    contradictsWith?: string | undefined;
+} | {
+    action: 'merge';
+    targetIds: string[];
+    text: string;
+    type?: string | undefined;
+    priority?: string | undefined;
+    confidence?: number | undefined;
+    tags?: string[] | undefined;
+    anchors?: CuratorMemoryAnchor[] | undefined;
+    reason: string;
+} | {
+    action: 'split';
+    targetId: string;
+    items: Array<{
+        text: string;
+        type?: string | undefined;
+        priority?: string | undefined;
+        confidence?: number | undefined;
+        tags?: string[] | undefined;
+        anchors?: CuratorMemoryAnchor[] | undefined;
+    }>;
+    reason: string;
+} | {
+    action: 'recalibrate';
+    targetId: string;
+    importance?: number | undefined;
+    confidence?: number | undefined;
+    freshness?: number | undefined;
+    status?: string | undefined;
+    reason: string;
+} | {
+    action: 'keep';
+    targetId: string;
+    reason: string;
+};
+export interface SessionMemoryCuratorOptions {
+    memoryStore: MemoryStore;
+    Sage?: CuratorSage | undefined;
+    provider?: Provider | undefined;
+    model?: string | undefined;
+    maxTargetMemories?: number | undefined;
+    oneShotOrchestrator?: OneShotOrchestrator | undefined;
+}
+export declare class SessionMemoryCurator implements AgentExtension {
+    name: string;
+    owner: string;
+    private readonly Sage?;
+    private readonly provider?;
+    private readonly model?;
+    private readonly maxTargetMemories;
+    private readonly oneShotOrchestrator?;
+    constructor(opts: SessionMemoryCuratorOptions);
+    afterRun: AfterRunHook;
+}
+//# sourceMappingURL=memory-curator.d.ts.map

package/dist/storage/session-agent-attribution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Writer-boundary agent attribution.
+ *
+ * A leader's journal can contain events that a SUBAGENT produced. That is not
+ * a bug: `createParentSubagentSessionWriter` deliberately forwards a
+ * subagent's appends into the leader's JSONL when that subagent has no journal
+ * of its own, because the leader's file is the one `/rewind` and the resume
+ * timeline read. What WAS a bug is that the forwarded events arrived
+ * unlabelled — a subagent's `tool_call_start` looked exactly like the
+ * leader's, so no reader could attribute the work.
+ *
+ * Stamping belongs here rather than at the emit sites. Every producer
+ * (director, fleet manager, tool loop, context) appends through a writer it
+ * was handed and has no idea whether that writer is its own or a parent's;
+ * the wrapper is the single place that does know. Doing it at the boundary
+ * also means a new emit site cannot forget.
+ *
+ * The stamp is never overwritten: an event that already carries an `agentId`
+ * came from a deeper agent whose own wrapper labelled it first, and that
+ * inner attribution is the more specific truth.
+ */
+import type { SessionEvent, SessionWriter } from '../types/session.js';
+/** Apply `agentId` to an event unless it already carries one. */
+export declare function stampAgentId(event: SessionEvent, agentId: string): SessionEvent;
+/**
+ * Wrap a writer so every event appended through it is attributed to `agentId`.
+ *
+ * Only `append`/`appendBatch` are intercepted. `recordFileChange` and
+ * `recordSideEffect` build their events inside the underlying writer, so a
+ * wrapper cannot reach them — those paths keep the writer's own identity,
+ * which for the parent-interleaved case is the correct owner anyway (the
+ * parent files them against its own prompt index so `/rewind` can undo them).
+ *
+ * An empty `agentId` returns the writer untouched rather than stamping an
+ * empty string, so a caller that has not resolved a name yet degrades to
+ * today's behaviour instead of writing a meaningless label.
+ */
+export declare function withAgentAttribution(writer: SessionWriter, agentId: string): SessionWriter;
+//# sourceMappingURL=session-agent-attribution.d.ts.map

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

@@ -0,0 +1,109 @@
+import type { SecretScrubber } from '../types/secret-scrubber.js';
+export type SessionLifecycleBoundary = 'session_start' | 'in_flight_start' | 'in_flight_end' | 'session_end';
+export type SessionFindingCode = 
+/** Lines the loader cannot parse. It skips them silently, so they are invisible. */
+'unparsable_lines'
+/** The file does not end in a newline — a process died mid-write. */
+ | 'truncated_tail'
+/** No `session_start`: the journal never recorded what it was. */
+ | 'missing_session_start'
+/** Last boundary is `in_flight_start` — the process died mid-turn. */
+ | 'died_mid_turn'
+/** No `session_end`: closed by a kill, not by a clean exit. */
+ | 'never_closed'
+/** No events at all. */
+ | 'empty'
+/** No `.summary.json` sidecar; the picker has no title for it. */
+ | 'missing_summary'
+/** The sidecar predates the transcript, so its counts are behind. */
+ | 'stale_summary'
+/** Large enough that opening it is a visible wait. */
+ | 'oversized';
+export interface SessionFinding {
+    code: SessionFindingCode;
+    severity: 'error' | 'warn' | 'info';
+    detail: string;
+    /** Present when `repairSessionSummaries` can resolve this finding. */
+    fix?: string;
+}
+export interface SessionDiagnosis {
+    /** Store-relative id, e.g. `2026-08-29/sess_01M16QFGAJ…`. */
+    id: string;
+    file: string;
+    bytes: number;
+    /** Physical lines, including any that failed to parse. */
+    lines: number;
+    unparsableLines: number;
+    /** Bytes held by superseded conversation snapshots — reported, never rewritten. */
+    snapshotBytes: number;
+    lastBoundary: SessionLifecycleBoundary | null;
+    hasSessionStart: boolean;
+    hasSummarySidecar: boolean;
+    /** True when the sidecar is older than the transcript it summarizes. */
+    summaryStale: boolean;
+    findings: SessionFinding[];
+}
+export interface SessionDoctorTotals {
+    sessions: number;
+    bytes: number;
+    snapshotBytes: number;
+    unparsableLines: number;
+}
+export interface SessionDoctorReport {
+    sessionsDir: string;
+    totals: SessionDoctorTotals;
+    /** How many sessions carry each finding. */
+    byCode: Partial<Record<SessionFindingCode, number>>;
+    /** Every scanned session, worst-first (errors, then warnings, then size). */
+    sessions: SessionDiagnosis[];
+    /** Journals that could not be read at all, with the reason. */
+    unreadable: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+export interface DiagnoseSessionsOptions {
+    sessionsDir: string;
+    /**
+     * Size at which a session is flagged as slow to open. Default 64 MB —
+     * measured on this corpus, journals load at roughly 40 MB/s, so that is a
+     * couple of seconds and climbing.
+     */
+    oversizedBytes?: number | undefined;
+    /** Progress for a scan that walks tens of gigabytes. */
+    onProgress?: ((progress: {
+        scanned: number;
+        total: number;
+        id: string;
+    }) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Walk every journal under `sessionsDir` and report on it. Writes nothing.
+ */
+export declare function diagnoseSessions(options: DiagnoseSessionsOptions): Promise<SessionDoctorReport>;
+export interface SummaryRepairResult {
+    repaired: string[];
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Rebuild the `.summary.json` sidecars the report flagged.
+ *
+ * The only thing this module writes. A summary is a projection of the journal
+ * beside it — regenerating one cannot lose anything, and a session whose
+ * summary is missing is a session the picker cannot describe.
+ */
+export declare function repairSessionSummaries(options: {
+    report: SessionDoctorReport;
+    secretScrubber?: SecretScrubber | undefined;
+    onProgress?: ((progress: {
+        repaired: number;
+        total: number;
+        id: string;
+    }) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<SummaryRepairResult>;
+//# sourceMappingURL=session-doctor.d.ts.map

package/dist/storage/session-event-bridge.d.ts

@@ -45,12 +45,12 @@ export interface SessionEventBridge {
     allows(type: SessionEvent['type']): boolean;
 }
 /** Core events that are always written regardless of auditLevel. */
-declare const CORE_RECONSTRUCT_EVENTS: Set<"agent_error" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "error" | "file_event" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "message_appended" | "message_truncated" | "message_updated" | "messages_dropped" | "messages_replaced" | "mode_changed" | "provider_error" | "provider_retry" | "rewound" | "session_end" | "session_forked" | "session_resumed" | "session_start" | "side_effect" | "skill_activated" | "skill_deactivated" | "spec_analyzed" | "spec_parsed" | "task_completed" | "task_created" | "task_failed" | "task_updated" | "tool_call_end" | "tool_call_start" | "tool_progress" | "tool_result" | "tool_use" | "user_input">;
+export declare const CORE_RECONSTRUCT_EVENTS: Set<"agent_error" | "agent_session_linked" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "delegate_completed" | "delegate_started" | "error" | "file_event" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "loop_detected" | "message_appended" | "message_truncated" | "message_updated" | "messages_dropped" | "messages_replaced" | "mode_changed" | "model_switched" | "provider_error" | "provider_retry" | "rewound" | "session_end" | "session_forked" | "session_resumed" | "session_start" | "side_effect" | "skill_activated" | "skill_deactivated" | "task_completed" | "task_created" | "task_failed" | "task_updated" | "tool_call_end" | "tool_call_start" | "tool_progress" | "tool_result" | "tool_use" | "user_input">;
 /**
  * Events that are considered "standard" audit detail.
  * These are lightweight and high-value for forensics.
  */
-declare const STANDARD_AUDIT_EVENTS: Set<"agent_error" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "error" | "file_event" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "message_appended" | "message_truncated" | "message_updated" | "messages_dropped" | "messages_replaced" | "mode_changed" | "provider_error" | "provider_retry" | "rewound" | "session_end" | "session_forked" | "session_resumed" | "session_start" | "side_effect" | "skill_activated" | "skill_deactivated" | "spec_analyzed" | "spec_parsed" | "task_completed" | "task_created" | "task_failed" | "task_updated" | "tool_call_end" | "tool_call_start" | "tool_progress" | "tool_result" | "tool_use" | "user_input">;
+export declare const STANDARD_AUDIT_EVENTS: Set<"agent_error" | "agent_session_linked" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "delegate_completed" | "delegate_started" | "error" | "file_event" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "loop_detected" | "message_appended" | "message_truncated" | "message_updated" | "messages_dropped" | "messages_replaced" | "mode_changed" | "model_switched" | "provider_error" | "provider_retry" | "rewound" | "session_end" | "session_forked" | "session_resumed" | "session_start" | "side_effect" | "skill_activated" | "skill_deactivated" | "task_completed" | "task_created" | "task_failed" | "task_updated" | "tool_call_end" | "tool_call_start" | "tool_progress" | "tool_result" | "tool_use" | "user_input">;
 /**
  * Create a safe, audit-level-aware bridge around a SessionWriter.
  *
@@ -65,8 +65,6 @@ declare const STANDARD_AUDIT_EVENTS: Set<"agent_error" | "agent_spawned" | "agen
  * });
  */
 export declare function createSessionEventBridge(writer: SessionWriter | (() => SessionWriter | undefined | null) | undefined | null, level?: AuditLevel, options?: SessionEventBridgeOptions): SessionEventBridge;
-/** Convenience re-export of the allowed core set for tests/docs. */
-export { CORE_RECONSTRUCT_EVENTS, STANDARD_AUDIT_EVENTS };
 /**
  * Safely extract the auditLevel from a (possibly partial) Config object.
  * Falls back to 'standard' if not present or invalid.
@@ -86,9 +84,9 @@ export declare function resolveSessionLoggingConfig(cfg?: {
         sampling?: {
             toolProgress?: {
                 sampleRate?: number | undefined;
-            };
-        };
-    };
+            } | undefined;
+        } | undefined;
+    } | undefined;
 } | null): {
     auditLevel: AuditLevel;
     sampling: {

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

@@ -0,0 +1,42 @@
+import type { SessionEvent, SessionSummary } from '../types/session.js';
+/**
+ * The single definition of `SessionSummary.outcome`.
+ *
+ * Two code paths produce this field — the live writer's `SessionSummaryTracker`
+ * and the disk-rebuild `summarizeSessionEventSequence` — and they disagreed
+ * three ways on the same journal, so the value a user saw depended on whether
+ * the `.summary.json` sidecar cache happened to be warm:
+ *
+ *  1. **Precedence.** The rebuild asked "how did this session END", letting a
+ *     trailing `session_end` mean `completed`. The live tracker made `error`
+ *     sticky from the moment it was set, overriding the terminal marker — so a
+ *     session that hit one error and then finished cleanly reported `error`
+ *     forever, and no successful recovery could clear it.
+ *  2. **What counts as an error.** The live tracker treated any `tool_result`
+ *     with `isError` as an errored session. A failed grep is ordinary agent
+ *     operation; `toolErrorCount` already records those precisely. Only
+ *     `error` / `provider_error` events mean the session itself went wrong.
+ *  3. **The no-signal case.** The rebuild left `outcome` undefined when the
+ *     journal ended on neither a terminal marker nor an error; the live
+ *     tracker defaulted to `completed`, asserting a clean end it had no
+ *     evidence for.
+ *
+ * Measured drift: one journal (`user_input`, an errored `tool_result`, a normal
+ * `llm_response`, `session_end`) summarized as `error` live and `completed`
+ * rebuilt. Both paths now call this function.
+ *
+ * @param lastEventType Type of the final event in the journal, or undefined for
+ *   an empty one. `session_end` means a clean shutdown wrote its marker; a
+ *   trailing `in_flight_start` means the process died mid-operation.
+ * @param hadSessionError Whether any `error` / `provider_error` event was
+ *   observed. Consulted only when the journal has no terminal marker to speak
+ *   for itself.
+ */
+export declare function resolveSessionOutcome(lastEventType: SessionEvent['type'] | undefined, hadSessionError: boolean): SessionSummary['outcome'];
+/**
+ * Whether an event means the SESSION failed, as opposed to one operation
+ * inside it failing. Kept next to {@link resolveSessionOutcome} so both
+ * producers classify identically.
+ */
+export declare function isSessionErrorEvent(event: SessionEvent): boolean;
+//# sourceMappingURL=session-outcome.d.ts.map

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

@@ -29,6 +29,35 @@ export interface StaleSession {
     /** Total events in the log. */
     eventCount: number;
 }
+/**
+ * A session whose journal has no trailing `session_end`.
+ *
+ * Broader than {@link StaleSession} on purpose. `StaleSession` answers "did a
+ * process die *mid-iteration*", which needs a dangling `in_flight_start`. But a
+ * host killed while the agent was idle — waiting for the next prompt — closes
+ * its last turn with `in_flight_end` and then simply stops writing. Such a
+ * session is every bit as unfinished, and matching only on `in_flight_start`
+ * made exactly the common case (close the terminal, kill the daemon, reboot)
+ * invisible to recovery.
+ *
+ * Detection is a tail scan for the newest lifecycle boundary:
+ *   - `session_end`            -> closed, not reported
+ *   - `in_flight_start`        -> unclosed AND stale (died mid-iteration)
+ *   - `in_flight_end` / none   -> unclosed, not stale (died between turns)
+ */
+export interface UnclosedSession {
+    sessionId: string;
+    /** Path to the JSONL log. */
+    path: string;
+    /** Newest lifecycle boundary, or null for a journal that has none. */
+    lastBoundary: 'in_flight_start' | 'in_flight_end' | null;
+    /** Boundary timestamp when there is one, else the file's mtime as ISO. */
+    lastEventTs: string;
+    /** True when the newest boundary is a dangling `in_flight_start`. */
+    stale: boolean;
+    /** File mtime in ms — the ordering key, since a boundary-less log has no ts. */
+    modifiedAt: number;
+}
 export interface RecoveryPlan {
     sessionId: string;
     /** True if the session is stale (has a dangling in_flight_start). */
@@ -110,6 +139,32 @@ export declare class SessionRecovery {
      * recent crash first.
      */
     listResumable(): Promise<StaleSession[]>;
+    /**
+     * List every session whose journal has no trailing `session_end`, newest
+     * file first. This is the read side of "recovery" as a user means it: the
+     * conversations a crash, a `kill`, or a closed laptop lid left hanging.
+     *
+     * Ordering is by file mtime, not by boundary timestamp: a journal with no
+     * lifecycle boundary at all (a session that never completed a turn) has no
+     * timestamp to sort on, and mtime is the one key every candidate has.
+     *
+     * @param options.limit Stop after this many unclosed sessions are found.
+     *   Candidates are examined newest-mtime-first, so the cap keeps the common
+     *   "give me the last one" call to a couple of tail reads instead of a scan
+     *   of every transcript the project ever wrote.
+     */
+    listUnclosed(options?: {
+        limit?: number;
+    }): Promise<UnclosedSession[]>;
+    private detectUnclosedExact;
+    /**
+     * Every session transcript under `dir`, with the stat both scanners need.
+     *
+     * Modern sessions live inside date-shard subdirectories
+     * ("2026-06-11/<base>.jsonl"); legacy/flat sessions sit at the root. Scan
+     * both — a root-only scan silently misses every modern crash.
+     */
+    private collectTranscripts;
     private filePath;
     constructor(dir: string);
 }

package/dist/storage/session-store/load-session-data.d.ts

@@ -1,4 +1,5 @@
 import type { EventBus } from '../event-bus-port.js';
+import type { SessionLoadProgress } from '../../types/session.js';
 import type { SecretScrubber } from '../../types/secret-scrubber.js';
 import type { SessionData } from '../../types/session.js';
 /**
@@ -28,5 +29,15 @@ export declare function loadSessionDataFromFile(params: {
     events?: EventBus | undefined;
     secretScrubber: SecretScrubber;
     maxRetainedEventBytes?: number | undefined;
+    /**
+     * Byte-level parse progress for large journals. Throttled to one call per
+     * `progressIntervalMs` (the per-line accounting approximates delimiters)
+     * plus an unthrottled final call at EOF reporting
+     * `loadedBytes === totalBytes` exactly. When omitted,
+     * no progress work happens at all — not even the source-size stat.
+     */
+    onLoadProgress?: ((progress: SessionLoadProgress) => void) | undefined;
+    /** Test seam: override the throttle window (0 = every line). */
+    progressIntervalMs?: number | undefined;
 }): Promise<SessionData>;
 //# sourceMappingURL=load-session-data.d.ts.map

package/dist/storage/session-store/prune-helpers.d.ts

@@ -4,5 +4,5 @@
  * predicate is what stops them disagreeing again.
  */
 export declare function isPrunableSessionJsonl(name: string): boolean;
-export declare function pruneSessionFiles(storeDir: string, maxAgeDays: number, deleteSession: (id: string) => Promise<void>): Promise<number>;
+export declare function pruneSessionFiles(storeDir: string, maxAgeDays: number, deleteSession: (id: string) => Promise<void>, isSessionInUse?: ((sessionId: string) => Promise<string | null>) | undefined): Promise<number>;
 //# sourceMappingURL=prune-helpers.d.ts.map

package/dist/storage/session-store/resume-session.d.ts

@@ -1,4 +1,3 @@
-import * as fsp from 'node:fs/promises';
 import type { EventBus } from '../event-bus-port.js';
 import type { SecretScrubber } from '../../types/secret-scrubber.js';
 import type { ResumedSession, SessionData, SessionEvent, SessionSummary } from '../../types/session.js';
@@ -24,5 +23,4 @@ export interface ResumeSessionParams {
     sessionsDir?: string | undefined;
 }
 export declare function executeResumeSession(params: ResumeSessionParams): Promise<ResumedSession>;
-export declare function openSessionForAppend(file: string): Promise<fsp.FileHandle>;
 //# sourceMappingURL=resume-session.d.ts.map

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

@@ -48,8 +48,16 @@ export interface SessionStoreOptions {
  */
 export interface LoadCacheEntry {
     mtimeMs: number;
+    /** Source journal size — the freshness key, paired with `mtimeMs`. */
     size: number;
     data: SessionData;
+    /**
+     * Estimated heap this entry occupies, and what it is charged against the
+     * cache budget. Distinct from `size`: a journal is mostly superseded
+     * snapshots and evicted events, so the file dwarfs what survives into
+     * `data`. Optional for entries written before the distinction existed.
+     */
+    bytes?: number | undefined;
 }
 export interface IndexCacheEntry {
     mtimeMs: number;

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

@@ -1,4 +1,4 @@
-import type { ForkedSession, ResumedSession, SessionData, SessionEvent, SessionForkOptions, SessionMetadata, SessionStore, SessionSummary, SessionWriter, WorkspaceCheckpointRef } from '../types/session.js';
+import type { ForkedSession, ResumedSession, SessionData, SessionEvent, SessionForkOptions, SessionLoadProgress, SessionMetadata, SessionStore, SessionSummary, SessionWriter, WorkspaceCheckpointRef } from '../types/session.js';
 import type { SessionStoreOptions } from './session-store/types.js';
 export type { SessionStoreOptions } from './session-store/types.js';
 export declare class DefaultSessionStore implements SessionStore {
@@ -69,8 +69,8 @@ export declare class DefaultSessionStore implements SessionStore {
     captureWorkspaceCheckpoint(sessionId: string, promptIndex: number): Promise<WorkspaceCheckpointRef | undefined>;
     materializeWorkspaceCheckpoint(checkpoint: WorkspaceCheckpointRef, targetRoot: string): Promise<import("../types/session.js").WorkspaceMaterializationResult>;
     resolveId(query: string): Promise<string>;
-    resume(id: string): Promise<ResumedSession>;
-    load(id: string): Promise<SessionData>;
+    resume(id: string, onLoadProgress?: (progress: SessionLoadProgress) => void): Promise<ResumedSession>;
+    load(id: string, onLoadProgress?: (progress: SessionLoadProgress) => void): Promise<SessionData>;
     loadEventsOnly(id: string): Promise<SessionData>;
     private loadInternal;
     searchEvents(id: string, predicate: (event: SessionEvent, eventIndex: number, ts: string) => boolean, opts?: {

package/dist/storage/session-summary-tracker.d.ts

@@ -26,7 +26,14 @@ export declare class SessionSummaryTracker {
     private messageCount;
     private lastUserMessage;
     private lastActivityAt;
-    private outcome;
+    /**
+     * Whether an `error`/`provider_error` was seen. Not a latched outcome — see
+     * {@link resolveSessionOutcome} for why a trailing terminal marker outranks
+     * it, and why a failed tool_result is deliberately not counted here.
+     */
+    private hadSessionError;
+    /** Type of the newest observed event; the terminal-marker signal. */
+    private lastEventType;
     private openToolUses;
     constructor(opts: SessionSummaryTrackerOptions);
     get currentSummary(): Readonly<SessionSummary>;

package/dist/storage/session-write-buffer.d.ts

@@ -26,6 +26,16 @@ export declare class SessionWriteBuffer {
     private static readonly FLUSH_SIZE;
     private static readonly WRITE_BUFFER_MAX_EVENTS;
     private static readonly WRITE_BUFFER_MAX_BYTES;
+    /**
+     * Absolute ceiling for ONE event, even via the empty-buffer exemption in
+     * `push`. That exemption exists so a legitimately huge user prompt is
+     * persisted instead of silently dropped (its bytes are already resident —
+     * accepting it costs one reference, not a copy); without a ceiling an
+     * unbounded payload could pin memory and stall the event loop on
+     * stringify. 64MiB is 4x the retention budget and far above any real
+     * prompt, so it only fires on pathological input.
+     */
+    private static readonly MAX_SINGLE_EVENT_BYTES;
     private writeBuffer;
     private writeBufferBytes;
     private flushTimer;
@@ -33,6 +43,8 @@ export declare class SessionWriteBuffer {
     private lastBufferOverflowWarnAt;
     private appendFailCount;
     private lastAppendWarnAt;
+    private invalidEventCount;
+    private lastInvalidEventWarnAt;
     private writeChain;
     private flushPromise;
     /**
@@ -57,6 +69,12 @@ export declare class SessionWriteBuffer {
     /**
      * Last-gasp synchronous append (SIGKILL/SIGTERM traps, `process.on('exit')`).
      *
+     * If an async append is actively writing when teardown arrives, flushSync
+     * must not open a second append descriptor and race it. It defers with a
+     * structured `session.flush_sync_deferred` warning, leaving the buffer
+     * untouched for the already-running flush loop to drain if the process
+     * survives.
+     *
      * Failure contract: nothing is discarded before the write is known to have
      * landed. Buffered events stay in `writeBuffer` — it is cleared only after
      * `fsyncSync` returns — and a stolen in-flight batch is handed back to the

package/dist/storage/session-writer-truncate.d.ts

@@ -1,6 +1,8 @@
 export interface SessionTruncatePlan {
     checkpointByteOffset: number;
     removedCount: number;
+    /** Transcript paths referenced ONLY by the removed window — safe to delete. */
+    removedSubagentTranscriptPaths: string[];
 }
 export declare function findSessionCheckpointTruncatePlan(filePath: string, targetPromptIndex: number): Promise<SessionTruncatePlan | null>;
 export declare function rewriteSessionToCheckpoint(filePath: string, checkpointByteOffset: number): Promise<void>;