@threadbase-sh/streamer 1.63.0 → 1.65.0

package/dist/services/sessions/conversationBusy.d.ts

@@ -0,0 +1,32 @@
+import type { DiscoveredProcess } from "../../types";
+export declare const RESUME_BUSY_WINDOW_MS = 120000;
+export declare function resolveResumeBusyWindowMs(env?: NodeJS.ProcessEnv): number;
+export type BusySignal = "jsonl_mtime" | "process_argv" | "process_cwd" | "file_handle";
+export interface ConversationBusyInput {
+    conversationId: string;
+    projectPath: string | null;
+    jsonlPath: string | null;
+    discovered: DiscoveredProcess[];
+    now?: number;
+    windowMs?: number;
+    platform?: NodeJS.Platform;
+    /**
+     * When this streamer's own PTY for this conversation last went idle (ms epoch),
+     * or null/undefined if it never owned one in this process's lifetime.
+     *
+     * Without this the probe cannot tell our own echo from a stranger: the normal
+     * background → hold_session → foreground → resume flow releases the PTY (so the
+     * hasSession early-return no longer applies) while leaving a JSONL we wrote
+     * seconds ago — which would 409 the single most common resume in the product.
+     * File activity at or before this timestamp is attributed to us, not a collision.
+     */
+    selfPtyEndedAt?: number | null;
+}
+export interface ConversationBusyResult {
+    busy: boolean;
+    detectedBy: BusySignal[];
+    lastActivityMs: number | null;
+    likelyOwner: "external" | "unknown";
+}
+export declare function conversationBusy(input: ConversationBusyInput): ConversationBusyResult;
+//# sourceMappingURL=conversationBusy.d.ts.map

package/dist/services/sessions/conversationBusy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversationBusy.d.ts","sourceRoot":"","sources":["../../../src/services/sessions/conversationBusy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOrD,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAI7C,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAKtF;AAMD,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,cAAc,GAAG,aAAa,GAAG,aAAa,CAAC;AAOxF,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,UAAU,EAAE,CAAC;IAGzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,UAAU,GAAG,SAAS,CAAC;CACrC;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAmDrF"}

package/dist/services/sessions/idempotency.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Idempotency for session input (C4).
+ *
+ * `POST /api/sessions/:id/input` had no duplicate protection. A retry — a flaky
+ * network, a user double-tap, a client that resends on timeout — submitted the
+ * same prompt to the agent twice, and nothing downstream could tell the second
+ * submission from a deliberate repeat of the same words.
+ *
+ * The rate limiter does not help: 500 requests/minute is aimed at floods, and a
+ * genuine retry is well inside it.
+ *
+ * Clients send `idempotencyKey` with a write. A repeat of a key we have already
+ * accepted replays the original outcome instead of re-submitting.
+ *
+ * Scoped per session, because a key is only meaningful against the conversation
+ * it was minted for — the same key against a different session is a different
+ * write, and treating it as a duplicate would silently drop a real prompt.
+ */
+/** How long a key is remembered. Long enough to cover a retry, not a session. */
+export declare const IDEMPOTENCY_TTL_MS: number;
+/**
+ * Cap on remembered keys per session. Bounds memory on a long conversation; the
+ * oldest entries are evicted first, so a key older than the cap behaves as if it
+ * had expired — the request is treated as new.
+ */
+export declare const IDEMPOTENCY_MAX_KEYS = 200;
+export interface IdempotentResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Per-session record of recently accepted idempotency keys.
+ *
+ * Deliberately in-memory: this guards against retries seconds apart, and a
+ * streamer restart already ends the PTY those retries would target (see the
+ * durable-session-runtime ADR). Persisting it would imply a durability the
+ * surrounding runtime does not have.
+ */
+export declare class IdempotencyStore {
+    private ttlMs;
+    private maxKeys;
+    private bySession;
+    constructor(ttlMs?: number, maxKeys?: number);
+    /**
+     * Previously recorded result for this key, or null if the key is new,
+     * expired, or evicted. A miss always means "treat as a fresh request" —
+     * failing open, because dropping a real prompt is far worse than allowing a
+     * rare duplicate.
+     */
+    get(sessionId: string, key: string, now?: number): IdempotentResult | null;
+    /** Record the outcome of an accepted write so a retry can replay it. */
+    set(sessionId: string, key: string, result: IdempotentResult, now?: number): void;
+    /** Drop everything for a session whose PTY is gone. */
+    clear(sessionId: string): void;
+    /** Test/diagnostic helper: how many keys are currently held for a session. */
+    size(sessionId: string): number;
+}
+/**
+ * Extract and validate an idempotency key from a request body.
+ *
+ * Returns `undefined` when absent (the field is optional, so existing clients
+ * keep working) and throws on a present-but-invalid value rather than ignoring
+ * it — a client that sends a malformed key believes it has retry protection,
+ * and silently proceeding without it would be worse than a clear rejection.
+ */
+export declare function readIdempotencyKey(body: Record<string, unknown>): string | undefined;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/services/sessions/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/services/sessions/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAQD;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,OAAO;IAJjB,OAAO,CAAC,SAAS,CAA8B;IAE/C,YACU,KAAK,GAAE,MAA2B,EAClC,OAAO,GAAE,MAA6B,EAC5C;IAEJ;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,gBAAgB,GAAG,IAAI,CAcrF;IAED,wEAAwE;IACxE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,GAAE,MAAmB,GAAG,IAAI,CAM5F;IAED,uDAAuD;IACvD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE7B;IAED,8EAA8E;IAC9E,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9B;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAOpF"}

