ftown-bridge 0.19.0 → 0.19.2

package/dist/session-controller.js

@@ -0,0 +1,141 @@
+import { createFtownSession, relaunchFtownSession, } from './create-ftown-session.js';
+export class SessionController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    require(dep, name) {
+        if (dep === undefined) {
+            throw new Error(`SessionController: ${name} dependency not wired`);
+        }
+        return dep;
+    }
+    /** Create + launch a session. Throws (see class doc) — adapters map errors. */
+    async create(input) {
+        const factory = this.require(this.deps.sessionFactory, 'sessionFactory');
+        return createFtownSession(factory, input);
+    }
+    /** Stop a running session and persist/publish its completed state. */
+    async stop(sessionId) {
+        const stopped = this.deps.runner.stop(sessionId);
+        if (stopped) {
+            this.require(this.deps.publishSyntheticStop, 'publishSyntheticStop')(sessionId, 'stopped');
+            await this.require(this.deps.withSessionWrite, 'withSessionWrite')(sessionId, async () => {
+                const session = await this.deps.store.loadSession(sessionId);
+                if (session) {
+                    session.status = 'completed';
+                    session.updatedAt = new Date().toISOString();
+                    await this.deps.store.saveSession(session);
+                    await this.deps.publishSessionUpdate(session);
+                }
+            });
+            this.require(this.deps.unregisterSession, 'unregisterSession')(sessionId);
+        }
+        return { stopped };
+    }
+    list() {
+        return this.deps.store.listSessions();
+    }
+    get(sessionId) {
+        return this.deps.store.loadSession(sessionId);
+    }
+    /**
+     * Per-session token/cost usage. Returns the persisted snapshot when
+     * present; otherwise collects on demand (covers live sessions and sessions
+     * that finished before usage collection existed). An on-demand result is
+     * persisted + published only when the session is terminal — a live
+     * session's numbers are still moving, so caching them would go stale.
+     */
+    async usage(sessionId) {
+        const session = await this.deps.store.loadSession(sessionId);
+        if (!session) {
+            return { ok: false, code: 'not_found', message: 'Session not found' };
+        }
+        if (session.usage) {
+            return { ok: true, usage: session.usage };
+        }
+        const collect = this.deps.collectUsage;
+        if (!collect) {
+            return { ok: true, usage: null };
+        }
+        const usage = await collect(session);
+        if (usage && (session.status === 'completed' || session.status === 'error')) {
+            session.usage = usage;
+            session.updatedAt = new Date().toISOString();
+            await this.deps.store.saveSession(session);
+            await this.deps.publishSessionUpdate(session);
+        }
+        return { ok: true, usage };
+    }
+    /** Re-run a finished/dead session's stored command verbatim. */
+    async retry(sessionId) {
+        const factory = this.require(this.deps.sessionFactory, 'sessionFactory');
+        const existingSession = await this.deps.store.loadSession(sessionId);
+        if (!existingSession) {
+            return { ok: false, code: 'not_found', message: 'Session not found' };
+        }
+        if (existingSession.status === 'running') {
+            return { ok: false, code: 'conflict', message: 'Session is already running' };
+        }
+        if (!existingSession.command) {
+            return { ok: false, code: 'invalid', message: 'Session has no command (created before v0.2.0)' };
+        }
+        await relaunchFtownSession(factory, existingSession, 'retry');
+        return { ok: true, session: existingSession };
+    }
+    /**
+     * Rename and/or reparent in ONE load-mutate-save-publish pass (the HTTP
+     * PATCH route updates both fields atomically; the RPC adapter calls with a
+     * single field). Reparenting flattens to the proposed parent's root so
+     * session trees stay one level deep.
+     */
+    async update(sessionId, input) {
+        const session = await this.deps.store.loadSession(sessionId);
+        if (!session) {
+            return { ok: false, code: 'not_found', message: 'Session not found' };
+        }
+        if (input.name !== undefined) {
+            if (typeof input.name !== 'string' || !input.name) {
+                return { ok: false, code: 'invalid', message: 'Invalid name' };
+            }
+            session.name = input.name;
+        }
+        if (input.parent) {
+            const raw = input.parent.value;
+            if (raw === null || raw === undefined || raw === '') {
+                session.parentSessionId = undefined;
+            }
+            else if (typeof raw !== 'string') {
+                return { ok: false, code: 'invalid', message: 'Invalid parentSessionId' };
+            }
+            else if (raw === session.id) {
+                return { ok: false, code: 'invalid', message: 'Session cannot be its own parent' };
+            }
+            else {
+                const proposed = await this.deps.store.loadSession(raw);
+                if (!proposed) {
+                    return { ok: false, code: 'invalid', message: 'Parent session not found' };
+                }
+                session.parentSessionId = proposed.parentSessionId ?? proposed.id;
+            }
+        }
+        session.updatedAt = new Date().toISOString();
+        await this.deps.store.saveSession(session);
+        await this.deps.publishSessionUpdate(session);
+        return { ok: true, session };
+    }
+    /** Remove (archive + delete + publish removed). removed=false when nothing
+     * was removed — unknown id, or the onlyIfFinished guard rejected it. */
+    async remove(sessionId, options) {
+        const removed = await this.deps.removeSession(sessionId, options);
+        return { removed: removed !== null };
+    }
+    /** Flush pending output, wipe the persisted log, drop the live buffer. */
+    async clearTerminal(sessionId) {
+        this.require(this.deps.flushTerminalBuffer, 'flushTerminalBuffer')(sessionId);
+        await this.deps.store.clearTerminalLog(sessionId);
+        this.require(this.deps.destroyTerminal, 'destroyTerminal')(sessionId);
+        return { cleared: true };
+    }
+}
+//# sourceMappingURL=session-controller.js.map

