@wrongstack/core 0.284.0 → 0.285.0

package/dist/storage/provider-config-watcher.d.ts

@@ -0,0 +1,34 @@
+import type { ProviderConfig } from '../types/config.js';
+import type { SecretVault } from '../types/secret-vault.js';
+/**
+ * A decrypted snapshot of the credential-bearing slice of `config.json`.
+ * `providers` is always present (empty object when the file has none);
+ * `apiKey`/`baseUrl` are the top-level fallbacks a provider inherits when its
+ * saved entry omits them.
+ */
+export interface ProviderConfigSnapshot {
+    providers: Record<string, ProviderConfig>;
+    apiKey?: string;
+    baseUrl?: string;
+    /** Display language (Config.uiLocale), surfaced so a cross-process change
+     *  (e.g. the desktop shell) propagates to running webui instances. */
+    uiLocale?: string;
+}
+export interface WatchProviderConfigOptions {
+    /** Surface non-fatal read/parse/decrypt issues. */
+    warn?: (msg: string) => void;
+    /** Coalesce bursts of fs events (default 200ms). */
+    debounceMs?: number;
+}
+/**
+ * Watch `configPath` for credential changes and invoke `onChange` with a
+ * freshly-decrypted snapshot whenever the `providers`/`apiKey`/`baseUrl` slice
+ * actually changes. Returns a `close()` that stops watching.
+ *
+ * The initial on-disk state is read once to seed the no-op guard but does NOT
+ * fire `onChange` — only subsequent changes do.
+ */
+export declare function watchProviderConfig(configPath: string, vault: SecretVault, onChange: (snapshot: ProviderConfigSnapshot) => void, opts?: WatchProviderConfigOptions): {
+    close: () => void;
+};
+//# sourceMappingURL=provider-config-watcher.d.ts.map

package/dist/storage/provider-config-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-config-watcher.d.ts","sourceRoot":"","sources":["../../src/storage/provider-config-watcher.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;0EACsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,mDAAmD;IACnD,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuDD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,EACpD,IAAI,GAAE,0BAA+B,GACpC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAgEvB"}

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