package/dist/services/sessions/reconcileSessions.d.ts

@@ -0,0 +1,63 @@
+import type { ManagedSessionRow, SessionLifecycle } from "../../db/repositories/managed-sessions.repository";
+/**
+ * Boot reconciliation (C1 Phase 3a).
+ * See docs/architecture/2026-07-24-durable-session-runtime.md.
+ *
+ * On startup the registry holds rows from previous runs. Some of those
+ * processes are gone; some are still alive (the crash and dev-takeover paths
+ * exit without reaching ptyManager.dispose(), so agents genuinely outlive the
+ * streamer today — they are simply invisible when they do). This module decides
+ * which is which.
+ *
+ * Two rules make it safe:
+ *
+ *  1. **A stored status is never trusted over a live probe.** A SIGKILLed
+ *     streamer never ran its exit writes, so a row can claim `running`
+ *     indefinitely. Only the pid probe decides liveness.
+ *
+ *  2. **Liveness is never treated as identity.** Pids are recycled. A live pid
+ *     whose command line does not carry the recorded token is reported
+ *     `orphaned` and never signalled — that is the difference between a
+ *     durability feature and one that kills an unrelated user process.
+ */
+/**
+ * Reason attached to a row whose pid was never probed because it was recorded
+ * under a previous machine boot. Exported so the caller can recognise the
+ * abstention and log it, without matching on a free-text string that could
+ * drift away from the one produced here.
+ */
+export declare const PRE_BOOT_REASON = "recorded before this machine boot";
+/** Result for a single registry row. Pure data — nothing here acts. */
+export interface ReconcileVerdict {
+    sessionId: string;
+    lifecycle: SessionLifecycle;
+    /** Why this verdict was reached, for logs and the diagnostics surface. */
+    reason: string;
+}
+export interface ReconcileProbe {
+    /** Whether a process currently exists at this pid. */
+    isPidAlive: (pid: number) => boolean;
+    /** Full command line for a live pid, or "" when it cannot be read. */
+    getProcessArgs: (pid: number) => Promise<string>;
+    /**
+     * Whether the provider's own history shows this session ended cleanly.
+     * Distinguishes `completed` from `failed` for a process that is gone.
+     */
+    endedCleanly?: (row: ManagedSessionRow) => boolean;
+}
+/**
+ * Classify one registry row against live process state.
+ *
+ * Exported separately from reconcileSessions so the decision table can be
+ * tested without a database. `currentBootToken` is passed in rather than read
+ * here for the same reason — this stays a pure function of its arguments.
+ * Omitted/null means the caller has no boot identity, which skips the pre-boot
+ * check entirely; the server always supplies one.
+ */
+export declare function classifySession(row: ManagedSessionRow, probe: ReconcileProbe, currentInstanceId: string, currentBootToken?: string | null): Promise<ReconcileVerdict>;
+/**
+ * Classify every non-terminal row. Returns verdicts only — the caller decides
+ * what to persist or broadcast. This function never signals a process.
+ */
+export declare function reconcileSessions(rows: ManagedSessionRow[], probe: ReconcileProbe, currentInstanceId: string, currentBootToken?: string | null): Promise<ReconcileVerdict[]>;
+//# sourceMappingURL=reconcileSessions.d.ts.map