package/dist/session-controller.js.map

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

package/dist/session-ids.d.ts

@@ -0,0 +1,19 @@
+import type { HookEvent } from './local-api-server.js';
+import type { SessionStore } from './session-store.js';
+import type { Session } from './types.js';
+export interface AgentSessionIdPersisterDeps {
+    store: Pick<SessionStore, 'loadSession' | 'saveSession'>;
+    publishSessionUpdate: (session: Session) => Promise<void>;
+}
+/**
+ * Persists agent-native session ids (Claude/Codex session_id, Cursor
+ * conversation_id) from hook events onto the stored session record, with an
+ * in-memory cache of the last persisted ids to skip disk reads on the hot
+ * hook path.
+ */
+export declare class AgentSessionIdPersister {
+    private readonly deps;
+    private readonly cache;
+    constructor(deps: AgentSessionIdPersisterDeps);
+    persist(hookEvent: HookEvent): Promise<void>;
+}

package/dist/session-ids.js

@@ -0,0 +1,72 @@
+/**
+ * Persists agent-native session ids (Claude/Codex session_id, Cursor
+ * conversation_id) from hook events onto the stored session record, with an
+ * in-memory cache of the last persisted ids to skip disk reads on the hot
+ * hook path.
+ */
+export class AgentSessionIdPersister {
+    deps;
+    cache = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async persist(hookEvent) {
+        // Workspace-fallback attribution may come from a foreign agent the user
+        // ran manually in the same directory; never persist its ids.
+        if (hookEvent.source === 'workspace')
+            return;
+        const rawAgentId = hookEvent.data['session_id'];
+        const rawCursorId = hookEvent.data['conversation_id'];
+        // Claude Code AND Codex hooks carry session_id (which field it lands in
+        // depends on the session's shellType); Cursor hooks carry conversation_id.
+        const agentId = typeof rawAgentId === 'string' && rawAgentId ? rawAgentId : undefined;
+        const cursorId = typeof rawCursorId === 'string' && rawCursorId ? rawCursorId : undefined;
+        if (!agentId && !cursorId)
+            return;
+        const cached = this.cache.get(hookEvent.sessionId);
+        if (cached
+            && (!agentId || (cached.isCodex ? cached.codex === agentId : cached.claude === agentId))
+            && (!cursorId || cached.cursor === cursorId)) {
+            return;
+        }
+        const session = await this.deps.store.loadSession(hookEvent.sessionId);
+        if (!session)
+            return;
+        const isCodex = session.shellType === 'codex';
+        let changed = false;
+        if (agentId) {
+            if (isCodex && session.codexSessionId !== agentId) {
+                session.codexSessionId = agentId;
+                changed = true;
+            }
+            else if (!isCodex && session.claudeSessionId !== agentId) {
+                session.claudeSessionId = agentId;
+                changed = true;
+            }
+        }
+        if (cursorId && session.cursorSessionId !== cursorId) {
+            session.cursorSessionId = cursorId;
+            changed = true;
+        }
+        if (!changed) {
+            this.cache.set(hookEvent.sessionId, {
+                claude: session.claudeSessionId,
+                cursor: session.cursorSessionId,
+                codex: session.codexSessionId,
+                isCodex,
+            });
+            return;
+        }
+        session.updatedAt = new Date().toISOString();
+        await this.deps.store.saveSession(session);
+        // Cache only after a successful save, so a failed persist is retried.
+        this.cache.set(hookEvent.sessionId, {
+            claude: session.claudeSessionId,
+            cursor: session.cursorSessionId,
+            codex: session.codexSessionId,
+            isCodex,
+        });
+        await this.deps.publishSessionUpdate(session);
+    }
+}
+//# sourceMappingURL=session-ids.js.map