@@ -0,0 +1,37 @@
+import type { EventBus } from '../kernel/events.js';
+import type { ContentBlock } from '../types/blocks.js';
+/**
+ * The persisted form of a single queued user message. The TUI's
+ * in-memory QueueItem has a render id; that's pure UI bookkeeping, so
+ * we drop it when serializing — fresh ids are assigned on rehydrate.
+ */
+export interface PersistedQueueItem {
+    displayText: string;
+    blocks: ContentBlock[];
+}
+/**
+ * Side-file storage for a session's pending input queue. Lives at
+ * `<sessionDir>/queue.json` next to the attachment spool. Reads are
+ * tolerant (missing/malformed file → empty array); writes are atomic
+ * (tmp + rename) so a crash mid-write can never leave a partial file
+ * the next launch would choke on.
+ *
+ * The contract is "snapshot replacement": every mutation hands the
+ * full queue and we rewrite the file. The queue is small (rarely more
+ * than a handful of messages), so this is cheaper than delta logging
+ * and avoids the replay complexity.
+ */
+export declare class QueueStore {
+    private readonly file;
+    private readonly events;
+    private readonly traceId;
+    constructor(opts: {
+        dir: string;
+        events?: EventBus;
+        traceId?: string;
+    });
+    write(items: PersistedQueueItem[]): Promise<void>;
+    read(): Promise<PersistedQueueItem[]>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=queue-store.d.ts.map

package/dist/storage/queue-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-store.d.ts","sourceRoot":"","sources":["../../src/storage/queue-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAG9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,YAAY,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAIrE;IAEK,KAAK,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCtD;IAEK,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiF1C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAqC3B;CACF"}

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

@@ -0,0 +1,79 @@
+import type { SessionStore } from '../types/session.js';
+/**
+ * Per-project lockfile used for crash detection. The CLI writes one of
+ * these alongside the session JSONLs (`<projectSessions>/active.json`)
+ * when an interactive run starts, and deletes it on clean exit. If we
+ * find one on the next launch whose owning PID is dead (or whose host
+ * doesn't match), we know the previous run was killed mid-flight and
+ * the session it was writing to is a recovery candidate.
+ *
+ * The lockfile is intentionally per-project (already isolated by
+ * `wpaths.projectSessions`), so two TUIs in two different repos do not
+ * fight each other.
+ */
+export interface RecoveryLockOptions {
+    /** Directory the lockfile lives in. Usually `wpaths.projectSessions`. */
+    dir: string;
+    /** This process's PID. Default: `process.pid`. */
+    pid?: number | undefined;
+    /** Hostname recorded for the lock. Default: `os.hostname()`. */
+    hostname?: string | undefined;
+    /** Locks older than this are considered orphaned (disk wiped, etc.). Default 24h. */
+    maxAgeMs?: number | undefined;
+    /** Used to check whether the abandoned session was actually closed cleanly. */
+    sessionStore?: SessionStore | undefined;
+    /**
+     * Override the PID-liveness probe. Default: `process.kill(pid, 0)` —
+     * succeeds (or throws EPERM) when the PID is alive, throws ESRCH when
+     * it is gone. Tests inject a deterministic stub.
+     */
+    isPidAlive?: (((pid: number) => boolean)) | undefined;
+}
+export interface AbandonedSession {
+    sessionId: string;
+    pid: number;
+    startedAt: string;
+    /** Lockfile age in ms at the time of the check. */
+    ageMs: number;
+    /** Number of messages already on disk for this session. */
+    messageCount: number;
+}
+export declare class RecoveryLock {
+    private readonly file;
+    private readonly pid;
+    private readonly hostname;
+    private readonly maxAgeMs;
+    private readonly sessionStore?;
+    private readonly probe;
+    constructor(opts: RecoveryLockOptions);
+    /**
+     * Examine the lockfile and decide whether it represents an abandoned
+     * session. Returns `null` if the file is missing, points to a live
+     * instance, references a clean-closed session, is too old, or is
+     * malformed. Otherwise returns enough detail to prompt the user.
+     *
+     * Important: this is a read-only check. We never delete an active
+     * lock from here — if another wstack instance is alive, the caller
+     * should bail or run with a fresh session instead.
+     */
+    checkAbandoned(): Promise<AbandonedSession | null>;
+    /**
+     * Claim the lock for the given session. Uses exclusive-create (`O_EXCL`)
+     * to detect whether another process acquired the lock between our
+     * `checkAbandoned()` call and now. If the file already exists, it means
+     * another process won the race and we throw instead of silently
+     * overwriting their recovery record.
+     *
+     * The caller MUST have already called `checkAbandoned()` and handled its
+     * null return before calling this.
+     */
+    write(sessionId: string): Promise<void>;
+    /**
+     * Release the lock. Idempotent — silently succeeds if the file is
+     * already gone (e.g. someone else cleared it, or the directory was
+     * wiped).
+     */
+    clear(): Promise<void>;
+    private readLock;
+}
+//# sourceMappingURL=recovery-lock.d.ts.map

package/dist/storage/recovery-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-lock.d.ts","sourceRoot":"","sources":["../../src/storage/recovery-lock.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;CACtB;AAaD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IAEjD,YAAY,IAAI,EAAE,mBAAmB,EAOpC;IAED;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAwDvD;IAED;;;;;;;;;OASG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5C;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAS3B;YAEa,QAAQ;CAiBvB"}

package/dist/storage/replay-log-store.d.ts

@@ -0,0 +1,97 @@
+import type { Request, Response } from '../types/provider.js';
+import type { EventBus } from '../kernel/events.js';
+/**
+ * ReplayLogStore — sidecar store for deterministic-replay support
+ * (idea #2 from IDEAS.md). One JSONL file per session, recording
+ * every provider request/response pair so the same agent loop can
+ * be re-run later with frozen API responses.
+ *
+ * Why a sidecar (not the session JSONL)?
+ *
+ *   Same reason as `AnnotationsStore` — the session log is
+ *   event-sourced and append-only; a provider request payload can be
+ *   tens of kilobytes (especially with long conversation history),
+ *   and we want replay to be opt-in (recorded only when the user
+ *   runs with `--replay` or a future equivalent). Mixing it into
+ *   the event log would inflate every read for replay-irrelevant
+ *   paths.
+ *
+ * File layout: `sessionScopedPath(dir, sessionId, '.replay.jsonl')`,
+ * one entry per line.
+ * Each entry: `{ hash, ts, request, response }`. The `hash` is
+ * computed via `hashRequest` so lookups are O(1) by hash.
+ *
+ * Concurrency: per-session write queue (same pattern as
+ * `AnnotationsStore`). Reads are lock-free; the write chain makes
+ * the append + rehash sequence atomic.
+ */
+export interface ReplayEntry {
+    hash: string;
+    ts: string;
+    request: Request;
+    response: Response;
+}
+export interface ReplayLogStoreOptions {
+    /** Root sessions directory used with `sessionScopedPath(..., '.replay.jsonl')`. */
+    dir: string;
+    /**
+     * Cap on the number of entries per session. When a `record` would
+     * push the file beyond this, the oldest entries are evicted (LRU
+     * by insertion order). Set to `Infinity` to disable rotation.
+     * Defaults to 1000 — a single LLM call averages ~5KB serialized
+     * (messages + tools + response), so 1000 entries is ~5MB per
+     * session which is a reasonable upper bound.
+     */
+    maxEntries?: number | undefined;
+    events?: EventBus;
+    traceId?: string;
+}
+export declare class ReplayLogStore {
+    private readonly dir;
+    private readonly events;
+    private readonly traceId;
+    private readonly writeChains;
+    /** Per-session hash → on-disk location, with lazy entry hydration. */
+    private readonly cache;
+    /** Per-session entry count on disk, to detect when compaction is needed. */
+    private readonly diskCount;
+    private readonly maxEntries;
+    constructor(opts: ReplayLogStoreOptions);
+    /**
+     * Record a request/response pair. Idempotent on hash: a second
+     * `record` for the same hash is a no-op (the existing entry wins).
+     * Returns the hash.
+     */
+    record(input: {
+        sessionId: string;
+        request: Request;
+        response: Response;
+    }): Promise<string>;
+    /**
+     * Look up an entry by hash. Returns `null` when the request has
+     * not been recorded for this session. O(1) after the first call
+     * per session (in-memory cache).
+     */
+    lookup(sessionId: string, hash: string): Promise<ReplayEntry | null>;
+    /** All recorded entries for a session, in insertion order. */
+    load(sessionId: string): Promise<ReplayEntry[]>;
+    /**
+     * List every session id that has a replay log in the store dir.
+     * Returns an array of `{ sessionId, entryCount, path }` sorted
+     * by sessionId for stable output. Used by `wstack replay --list`.
+     */
+    list(): Promise<Array<{
+        sessionId: string;
+        entryCount: number;
+        path: string;
+    }>>;
+    private filePath;
+    private countEntries;
+    private parseReplayLine;
+    private readAll;
+    private writeAll;
+    private ensureCache;
+    private hydrateEntry;
+    private enqueue;
+}
+//# sourceMappingURL=replay-log-store.d.ts.map

package/dist/storage/replay-log-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-log-store.d.ts","sourceRoot":"","sources":["../../src/storage/replay-log-store.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAgBpD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAOD,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAChE,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuD;IAC7E,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,IAAI,EAAE,qBAAqB,EAKtC;IAID;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;KACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuFlB;IAID;;;;OAIG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8BzE;IAED,8DAA8D;IACxD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkCpD;IAED;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CA2CpF;IAID,OAAO,CAAC,QAAQ;YAOF,YAAY;IA+B1B,OAAO,CAAC,eAAe;YAeT,OAAO;YAiBP,QAAQ;YAyBR,WAAW;YAyDX,YAAY;IAwB1B,OAAO,CAAC,OAAO;CAShB"}

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

@@ -0,0 +1,48 @@
+import type { SessionEvent } from '../types/session.js';
+export interface QueryFilter {
+    eventTypes?: string[] | undefined;
+    toolNames?: string[] | undefined;
+    timeRange?: {
+        start: string;
+        end: string;
+    } | undefined;
+}
+export interface ToolInvocation {
+    ts: string;
+    name: string;
+    input: unknown;
+    output?: unknown | undefined;
+    error?: string | undefined;
+    durationMs: number;
+}
+export interface SessionError {
+    ts: string;
+    phase: string;
+    message: string;
+}
+export interface ModeChange {
+    ts: string;
+    from: string;
+    to: string;
+}
+export interface TaskSummary {
+    taskId: string;
+    title: string;
+    status: string;
+    createdAt: string;
+    completedAt?: string | undefined;
+}
+export interface SessionAnalysis {
+    sessionId: string;
+    totalDuration: number;
+    toolUsageCount: Record<string, number>;
+    errorCount: number;
+    modeChanges: ModeChange[];
+    tasks: TaskSummary[];
+}
+export declare class SessionAnalyzer {
+    analyze(events: SessionEvent[]): SessionAnalysis;
+    query(events: SessionEvent[], filter: QueryFilter): SessionEvent[];
+    private calcDuration;
+}
+//# sourceMappingURL=session-analyzer.d.ts.map

package/dist/storage/session-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-analyzer.d.ts","sourceRoot":"","sources":["../../src/storage/session-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,eAAe,CAyE/C;IAED,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,EAAE,CAejE;IAED,OAAO,CAAC,YAAY;CAUrB"}

package/dist/storage/session-checkpoint-cas.d.ts

@@ -0,0 +1,37 @@
+import type { WorkspaceCheckpointRef, WorkspaceMaterializationResult } from '../types/session.js';
+export interface CheckpointGitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Set when the runner discarded output after its safety limit. */
+    stdoutTruncated?: boolean | undefined;
+    stderrTruncated?: boolean | undefined;
+}
+export interface SessionCheckpointCasOptions {
+    rootDir: string;
+    projectRoot: string;
+    runGit?: ((args: string[], cwd: string) => Promise<CheckpointGitResult>) | undefined;
+}
+/**
+ * Content-addressed workspace checkpoint store.
+ *
+ * A manifest references a Git base tree plus CAS blobs for every changed or
+ * untracked, non-ignored path. Applying it to a checkout at the same baseHead
+ * reproduces the checkpoint without touching the parent working tree.
+ */
+export declare class SessionCheckpointCas {
+    private readonly rootDir;
+    private readonly projectRoot;
+    private readonly runGit;
+    constructor(opts: SessionCheckpointCasOptions);
+    capture(_sessionId: string, _promptIndex: number): Promise<WorkspaceCheckpointRef | undefined>;
+    materialize(checkpoint: WorkspaceCheckpointRef, targetRoot: string): Promise<WorkspaceMaterializationResult>;
+    private objectPath;
+    private manifestPath;
+    private putBlob;
+    private putManifest;
+    private readBlob;
+    private loadManifest;
+    private safeOutputPath;
+}
+//# sourceMappingURL=session-checkpoint-cas.d.ts.map