package/dist/services/sessions/reconcileSessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcileSessions.d.ts","sourceRoot":"","sources":["../../../src/services/sessions/reconcileSessions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mDAAmD,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,sCAAsC,CAAC;AAEnE,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,sEAAsE;IACtE,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,cAAc,EACrB,iBAAiB,EAAE,MAAM,EACzB,gBAAgB,GAAE,MAAM,GAAG,IAAW,GACrC,OAAO,CAAC,gBAAgB,CAAC,CAoF3B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,iBAAiB,EAAE,EACzB,KAAK,EAAE,cAAc,EACrB,iBAAiB,EAAE,MAAM,EACzB,gBAAgB,GAAE,MAAM,GAAG,IAAW,GACrC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAI7B"}

package/dist/services/sessions/rehydrateSessions.d.ts

@@ -0,0 +1,68 @@
+import type { ManagedSessionRow } from "../../db/repositories/managed-sessions.repository";
+import type { ManagedSession } from "../../types";
+/**
+ * Boot rehydration (persistence plan Phase 1, gaps G1/G2/G8).
+ * See docs/plans/live-sessions-persistence-plan.md §4.
+ *
+ * `recordShutdownState()` stamps `completed_at` on every live session as the
+ * streamer stops, which takes the row out of the reconciler's probe set. So a
+ * *cleanly* restarted session is not classified as anything — it simply
+ * disappears from `GET /api/sessions`, because `SessionStore` starts empty and
+ * nothing ever seeds it from the registry.
+ *
+ * This module is the decision half of the fix: which rows come back, and what
+ * they look like when they do. Pure functions with no database import, mirroring
+ * how `classifySession` is split out of `reconcileSessions` — the decision table
+ * is the part worth testing, and it should not need a SQLite file to do it.
+ *
+ * The stub these produce holds no PTY and never reaches `LiveSessionManager`;
+ * it lives in `SessionStore` alone, so the idle reaper and the grace timer
+ * (both of which iterate `ptyManager.listSessions()`) cannot see it.
+ */
+/** Most recovered sessions to seed in one boot. */
+export declare const REHYDRATE_MAX = 25;
+/** How far back a registry row may reach and still be offered as recoverable. */
+export declare const REHYDRATE_WINDOW_MS: number;
+export interface ShouldRehydrateOptions {
+    now: number;
+    /** Whether the row's project directory still exists on disk. */
+    projectExists: (projectPath: string) => boolean;
+}
+/**
+ * Why a registry row was not brought back, or `null` when it was.
+ *
+ * A stable code rather than a sentence: it is logged per row and surfaced by
+ * `GET /api/diagnostics/sessions`, where "my session did not come back" has to
+ * be answerable without reading the source.
+ */
+export type RehydrateSkipReason = "codex_unbound" | "project_missing" | "too_old" | "agent_exited";
+/**
+ * Should this registry row come back as a recovered session? `null` means yes.
+ *
+ * Three ways to answer no, all of them "resuming this would waste the user's
+ * tap":
+ *
+ *  - the project directory is gone — `handleResume` would fail to spawn, and
+ *    `classifyResumability` already encodes the same rule for conversations;
+ *  - the row is older than the window — a week-old session belongs in the
+ *    conversations list, not the live-session list;
+ *  - the agent exited on its own without recording a failure — it finished, so
+ *    there is nothing to recover. A row that recorded a `failureReason` is
+ *    deliberately still offered: that one was cut short.
+ *
+ * Plus a fourth that is not a heuristic but an impossibility: a Codex row that
+ * never bound its rollout id has no id that can resume it at all (G6).
+ */
+export declare function rehydrateSkipReason(row: ManagedSessionRow, opts: ShouldRehydrateOptions): RehydrateSkipReason | null;
+/**
+ * Registry row → an idle, non-attached `ManagedSession` stub.
+ *
+ * `status` is `idle` rather than anything new: a fresh `SessionStatus` value
+ * would be rejected by `VALID_STATUSES` on `?status=` and dropped by
+ * `SessionStore.paginate`'s filter, making recovered sessions *vanish* from
+ * already-shipped mobile clients. The recovered-ness travels on `rehydrated`
+ * instead, which `managedToResponse` turns into the existing
+ * `ownership: "historical"` / `lifecycle: "resumable"` pair.
+ */
+export declare function rowToStubSession(row: ManagedSessionRow): ManagedSession;
+//# sourceMappingURL=rehydrateSessions.d.ts.map