package/dist/session-ids.js.map

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

package/dist/session-resurrection.d.ts

@@ -1,2 +1,26 @@
 import type { Session } from './types.js';
+import type { SessionStore } from './session-store.js';
+import type { ProcessRunner } from './claude-runner.js';
+import { type CreateFtownSessionDeps } from './create-ftown-session.js';
 export declare function shouldResurrectStoredSession(session: Session): boolean;
+export interface SessionResurrectionDeps {
+    store: SessionStore;
+    runner: ProcessRunner;
+    bridgeId: string;
+    sessionFactoryDeps: CreateFtownSessionDeps;
+    publishSessionUpdate: (session: Session) => Promise<void>;
+    wireTerminalInput: (sessionId: string) => void;
+}
+/**
+ * Resurrection engine: on bridge start, sessions left in a live state by a
+ * previous bridge are reattached (tmux), respawned (resume), or marked as
+ * error. Loop-run sessions are deferred to the loop scheduler.
+ */
+export declare class SessionResurrection {
+    private readonly deps;
+    private started;
+    constructor(deps: SessionResurrectionDeps);
+    private markSessionDead;
+    private resurrectSession;
+    resurrectSessions(): Promise<void>;
+}

package/dist/session-resurrection.js

@@ -1,6 +1,134 @@
+import { canResumeStoredSession, findMissingProviderAuth, relaunchFtownSession, } from './create-ftown-session.js';
+import { loadProviderEnv } from './provider-env-store.js';
+import { registerSessionWorkspace } from './session-registry.js';
+import { isTmuxAvailable, killTmuxSession, listFtownTmuxSessions } from './tmux.js';
 export function shouldResurrectStoredSession(session) {
     if (session.status !== 'running' && session.status !== 'pending')
         return false;
     return !session.loopId;
 }
+/**
+ * Resurrection engine: on bridge start, sessions left in a live state by a
+ * previous bridge are reattached (tmux), respawned (resume), or marked as
+ * error. Loop-run sessions are deferred to the loop scheduler.
+ */
+export class SessionResurrection {
+    deps;
+    started = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async markSessionDead(session, reason) {
+        session.status = 'error';
+        session.errorReason = reason;
+        session.updatedAt = new Date().toISOString();
+        await this.deps.store.saveSession(session);
+        await this.deps.publishSessionUpdate(session);
+        console.log(`[Bridge] Marked stale session ${session.id} as error`);
+    }
+    async resurrectSession(sessionId) {
+        const { store, runner, bridgeId, sessionFactoryDeps } = this.deps;
+        // Commands run concurrently with the resurrection loop; act on fresh
+        // state so a session stopped or removed mid-loop is not respawned.
+        const session = await store.loadSession(sessionId);
+        if (!session || (session.status !== 'running' && session.status !== 'pending'))
+            return;
+        if (runner.isRunning(session.id))
+            return;
+        if (runner.reattach(session.id, {
+            workingDir: session.workingDir,
+            parentSessionId: session.parentSessionId,
+        })) {
+            session.status = 'running';
+            session.bridgeId = bridgeId;
+            session.errorReason = undefined;
+            session.updatedAt = new Date().toISOString();
+            await store.saveSession(session);
+            await this.deps.publishSessionUpdate(session);
+            this.deps.wireTerminalInput(session.id);
+            registerSessionWorkspace(session.id, session.workingDir);
+            console.log(`[Bridge] Resurrected session ${session.id} via tmux reattach`);
+            return;
+        }
+        if (canResumeStoredSession(session)) {
+            const miss = findMissingProviderAuth(session.shellType, {
+                processEnv: process.env,
+                storeEnv: loadProviderEnv(),
+            });
+            if (miss) {
+                await this.markSessionDead(session, miss.message);
+                return;
+            }
+            // The custom-vs-rebuilt resume-command decision lives in
+            // deriveRelaunchCommand, inside relaunchFtownSession.
+            const resumeCommand = await relaunchFtownSession(sessionFactoryDeps, session, 'resume');
+            console.log(`[Bridge] Resurrected session ${session.id} via resume respawn: ${resumeCommand}`);
+            return;
+        }
+        await this.markSessionDead(session);
+    }
+    async resurrectSessions() {
+        if (this.started)
+            return;
+        this.started = true;
+        const { store } = this.deps;
+        const sessions = await store.listSessions();
+        // Reap tmux sessions for OUR dead store records (removed records, failed
+        // kills) before resurrection re-creates any. Archived tombstones count as
+        // dead too: remove_session deletes the store record, so a failed tmux
+        // kill would otherwise leave a permanently invisible live agent. Tmux
+        // sessions with ids we have no record of are left alone — they may
+        // belong to another bridge running on this machine.
+        if (isTmuxAvailable()) {
+            const archived = await store.listArchived();
+            const deadIds = new Set([
+                ...sessions
+                    .filter((s) => s.status !== 'running' && s.status !== 'pending')
+                    .map((s) => s.id),
+                ...archived.map((a) => a.id),
+            ]);
+            // A live store record outranks any tombstone for the same id (crash
+            // between archive and delete leaves both): never reap resurrectables.
+            for (const s of sessions) {
+                if (s.status === 'running' || s.status === 'pending') {
+                    deadIds.delete(s.id);
+                }
+            }
+            for (const tmuxId of listFtownTmuxSessions()) {
+                if (deadIds.has(tmuxId)) {
+                    console.log(`[Bridge] Killing tmux session for dead session ${tmuxId}`);
+                    await killTmuxSession(tmuxId);
+                }
+            }
+        }
+        let deferredLoopRuns = 0;
+        for (const session of sessions) {
+            if (session.loopId) {
+                if (session.status !== 'running' && session.status !== 'pending')
+                    continue;
+                deferredLoopRuns += 1;
+                continue;
+            }
+            if (!shouldResurrectStoredSession(session))
+                continue;
+            try {
+                await this.resurrectSession(session.id);
+            }
+            catch (err) {
+                console.error(`[Bridge] Failed to resurrect session ${session.id}:`, err);
+                try {
+                    const current = await store.loadSession(session.id);
+                    if (current)
+                        await this.markSessionDead(current);
+                }
+                catch (markErr) {
+                    console.error(`[Bridge] Failed to mark session ${session.id} as error:`, markErr);
+                }
+            }
+        }
+        if (deferredLoopRuns > 0) {
+            console.log(`[Bridge] Deferred ${deferredLoopRuns} loop-run session(s) to the loop scheduler`);
+        }
+    }
+}
 //# sourceMappingURL=session-resurrection.js.map