package/dist/storage/session-checkpoint-cas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-checkpoint-cas.d.ts","sourceRoot":"","sources":["../../src/storage/session-checkpoint-cas.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,SAAS,CAAC;CACtF;AAiDD;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgE;IAEvF,YAAY,IAAI,EAAE,2BAA2B,EAI5C;IAEK,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CA4GnG;IAEK,WAAW,CACf,UAAU,EAAE,sBAAsB,EAClC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,8BAA8B,CAAC,CAyGzC;IAED,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,YAAY;YAKN,OAAO;YAsCP,WAAW;YAUX,QAAQ;YAMR,YAAY;YA0CZ,cAAc;CAoB7B"}

package/dist/{session-event-bridge-D_z_mBwk.d.ts → storage/session-event-bridge.d.ts}

@@ -1,12 +1,11 @@
-import { S as SessionEvent, b as SessionWriter } from './tool-BNlnIJvo.js';
-
-type AuditLevel = 'minimal' | 'standard' | 'full';
+import type { SessionEvent, SessionWriter } from '../types/session.js';
+export type AuditLevel = 'minimal' | 'standard' | 'full';
 /**
  * Configuration for sampling high-volume events inside the bridge.
  * This allows callers (CLI, TUI, WebUI, plugins) to tune how aggressively
  * noisy events like tool progress are persisted.
  */