package/dist/services/sessions/rehydrateSessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrateSessions.d.ts","sourceRoot":"","sources":["../../../src/services/sessions/rehydrateSessions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,aAAa,CAAC;AAGhE;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mDAAmD;AACnD,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAS3D,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,aAAa,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,GAAG,cAAc,CAAC;AAEnG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,sBAAsB,GAC3B,mBAAmB,GAAG,IAAI,CAQ5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,CAwCvE"}

package/dist/services/sessions/resumeIdentity.d.ts

@@ -0,0 +1,16 @@
+import type { ManagedSessionRow } from "../../db/repositories/managed-sessions.repository";
+/**
+ * Which id can actually resume a registry row (persistence plan Phase 3, gap G6).
+ *
+ * Claude's session id is always resumable as-is: it was passed to the CLI as
+ * `--session-id`, so the JSONL is named after it and `--resume <id>` finds it.
+ *
+ * Codex has no such flag. A fresh Codex session is keyed by a local placeholder
+ * UUID and its real rollout id arrives later, via `watchForCodexRollout`, as
+ * `bound_conversation_id`. `codex resume <placeholder>` fails, so the bound id
+ * is the only usable one — and a row that never bound has none at all, which is
+ * what the `null` here means. Callers must treat `null` as "not resumable",
+ * never as "resume by session_id".
+ */
+export declare function resumeIdForRow(row: ManagedSessionRow): string | null;
+//# sourceMappingURL=resumeIdentity.d.ts.map

package/dist/services/sessions/resumeIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeIdentity.d.ts","sourceRoot":"","sources":["../../../src/services/sessions/resumeIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAG3F;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAGpE"}

package/dist/session-registry-boot.d.ts