package/dist/session-resurrection.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-resurrection.js","sourceRoot":"","sources":["../src/session-resurrection.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,4BAA4B,CAAC,OAAgB;IAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC/E,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;AACzB,CAAC"}
+{"version":3,"file":"session-resurrection.js","sourceRoot":"","sources":["../src/session-resurrection.ts"],"names":[],"mappings":"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"}

package/dist/spawn-stagger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-key spawn stagger: serializes concurrent callers of the same key so
+ * their spawns land at least `minGapMs` apart.
+ *
+ * Why: some harness CLIs (cursor-agent) refresh an auth token on startup with
+ * a read-modify-write against the macOS Keychain. Two or more concurrent
+ * startups race that write (pure last-writer-wins) and corrupt the stored
+ * credential. Spacing spawns by a small gap fully eliminates the race.
+ *
+ * Algorithm: a monotonic slot reservation per key. Each caller SYNCHRONOUSLY
+ * (before any await — this is what makes it lock-free under the single-threaded
+ * event loop) reserves `slot = max(now, lastSlot + minGapMs)`, records it as
+ * the new lastSlot, then sleeps until its slot. N concurrent callers therefore
+ * serialize at exactly `minGapMs` intervals; a caller arriving after the queue
+ * has drained (now >= lastSlot + minGapMs) gets slot = now and no delay.
+ */
+export declare function staggerSpawn(key: string, minGapMs: number, opts?: {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+/** Clears all reserved slots. Test seam only. */
+export declare function resetSpawnStaggerForTest(): void;

package/dist/spawn-stagger.js

@@ -0,0 +1,34 @@
+/**
+ * Per-key spawn stagger: serializes concurrent callers of the same key so
+ * their spawns land at least `minGapMs` apart.
+ *
+ * Why: some harness CLIs (cursor-agent) refresh an auth token on startup with
+ * a read-modify-write against the macOS Keychain. Two or more concurrent
+ * startups race that write (pure last-writer-wins) and corrupt the stored
+ * credential. Spacing spawns by a small gap fully eliminates the race.
+ *
+ * Algorithm: a monotonic slot reservation per key. Each caller SYNCHRONOUSLY
+ * (before any await — this is what makes it lock-free under the single-threaded
+ * event loop) reserves `slot = max(now, lastSlot + minGapMs)`, records it as
+ * the new lastSlot, then sleeps until its slot. N concurrent callers therefore
+ * serialize at exactly `minGapMs` intervals; a caller arriving after the queue
+ * has drained (now >= lastSlot + minGapMs) gets slot = now and no delay.
+ */
+const lastSlotByKey = new Map();
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function staggerSpawn(key, minGapMs, opts) {
+    const now = opts?.now ?? Date.now;
+    const sleep = opts?.sleep ?? defaultSleep;
+    // Reserve the slot synchronously — no await may happen before this point.
+    const arrival = now();
+    const lastSlot = lastSlotByKey.get(key);
+    const slot = lastSlot === undefined ? arrival : Math.max(arrival, lastSlot + minGapMs);
+    lastSlotByKey.set(key, slot);
+    const waitMs = slot - arrival;
+    return waitMs > 0 ? sleep(waitMs) : Promise.resolve();
+}
+/** Clears all reserved slots. Test seam only. */
+export function resetSpawnStaggerForTest() {
+    lastSlotByKey.clear();
+}
+//# sourceMappingURL=spawn-stagger.js.map

package/dist/spawn-stagger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-stagger.js","sourceRoot":"","sources":["../src/spawn-stagger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEhD,MAAM,YAAY,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,QAAgB,EAChB,IAAoE;IAEpE,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,YAAY,CAAC;IAE1C,0EAA0E;IAC1E,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;IACtB,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IACvF,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAE7B,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;IAC9B,OAAO,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,wBAAwB;IACtC,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/terminal-pump.d.ts

@@ -0,0 +1,61 @@
+import type { ProcessRunner } from './claude-runner.js';
+import type { SessionStore } from './session-store.js';
+import type { TerminalManager } from './terminal-manager.js';
+import type { Session, SessionUsage } from './types.js';
+export type SyntheticStopReason = 'complete' | 'error' | 'stopped';
+export interface TerminalPumpDeps {
+    store: Pick<SessionStore, 'appendTerminalData' | 'loadSession' | 'saveSession' | 'loadTerminalLog'>;
+    terminalManager: Pick<TerminalManager, 'write' | 'destroy'>;
+    publishTerminalData: (sessionId: string, data: string) => void;
+    publishSessionUpdate: (session: Session) => Promise<void>;
+    publishHookEvent: (sessionId: string, event: Record<string, unknown>) => Promise<void>;
+    unregisterSession: (sessionId: string) => void;
+    /**
+     * Optional (injectable for tests): extract token/cost usage from the
+     * session's harness-native transcript. Fired-and-forgotten after the
+     * terminal status persist on complete/error; a null result never clobbers
+     * previously persisted usage.
+     */
+    collectUsage?: (session: Session) => Promise<SessionUsage | null>;
+    /** Test seams; production uses the defaults. */
+    flushIntervalMs?: number;
+    maxBufferBytes?: number;
+}
+/**
+ * Terminal output pump: buffers runner PTY output per session (coalescing into
+ * ≤16ms / ≤32KB flushes to the store + transports), and owns the runner
+ * lifecycle handlers ('complete'/'error') that persist final loop-run/session
+ * statuses — the loop scheduler reads the statuses this module produces.
+ */
+export declare class TerminalPump {
+    private readonly deps;
+    private readonly outputBuffers;
+    private readonly flushTimers;
+    private readonly sessionWrites;
+    private readonly flushIntervalMs;
+    private readonly maxBufferBytes;
+    constructor(deps: TerminalPumpDeps);
+    /** Wire the pump onto the runner's data/lifecycle events. */
+    attach(runner: Pick<ProcessRunner, 'on'>): void;
+    handleData(sessionId: string, data: string): void;
+    flush(sessionId: string): void;
+    withSessionWrite(sessionId: string, task: () => Promise<void>): Promise<void>;
+    publishSyntheticStop(sessionId: string, reason: SyntheticStopReason): void;
+    /**
+     * Fire-and-forget usage collection after a terminal status persist. Runs
+     * OUTSIDE the caller's write (the collect can take seconds on huge
+     * transcripts); the persist itself is serialized via withSessionWrite.
+     * Guard: a null collection result never clobbers previously saved usage.
+     */
+    private collectAndPersistUsage;
+    private handleComplete;
+    /**
+     * `<error message> — <recent terminal tail>` (ANSI-stripped, whitespace
+     * collapsed, capped at ~400 chars) so a startup crash's cause is readable
+     * straight off the session record. The tail comes from the flushed terminal
+     * log; flush() fires its append without awaiting, so the chunk buffered at
+     * error time is re-appended if it hasn't landed on disk yet.
+     */
+    private buildErrorReason;
+    private handleError;
+}