-interface ToolProgressSamplingOptions {
+export interface ToolProgressSamplingOptions {
     /**
      * How often to persist 'log' and 'partial_output' progress events.
      * - 1 = every message (no sampling)
@@ -14,11 +13,11 @@ interface ToolProgressSamplingOptions {
      */
     sampleRate?: number | undefined;
 }
-interface SessionSamplingOptions {
+export interface SessionSamplingOptions {
     /** Controls sampling behavior for `tool_progress` events (only relevant at auditLevel 'full'). */
     toolProgress?: ToolProgressSamplingOptions | undefined;
 }
-interface SessionEventBridgeOptions {
+export interface SessionEventBridgeOptions {
     /** Sampling rules for high-volume audit events. */
     sampling?: SessionSamplingOptions | undefined;
 }
@@ -29,7 +28,7 @@ interface SessionEventBridgeOptions {
  * All appends are best-effort. Failures are swallowed (with optional
  * diagnostics) so they never crash the agent loop.
  */
-interface SessionEventBridge {
+export interface SessionEventBridge {
     /** Append an event if allowed by the current audit level. */
     append(event: SessionEvent): Promise<void>;
     /** Batch-append events allowed by the current audit level. */
@@ -46,12 +45,12 @@ interface SessionEventBridge {
     allows(type: SessionEvent['type']): boolean;
 }
 /** Core events that are always written regardless of auditLevel. */
-declare const CORE_RECONSTRUCT_EVENTS: Set<"error" | "tool_use" | "tool_result" | "session_start" | "session_resumed" | "session_forked" | "user_input" | "llm_request" | "llm_response" | "context_snapshot" | "compaction" | "session_end" | "mode_changed" | "task_created" | "task_updated" | "task_completed" | "task_failed" | "agent_spawned" | "agent_stopped" | "agent_error" | "spec_parsed" | "spec_analyzed" | "skill_activated" | "skill_deactivated" | "tool_call_start" | "tool_call_end" | "tool_progress" | "message_truncated" | "provider_retry" | "provider_error" | "checkpoint" | "file_snapshot" | "file_observation" | "rewound" | "in_flight_start" | "in_flight_end" | "side_effect">;
+declare const CORE_RECONSTRUCT_EVENTS: Set<"agent_error" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "error" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "message_truncated" | "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">;
 /**
  * Events that are considered "standard" audit detail.
  * These are lightweight and high-value for forensics.
  */
-declare const STANDARD_AUDIT_EVENTS: Set<"error" | "tool_use" | "tool_result" | "session_start" | "session_resumed" | "session_forked" | "user_input" | "llm_request" | "llm_response" | "context_snapshot" | "compaction" | "session_end" | "mode_changed" | "task_created" | "task_updated" | "task_completed" | "task_failed" | "agent_spawned" | "agent_stopped" | "agent_error" | "spec_parsed" | "spec_analyzed" | "skill_activated" | "skill_deactivated" | "tool_call_start" | "tool_call_end" | "tool_progress" | "message_truncated" | "provider_retry" | "provider_error" | "checkpoint" | "file_snapshot" | "file_observation" | "rewound" | "in_flight_start" | "in_flight_end" | "side_effect">;
+declare const STANDARD_AUDIT_EVENTS: Set<"agent_error" | "agent_spawned" | "agent_stopped" | "checkpoint" | "compaction" | "context_snapshot" | "error" | "file_observation" | "file_snapshot" | "in_flight_end" | "in_flight_start" | "llm_request" | "llm_response" | "message_truncated" | "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">;
 /**
  * Create a safe, audit-level-aware bridge around a SessionWriter.
  *
@@ -65,13 +64,14 @@ declare const STANDARD_AUDIT_EVENTS: Set<"error" | "tool_use" | "tool_result" |
  *   }
  * });
  */
-declare function createSessionEventBridge(writer: SessionWriter | (() => SessionWriter | undefined | null) | undefined | null, level?: AuditLevel, options?: SessionEventBridgeOptions): SessionEventBridge;
-
+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.
  */
-declare function resolveAuditLevel(cfg?: {
+export declare function resolveAuditLevel(cfg?: {
     session?: {
         auditLevel?: AuditLevel | undefined;
     } | undefined;
@@ -80,7 +80,7 @@ declare function resolveAuditLevel(cfg?: {
  * Fully resolves the session logging configuration with sensible defaults.
  * This is the recommended way for the CLI / TUI / WebUI to read session config.
  */
-declare function resolveSessionLoggingConfig(cfg?: {
+export declare function resolveSessionLoggingConfig(cfg?: {
     session?: {
         auditLevel?: AuditLevel | undefined;
         sampling?: {
@@ -97,5 +97,4 @@ declare function resolveSessionLoggingConfig(cfg?: {
         };
     };
 };
-
-export { type AuditLevel as A, CORE_RECONSTRUCT_EVENTS as C, type SessionEventBridge as S, type ToolProgressSamplingOptions as T, STANDARD_AUDIT_EVENTS as a, type SessionEventBridgeOptions as b, type SessionSamplingOptions as c, createSessionEventBridge as d, resolveSessionLoggingConfig as e, resolveAuditLevel as r };
+//# sourceMappingURL=session-event-bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-bridge.d.ts","sourceRoot":"","sources":["../../src/storage/session-event-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,kGAAkG;IAClG,YAAY,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,8DAA8D;IAC9D,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEvC,oFAAoF;IACpF,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED,oEAAoE;AACpE,QAAA,MAAM,uBAAuB,0oBAe3B,CAAC;AAEH;;;GAGG;AACH,QAAA,MAAM,qBAAqB,0oBAYzB,CAAC;AA8BH;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EACF,aAAa,GACb,CAAC,MAAM,aAAa,GAAG,SAAS,GAAG,IAAI,CAAC,GACxC,SAAS,GACT,IAAI,EACR,KAAK,GAAE,UAAuB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA2FpB;AAED,oEAAoE;AACpE,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,GAC7E,UAAU,CAMZ;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,CAAC,EAAE;IACJ,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;QACpC,QAAQ,CAAC,EAAE;YACT,YAAY,CAAC,EAAE;gBAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;aAAE,CAAC;SACpD,CAAC;KACH,CAAC;CACH,GAAG,IAAI,GACP;IACD,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE;QACR,YAAY,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KACtC,CAAC;CACH,CAgBA"}

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

@@ -0,0 +1,9 @@
+import type { ContentBlock } from '../types/blocks.js';
+/**
+ * Derive a short title from a user_input event's content. Used by both
+ * `DefaultSessionStore.summarize()` (offline summary rebuild) and
+ * `FileSessionWriter.observeForSummary()` (live tracking), so it lives
+ * here to avoid a bidirectional import between those two modules.
+ */
+export declare function userInputTitle(content: string | ContentBlock[]): string;
+//# sourceMappingURL=session-helpers.d.ts.map

package/dist/storage/session-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-helpers.d.ts","sourceRoot":"","sources":["../../src/storage/session-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,MAAM,CASvE"}

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

@@ -0,0 +1,18 @@
+/**
+ * @deprecated Legacy helper kept for callers that still need filename-safe
+ * labels. New session ids are opaque and do not include model/provider names.
+ */
+export declare function sanitizeModel(model: string): string;
+/**
+ * Generate a session ID in the format:
+ *   `YYYY-MM-DD/sess_<ULID>`
+ *
+ * Examples:
+ *   `2026-06-06/sess_01JX2S9V7T5M6N7P8Q9R0STXVW`
+ *
+ * The date prefix becomes a subdirectory so sessions group naturally by day.
+ * The leaf is an opaque sortable id; provider/model names belong in metadata,
+ * not file paths. Older IDs that contain model/provider text remain readable.
+ */
+export declare function generateSessionId(startedAt: string, _model?: string): string;
+//# sourceMappingURL=session-id.d.ts.map

package/dist/storage/session-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-id.d.ts","sourceRoot":"","sources":["../../src/storage/session-id.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5E"}

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

@@ -0,0 +1,21 @@
+import type { DefaultSessionReaderOptions, SessionExportOptions, SessionQuery, SessionReader, SessionSearchHit, SessionSearchQuery, SessionSummaryLite } from '../types/session-reader.js';
+import type { SessionEvent, SessionMetadata } from '../types/session.js';
+/**
+ * L2-A: read-only view over a `SessionStore` with query, replay, search,
+ * and export helpers. Implemented on top of the public `SessionStore`
+ * surface so any concrete store can be inspected without re-implementation.
+ */
+export declare class DefaultSessionReader implements SessionReader {
+    private readonly store;
+    private readonly eventCache;
+    private readonly eventCacheMtimes;
+    private static readonly EVENT_CACHE_MAX_ENTRIES;
+    constructor(opts: DefaultSessionReaderOptions);
+    private loadCachedSessionData;
+    query(q?: SessionQuery): Promise<SessionSummaryLite[]>;
+    replay(sessionId: string): AsyncIterable<SessionEvent>;
+    search(q: SessionSearchQuery, sessionId?: string | undefined, sessionQuery?: SessionQuery): Promise<SessionSearchHit[]>;
+    export(sessionId: string, opts: SessionExportOptions): Promise<string>;
+    metadata(sessionId: string): Promise<SessionMetadata>;
+}
+//# sourceMappingURL=session-reader.d.ts.map

package/dist/storage/session-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reader.d.ts","sourceRoot":"","sources":["../../src/storage/session-reader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,2BAA2B,EAC3B,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAe,YAAY,EAAE,eAAe,EAAgB,MAAM,qBAAqB,CAAC;AAEpG;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAM;IAErD,YAAY,IAAI,EAAE,2BAA2B,EAE5C;YAEa,qBAAqB;IAiD7B,KAAK,CAAC,CAAC,GAAE,YAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA+C/D;IAEM,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,CAG5D;IAEK,MAAM,CAAC,CAAC,EAAE,kBAAkB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAmH5H;IAEK,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+B3E;IAEK,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAG1D;CACF"}

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

@@ -0,0 +1,93 @@
+import type { SessionEvent } from '../types/session.js';
+/**
+ * Idea #1 from IDEAS.md — Stateful Session Recovery.
+ *
+ * `SessionRecovery` is the read-side companion to the in-flight
+ * marker mechanism. When the agent loop is running, it writes an
+ * `in_flight_start` event at the current point in the log. On
+ * clean shutdown, a matching `in_flight_end` follows. Provider and
+ * tool events may legitimately appear after the start marker, so
+ * recovery finds the latest lifecycle boundary rather than assuming
+ * the marker is literally the last JSONL record.
+ *
+ * Detection is diagnostic only. Normal session resume reconstructs the
+ * conversation by replaying persisted JSONL events; it must not blindly
+ * re-execute tool calls after a crash. `recover()` exposes the tail after the
+ * last checkpoint so callers can explain which persisted work was in flight.
+ *
+ * Concurrency: pure read; no writes. Safe to call from multiple
+ * processes simultaneously.
+ */
+export interface StaleSession {
+    sessionId: string;
+    /** Path to the JSONL log. */
+    path: string;
+    /** Last event ts (the in_flight_start timestamp). */
+    lastEventTs: string;
+    /** Context the agent was working on when it died. */
+    context: string;
+    /** Total events in the log. */
+    eventCount: number;
+}
+export interface RecoveryPlan {
+    sessionId: string;
+    /** True if the session is stale (has a dangling in_flight_start). */
+    stale: boolean;
+    /** The last `checkpoint` event before the un-replayed work, or null. */
+    lastCheckpoint: SessionEvent | null;
+    /** All persisted events after the last checkpoint (diagnostic in-flight tail). */
+    pendingEvents: SessionEvent[];
+    /** The dangling in_flight_start event, if any. */
+    inFlightStart: SessionEvent | null;
+    /** Free-form context the agent was working on, if any. */
+    context: string | null;
+}
+/**
+ * Result of `SessionRecovery.recover(sessionId)`. Distinct from
+ * `StaleSession`: a session is "stale" if its latest lifecycle
+ * boundary is an open marker, but a "recovery plan" can also be generated for
+ * clean sessions whose last checkpoint is older than the
+ * conversation history (e.g. a user-initiated "rewind to last
+ * good state" flow). This is a diagnostic plan, not authorization to replay
+ * external side effects.
+ */
+export declare class SessionRecovery {
+    private readonly dir;
+    /**
+     * Scan a session log and return a `StaleSession` if and only if the newest
+     * lifecycle boundary is an `in_flight_start` without a later
+     * `in_flight_end`/`session_end`. Ordinary provider/tool events after the
+     * marker do not make the session clean. Returns `null` when:
+     *   - the log does not exist;
+     *   - the log is empty;
+     *   - the latest lifecycle boundary is `in_flight_end` or `session_end`;
+     *   - there is no lifecycle boundary (legacy/pre-marker log).
+     *
+     * The reverse scanner is chunked and line-aware. It can cross arbitrarily
+     * large JSONL records (for example a large tool result) without imposing a
+     * fixed tail-size correctness limit. Clean logs normally return after the
+     * first chunk; stale logs continue counting lines so `eventCount` remains
+     * the documented total rather than a tail-only approximation.
+     */
+    detectStale(sessionId: string): Promise<StaleSession | null>;
+    /**
+     * Generate a recovery plan for a session. The plan describes
+     * the persisted tail after the last checkpoint, plus the dangling in-flight
+     * marker if present. SessionStore.resume() independently reconstructs state
+     * from the journal and does not re-run these events as commands.
+     *
+     * Returns a non-null plan for ANY session that has at least
+     * one event after a checkpoint (or, for legacy sessions, at
+     * least one event). Pure read; no mutation.
+     */
+    recover(sessionId: string): Promise<RecoveryPlan | null>;
+    /**
+     * List every stale session in a directory. Returns an array
+     * (possibly empty) sorted by `lastEventTs` descending — most
+     * recent crash first.
+     */
+    listResumable(): Promise<StaleSession[]>;
+    private filePath;
+    constructor(dir: string);
+}
+//# sourceMappingURL=session-recovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-recovery.d.ts","sourceRoot":"","sources":["../../src/storage/session-recovery.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,kFAAkF;IAClF,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,kDAAkD;IAClD,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAiKd,OAAO,CAAC,QAAQ,CAAC,GAAG;IAhKhC;;;;;;;;;;;;;;;OAeG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA2BjE;IAED;;;;;;;;;OASG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA+C7D;IAED;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAwC7C;IAID,OAAO,CAAC,QAAQ;IAOhB,YAA6B,GAAG,EAAE,MAAM,EAAI;CAC7C"}

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

@@ -0,0 +1,6 @@
+import type { ResumeValidation, SessionEvent } from '../types/session.js';
+/** Revalidate the latest persisted hash for every distinct observed path. */
+export declare function validateResumeFileObservations(events: readonly SessionEvent[], projectRoot: string): Promise<ResumeValidation>;
+/** Build the ephemeral system message injected into the first resumed turn. */
+export declare function formatResumeValidationNotice(validation: ResumeValidation, projectRoot: string): string | null;
+//# sourceMappingURL=session-resume-validation.d.ts.map

package/dist/storage/session-resume-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-resume-validation.d.ts","sourceRoot":"","sources":["../../src/storage/session-resume-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,gBAAgB,EAChB,YAAY,EACb,MAAM,qBAAqB,CAAC;AA0G7B,6EAA6E;AAC7E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAc3B;AAED,+EAA+E;AAC/E,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAiBf"}