@@ -0,0 +1,142 @@
+import { type ManagedSessionRow, type ManagedSessionsRepository } from "./db/repositories/managed-sessions.repository";
+import type { FeatureFlagValues } from "./feature-flags";
+import type { LiveSessionManager } from "./live-session-manager";
+import type { Logger } from "./logger";
+import type { ResumeOutcome } from "./server";
+import { type ReconcileVerdict } from "./services/sessions/reconcileSessions";
+import type { SessionStore } from "./session-store";
+import type { ManagedSession } from "./types";
+/**
+ * Everything the boot-time registry lifecycle reads from the server. Thunks
+ * rather than values for anything bound after construction or replaceable at
+ * runtime (`managedSessionsRepo` opens during listen(); tests swap `log` and
+ * `resumeSession` on the server instance) — the same reason ScannerManagerDeps
+ * passes `cache: () => ConversationCache | null`.
+ */
+export type SessionRegistryBootDeps = {
+    log: () => Logger;
+    ptyManager: () => LiveSessionManager;
+    sessionStore: () => SessionStore;
+    featureFlags: () => FeatureFlagValues;
+    autoResumeOnBoot: () => boolean;
+    managedSessionsRepo: () => ManagedSessionsRepository | null;
+    streamerInstanceId: string;
+    sessionVerdicts: Map<string, ReconcileVerdict>;
+    selfPtyEndedAt: Map<string, number>;
+    resumeSession: (opts: {
+        sessionId: string;
+        projectName?: string;
+        branch?: string;
+    }) => Promise<ResumeOutcome>;
+    watchConversationFile: (sessionId: string, historyId?: string) => Promise<void>;
+    broadcastSessionList: () => void;
+    resolveConversationTarget: (sessionId: string) => Promise<{
+        ok: false;
+        reason: string;
+    } | {
+        ok: true;
+        [key: string]: unknown;
+    }>;
+};
+/**
+ * The durable session registry's boot-and-shutdown lifecycle: classifying what
+ * previous runs left behind, seeding the session list from it, optionally
+ * resuming, pruning retired rows, and mirroring spawns and shutdown back into
+ * the registry.
+ *
+ * Extracted from StreamerServer so registry work stops editing the server file
+ * (see docs/plans/2026-07-12-server-ts-split.md, PR 6). State stays on the
+ * server: this class only reads it through `deps`.
+ */
+export declare class SessionRegistryBoot {
+    private deps;
+    constructor(deps: SessionRegistryBootDeps);
+    private get log();
+    private get ptyManager();
+    private get sessionStore();
+    private get featureFlags();
+    private get autoResumeOnBoot();
+    private get managedSessionsRepo();
+    private get streamerInstanceId();
+    private get sessionVerdicts();
+    private get selfPtyEndedAt();
+    /**
+     * Classify sessions left behind by previous streamer runs (C1 Phase 3a).
+     *
+     * Agents already outlive the streamer today on the crash and dev-takeover
+     * paths, which exit without reaching ptyManager.dispose() — they are just
+     * invisible when they do, because nothing recorded that they existed. This
+     * turns those rows into an explicit verdict per session.
+     *
+     * Read-only with respect to processes: it probes and classifies, and never
+     * signals anything. `orphaned` is a report, not a cleanup trigger.
+     */
+    reconcilePreviousSessions(): Promise<ReconcileVerdict[]>;
+    /**
+     * Drop finished sessions the registry has held long enough (plan Phase 4).
+     *
+     * The registry is authoritative and never rebuilt from the cache, so nothing
+     * else would ever remove a row: without this it grows for the life of the
+     * install, and every boot pays for rows about sessions from months ago.
+     */
+    pruneTerminalSessions(): void;
+    /**
+     * Seed the session list with what previous runs left behind (persistence plan
+     * Phase 1, gaps G1/G2/G8).
+     *
+     * Reconciliation classifies rows and stops there; a verdict is overlaid onto a
+     * SessionResponse that already exists, and after a clean restart none does —
+     * `SessionStore` starts empty. So the user's session did not become
+     * `resumable`, it became *absent*. This is the half that puts it back.
+     *
+     * The seeded stubs hold no PTY and are never handed to `LiveSessionManager`,
+     * so `reapIdleSessions` and `startGraceTimer` — both of which iterate
+     * `ptyManager.listSessions()` — cannot observe them. A later resume calls
+     * `sessionStore.addManaged` with the real session, which overwrites the stub
+     * by id rather than duplicating it.
+     */
+    rehydratePreviousSessions(verdicts: ReconcileVerdict[]): ManagedSessionRow[];
+    /** Resume only the recent sessions the user explicitly allowed us to start at boot. */
+    autoResumePreviousSessions(rows: ManagedSessionRow[]): Promise<void>;
+    /**
+     * Pick a token guaranteed to appear in the spawned process's argv, for the
+     * reconciler's pid-reuse guard.
+     *
+     * Claude always passes the session id (`--resume <id>` or `--session-id
+     * <id>`), so it is both present and unique. Codex only does on *resume*
+     * (`codex resume <id>`); a fresh Codex spawn is `codex --cd <path>
+     * --no-alt-screen` with no id at all, because the rollout id does not exist
+     * until the CLI writes it. boundConversationId is what distinguishes the two:
+     * it is set once that rollout has been discovered.
+     */
+    spawnArgvToken(session: ManagedSession): string;
+    /** Restore registry-only metadata after the host mirror has been adopted. */
+    refreshHostedSessionsFromRegistry(): void;
+    /**
+     * Mirror a freshly-spawned session into the durable registry (C1 Phase 2).
+     *
+     * Called at each addManaged() site rather than inside SessionStore, because
+     * the store is a pure in-memory structure with no DB dependency and adding
+     * one would drag persistence into every unit test that touches it.
+     *
+     * Best-effort by design: a failed registry write must never break session
+     * start. Losing a row costs post-restart *visibility* for that session, which
+     * is strictly better than refusing to run the agent at all.
+     */
+    recordSessionSpawn(session: ManagedSession): void;
+    /**
+     * Stamp every live session as ended-by-shutdown before dispose() kills it.
+     *
+     * PTYManager.dispose() signals each child directly and fires no
+     * onStatusChange, so the registry would otherwise keep rows sitting at
+     * `running` forever and the next boot could not tell a deliberate restart
+     * from a crash. Recording `shutdown` as the status source makes that
+     * distinction explicit rather than inferred.
+     *
+     * Not a `completed_at` write for the agent's own work — the agent did not
+     * finish, we stopped it — but the session is genuinely terminal, so it must
+     * leave the reconciler's probe set.
+     */
+    recordShutdownState(): void;
+}
+//# sourceMappingURL=session-registry-boot.d.ts.map

package/dist/session-registry-boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry-boot.d.ts","sourceRoot":"","sources":["../src/session-registry-boot.ts"],"names":[],"mappings":"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"}

package/dist/session-store.d.ts

@@ -0,0 +1,32 @@
+import type { DiscoveredProcess, ManagedSession, SessionCursor, SessionListPage, SessionListQuery, SessionResponse } from "./types";
+export declare class SessionStore {
+    private managed;
+    private discovered;
+    addManaged(session: ManagedSession): void;
+    /**
+     * Multi-agent mode only. Attach a dedupe LRU to a session record. Idempotent —
+     * calling twice keeps the existing LRU (and its contents).
+     */
+    initAgentSession(sessionId: string, dedupeCapacity: number): void;
+    updateManaged(sessionId: string, updates: Partial<ManagedSession>): ManagedSession | null;
+    removeManaged(sessionId: string): boolean;
+    /**
+     * The **live** stored record — mutating it mutates the store. Paired with
+     * `get()`, which hands back a throwaway response copy. Prefer
+     * `updateManaged()` for writes; this is for readers that need the internal
+     * shape (Date fields, `rehydrated`, …) rather than the wire shape.
+     */
+    getManaged(sessionId: string): ManagedSession | null;
+    setDiscovered(processes: DiscoveredProcess[]): void;
+    /**
+     * The **live** stored records — mutating an element mutates the store. Paired
+     * with `list()`, which hands back throwaway response copies.
+     */
+    listManaged(): ManagedSession[];
+    list(ptyAttachedIds: Set<string>): readonly Readonly<SessionResponse>[];
+    get(sessionId: string, ptyAttachedIds: Set<string>): Readonly<SessionResponse> | null;
+    paginate(ptyAttachedIds: Set<string>, query: SessionListQuery): SessionListPage;
+}
+export declare function encodeCursor(c: SessionCursor): string;
+export declare function decodeCursor(s: string): SessionCursor;
+//# sourceMappingURL=session-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,eAAe,EAGhB,MAAM,SAAS,CAAC;AAGjB,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,UAAU,CAAwC;IAE1D,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAExC;IAED;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAKhE;IAED,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,GAAG,IAAI,CAexF;IAED,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAExC;IAED;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAEnD;IAED,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAKlD;IAED;;;OAGG;IACH,WAAW,IAAI,cAAc,EAAE,CAE9B;IAUD,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,QAAQ,CAAC,eAAe,CAAC,EAAE,CAiBtE;IAKD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC,GAAG,IAAI,CASpF;IAOD,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,gBAAgB,GAAG,eAAe,CAsB9E;CACF;AAGD,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAErD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAgBrD"}

package/dist/session-watchers.d.ts

@@ -0,0 +1,60 @@
+import type { Conversation } from "@threadbase-sh/scanner";
+import type { ConversationCache } from "./conversation-cache";
+import type { CacheMetadataRepository } from "./db/repositories/cacheMetadata.repository";
+import type { ConversationsRepository } from "./db/repositories/conversations.repository";
+import type { ManagedSessionsRepository } from "./db/repositories/managed-sessions.repository";
+import type { ProjectsRepository } from "./db/repositories/projects.repository";
+import type { SessionsRepository } from "./db/repositories/sessions.repository";
+import type { LiveSessionManager } from "./live-session-manager";
+import type { ScannerManager } from "./scanner-manager";
+import type { ConversationWatcher } from "./services/conversations/conversationWatcher";
+import type { SessionStore } from "./session-store";
+import type { WSHub } from "./ws-hub";
+/**
+ * Everything SessionWatchers reads from the server. Collaborators constructed
+ * once in the server constructor are passed by reference; the ones opened
+ * during listen() (and rebound by the integrity monitor's reset-and-rescan) are
+ * thunks, for the same reason ApiDeps passes `cache: () => ConversationCache | null`.
+ *
+ * `broadcastConversationLines` / `findConversationByUuid` / `ptyAttachedIds`
+ * stay late-bound calls back into the server rather than moved code: they are
+ * server methods with their own dependencies (and tests spy on them).
+ */
+export type SessionWatchersDeps = {
+    ptyManager: LiveSessionManager;
+    sessionStore: SessionStore;
+    wsHub: WSHub;
+    fileWatcher: ConversationWatcher;
+    /** sessionId → JSONL filePath. Owned by the server; mutated in place here. */
+    sessionFileMap: Map<string, string>;
+    scannerManager: ScannerManager;
+    codexRoots: string[];
+    cache: () => ConversationCache | null;
+    projectsRepo: () => ProjectsRepository | null;
+    conversationsRepo: () => ConversationsRepository | null;
+    sessionsRepo: () => SessionsRepository | null;
+    cacheMetadataRepo: () => CacheMetadataRepository | null;
+    managedSessionsRepo: () => ManagedSessionsRepository | null;
+    findConversationByUuid: (uuid: string) => Promise<Conversation | null>;
+    broadcastConversationLines: (sessionId: string, lines: string[]) => void;
+    ptyAttachedIds: () => Set<string>;
+};
+/**
+ * Binds a live session to the transcript file its provider writes: finds the
+ * JSONL (Claude) or rollout (Codex), starts the tail watcher, replays whatever
+ * was written before the watcher attached, and links the session to its project.
+ *
+ * Extracted from StreamerServer so watcher work stops editing the server file
+ * (see docs/plans/2026-07-12-server-ts-split.md, PR 5).
+ */
+export declare class SessionWatchers {
+    private deps;
+    private log;
+    constructor(deps: SessionWatchersDeps);
+    linkSessionToProject(sessionId: string, projectPath: string, filePath: string): void;
+    watchConversationFile(sessionId: string, historyId?: string): Promise<void>;
+    readFirstLineSessionId(filePath: string): string | null;
+    watchForJsonl(sessionId: string, projectPath: string): void;
+    watchForCodexRollout(sessionId: string, projectPath: string): void;
+}
+//# sourceMappingURL=session-watchers.d.ts.map

package/dist/session-watchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-watchers.d.ts","sourceRoot":"","sources":["../src/session-watchers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAC1F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAC1F,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+CAA+C,CAAC;AAC/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,mBAAmB,CAAC;IACjC,8EAA8E;IAC9E,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAC;IAC9C,iBAAiB,EAAE,MAAM,uBAAuB,GAAG,IAAI,CAAC;IACxD,YAAY,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAC;IAC9C,iBAAiB,EAAE,MAAM,uBAAuB,GAAG,IAAI,CAAC;IACxD,mBAAmB,EAAE,MAAM,yBAAyB,GAAG,IAAI,CAAC;IAC5D,sBAAsB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACvE,0BAA0B,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACzE,cAAc,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,IAAI;IAFxB,OAAO,CAAC,GAAG,CAAuB;IAElC,YAAoB,IAAI,EAAE,mBAAmB,EAAI;IAIjD,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAuCnF;IAOK,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnF;IAMD,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWtD;IAKD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAmG1D;IAUD,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CA+JjE;CACF"}