@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/browser-server.js

@@ -0,0 +1,1189 @@
+import { createServer } from 'node:http';
+import lockfile from 'proper-lockfile';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { readFile, readdir, mkdir, stat, realpath } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join, resolve } from 'node:path';
+import { configDirectory, loadConfig } from './config.js';
+import { SessionWriteFence, SessionStore, sessionName, writeSessionSnapshot, removeSessionSnapshot, savedSessionFields, carryRailOwnedFields, primaryDigest, projectIdentity, validSavedSession } from './sessions.js';
+import { acquireSessionMutationLock, SessionMutationLockHeldError, sessionHasOpenRun } from './run-records.js';
+import { createBrowserBridge, validBrowserSession, browserAuthorized, browserBody, browserReply, discoverBrowserSessions, assertBrowserSessionUnowned } from './browser-bridge.js';
+import { readSessionTrajectory } from './app-server/workspace.js';
+import { runBrowserTask } from './browser-runner.js';
+import { configuredSurface, reportSessionStarted } from './telemetry/surface.js';
+import { currentGraphSubject } from './graph-selection.js';
+import { createSessionTrajectory } from './trajectory.js';
+import { boundBrowserActivity } from './browser-activity.js';
+/**
+ * A required save found this session's mutation lock held by another writer, so its round did not happen.
+ *
+ * The message is what the surface shows; the type is what lets the one caller that owes a completed turn
+ * retry it, instead of treating contention and a broken filesystem as the same answer.
+ */
+export class SessionSaveContendedError extends Error {
+}
+/**
+ * The rail's filing and name pin, applied to a copy of the record before it is written.
+ *
+ * Both copies this save writes have to say the same thing about those fields. Hydrate decides what a
+ * run that died mid-prompt was doing by comparing the primary's digest against the archive's, and a
+ * primary carrying `archived` while its archive does not makes those digests differ for as long as
+ * the filing stands — the exact difference `independentlyUpdated` reads as "another writer moved on",
+ * which restores a session whose engine was killed as idle and drops the recoverable prompt. Same rule
+ * as the CLI's save, shared through `carryRailOwnedFields`; the one exemption is the acceptance save,
+ * which clears the flag in both copies because work the user just started belongs on the working rail.
+ */
+function withRailFields(target, predecessor, carryFiling) {
+    carryRailOwnedFields(target, predecessor);
+    if (!carryFiling) {
+        delete target.archived;
+        delete target.autoArchived;
+    }
+    return target;
+}
+/**
+ * The status a browser-written turn must carry into the saved record.
+ *
+ * A turn's status is read off its completion, and a completion with no status IS a normal completion —
+ * that is the engine's contract, and it is what lets a finished task still read as finished after a
+ * reload. The browser surface ends a turn from a result that can say `cancelled`, `exhausted`,
+ * `needs_clarification` or `infrastructure_error`, and from catches that know only that the attempt did
+ * not finish. Saving those turns status-less would hand the rail a green completed mark for work that
+ * failed or was interrupted, so every terminal write here stamps what actually happened.
+ */
+function terminalCompletion(completion, status) {
+    return completion.status === undefined ? { ...completion, status } : completion;
+}
+async function readSnapshot(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function startBrowserServer(options = {}) {
+    const directory = options.directory ?? configDirectory();
+    const store = new SessionStore(directory);
+    const token = randomBytes(32).toString('hex');
+    let origin = '';
+    let closing = false;
+    const sanitizer = await createSessionTrajectory({ directory: join(directory, 'browser-trajectories') });
+    const refreshSecrets = async () => {
+        const config = await loadConfig(directory);
+        const secrets = config.providers.flatMap(provider => [provider.apiKey || '', provider.apiKeyEnv ? process.env[provider.apiKeyEnv] || '' : '']);
+        sanitizer.addSecrets(secrets);
+        return secrets;
+    };
+    await refreshSecrets();
+    const publicState = (state) => {
+        boundBrowserActivity(state.events);
+        // Keep routing UUIDs and validated timestamp/status metadata canonical;
+        // redacting them would break discovery or control of the public projection.
+        return { ...sanitizer.sanitize(state), id: state.id, parentId: state.parentId, updatedAt: state.updatedAt, status: state.status };
+    };
+    const bridges = new Map();
+    const writes = new SessionWriteFence();
+    const leases = new Map();
+    const lostOwnership = new Set();
+    const failedRollbacks = new Set();
+    const ownershipAcquisitions = new Set();
+    const acquisitionSignals = new Set();
+    const forwardedRequests = new Set();
+    const acquireOwner = async (state, fresh = false) => {
+        const cancellation = new AbortController();
+        acquisitionSignals.add(cancellation);
+        try {
+            return await acquireOwnerInner(state, fresh, cancellation.signal);
+        }
+        finally {
+            acquisitionSignals.delete(cancellation);
+        }
+    };
+    const acquireOwnerInner = async (state, fresh, cancellation) => {
+        if (closing)
+            throw new Error('Application is shutting down');
+        if (bridges.has(state.id))
+            return;
+        // A freshly generated id cannot already be held by another descriptor;
+        // an unrelated bridge outage must not block creating a new session.
+        if (!fresh)
+            await assertBrowserSessionUnowned(directory, state.id);
+        const folder = join(directory, 'browser-owners');
+        await mkdir(folder, { recursive: true, mode: 0o700 });
+        const path = join(folder, state.id);
+        let release;
+        try {
+            release = await lockfile.lock(path, { realpath: false, stale: 10000, update: 2000, onCompromised: () => {
+                    lostOwnership.add(state.id);
+                    running.get(state.id)?.abort.abort(new Error('Session ownership was lost'));
+                    const bridge = bridges.get(state.id);
+                    bridges.delete(state.id);
+                    owned.delete(state.id);
+                    // The lost-ownership guard fences future writes, but submitted OS
+                    // replacements cannot be cancelled. Keep discovery fail-closed until
+                    // those settle, just as normal shutdown does, while closing the listener.
+                    void bridge?.close(writes.replacements.size ? writes.settled() : undefined).catch(() => { });
+                } });
+        }
+        catch {
+            throw new Error('Session is owned by another application. Refresh to reconnect. After a crash, wait 10 seconds before retrying.');
+        }
+        try {
+            if (closing)
+                throw new Error('Application is shutting down');
+            const bridge = await createBrowserBridge(directory, () => publicState(state), {
+                prompt: text => execute(state, text),
+                steer: text => { const job = running.get(state.id); if (!job || !state.live)
+                    throw new Error('Session is idle'); if (job.abort.signal.aborted)
+                    throw new Error('Session is cancelling'); job.steering.push(text); },
+                cancel: () => cancel(state),
+                answer: answer => { const job = running.get(state.id); if (!job?.answer)
+                    throw new Error('Question is no longer pending'); job.answer(answer); },
+            }, cancellation);
+            if (closing) {
+                await bridge.close();
+                throw new Error('Application is shutting down');
+            }
+            leases.set(path, release);
+            bridges.set(state.id, bridge);
+            owned.set(state.id, state);
+        }
+        catch (error) {
+            await release();
+            leases.delete(path);
+            throw error;
+        }
+    };
+    const ensureOwner = (state, fresh = false) => {
+        const acquisition = acquireOwner(state, fresh);
+        ownershipAcquisitions.add(acquisition);
+        void acquisition.finally(() => ownershipAcquisitions.delete(acquisition)).catch(() => { });
+        return acquisition;
+    };
+    const owned = new Map();
+    const running = new Map();
+    const cancel = (state) => {
+        const job = running.get(state.id);
+        if (!job || !state.live)
+            throw new Error('Session is idle or disconnected');
+        if (job.abort.signal.aborted)
+            throw new Error('Session is cancelling');
+        state.status = 'cancelling';
+        state.pending = undefined;
+        state.updatedAt = new Date().toISOString();
+        job.steering.length = 0;
+        job.abort.abort(new Error('Cancelled by user'));
+        checkpoint(state);
+    };
+    const folder = join(directory, 'browser-history');
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    const listRecords = async () => {
+        const records = await store.list();
+        const primaryIds = new Set(records.map(record => record.id));
+        for (const name of await readdir(folder)) {
+            if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\.json$/i.test(name) || primaryIds.has(name.slice(0, -5)))
+                continue;
+            try {
+                // Recover an archive-only first CLI save, but never replace an existing
+                // primary (including a damaged one) with potentially stale context.
+                if (await readSnapshot(join(directory, 'sessions', name)) !== undefined)
+                    continue;
+                const saved = JSON.parse(await readFile(join(folder, name), 'utf8'));
+                if (!validBrowserSession(saved) || name !== `${saved.id}.json`)
+                    continue;
+                records.push(savedSessionFields(saved));
+            }
+            catch { /* One damaged archive must not hide other retained sessions. */ }
+        }
+        return records;
+    };
+    let settings = { maxAgeDays: 30, theme: 'system' };
+    const refreshSettings = async () => {
+        try {
+            const saved = JSON.parse(await readFile(join(directory, 'browser-settings.json'), 'utf8'));
+            if (Number.isInteger(saved.maxAgeDays) && saved.maxAgeDays >= 0 && saved.maxAgeDays <= 36500)
+                settings = { maxAgeDays: saved.maxAgeDays, theme: ['system', 'light', 'dark'].includes(saved.theme) ? saved.theme : 'system' };
+        }
+        catch { /* retain defaults or last valid setting */ }
+    };
+    await refreshSettings();
+    const saves = new Map();
+    const saveGenerations = new Map();
+    const invalidateSaves = (id) => {
+        saveGenerations.set(id, (saveGenerations.get(id) ?? 0) + 1);
+        clearTimeout(checkpoints.get(id));
+        checkpoints.delete(id);
+    };
+    const dirtyCompleted = new Set();
+    const checkpoints = new Map();
+    const assertOwnership = (id) => { if (lostOwnership.has(id))
+        throw new Error('Session ownership was lost. Reopen this application before retrying.'); };
+    // `carryFiling` is false only for the save that accepts a prompt: that one deliberately files
+    // the session onto the working rail. Every other save carries the record's own filing instead.
+    const save = (state, required = false, carryFiling = true) => {
+        clearTimeout(checkpoints.get(state.id));
+        checkpoints.delete(state.id);
+        if (lostOwnership.has(state.id))
+            return required ? Promise.reject(new Error('Session ownership was lost. Reopen this application before retrying.')) : Promise.resolve();
+        // Public path redaction must not change where a retained session executes.
+        // Activity/history remain sanitized in both durable records.
+        const snapshot = { ...publicState({ ...state, pending: undefined, live: undefined }), workspace: state.workspace, updatedAt: state.updatedAt };
+        const content = JSON.stringify(snapshot);
+        const generation = saveGenerations.get(state.id) ?? 0;
+        const pending = (saves.get(state.id) ?? Promise.resolve()).catch(() => { }).then(async () => {
+            if (generation !== (saveGenerations.get(state.id) ?? 0)) {
+                if (required)
+                    throw new Error('Session save was invalidated');
+                return;
+            }
+            if (!required && lostOwnership.has(state.id))
+                return;
+            const assertCanWrite = writes.guard(() => {
+                assertOwnership(state.id);
+                if (generation !== (saveGenerations.get(state.id) ?? 0))
+                    throw new Error('Session save was invalidated');
+            });
+            assertCanWrite();
+            // The primary record's filing and name pin are the rail's changes, not this surface's
+            // state: the desktop renames or archives through its own process, while this cached state
+            // can predate that write. Take the same per-session mutation lock every rail rename,
+            // archive, and delete takes, and read the record under it, so a change that landed while
+            // this save queued is carried forward instead of overwritten: while the rail says the user
+            // chose the name, that name and its pin survive this save (auto-titling is for unnamed
+            // sessions only); while this session is not live, the record's own filing decides — a task
+            // filed away on the desktop during an idle window of this surface stays filed away, and one
+            // let back out does not silently return. A filing made while this surface's own run is live
+            // is carried too: the desktop's guard answers from open-run claims, which a browser task does
+            // not write, so filing a running browser session is a legitimate change from there — and a
+            // cached state that predates it must not undo it. The exempt save is the acceptance save
+            // below, which passes `carryFiling = false` because work the user started belongs on the
+            // working rail.
+            let releaseRailLock;
+            try {
+                releaseRailLock = await acquireSessionMutationLock(directory, state.id);
+            }
+            catch (error) {
+                if (error instanceof SessionMutationLockHeldError) {
+                    if (required)
+                        throw new SessionSaveContendedError('That session is being changed in another window. Wait a moment, then try again.');
+                    return; // A best-effort checkpoint skipping one round is safe; a stale overwrite is not.
+                }
+                throw error;
+            }
+            try {
+                assertCanWrite();
+                // Record the exact predecessor, not a timestamp: primary-only CLI resets
+                // must win even when they share the archive's millisecond timestamp.
+                const previous = await readSnapshot(join(directory, 'sessions', `${state.id}.json`));
+                const predecessor = previous === undefined ? undefined : JSON.parse(previous);
+                const cached = JSON.parse(content);
+                const archive = withRailFields({ ...cached, previousPrimaryDigest: predecessor === undefined ? undefined : primaryDigest(predecessor) }, predecessor, carryFiling);
+                await writeSessionSnapshot(join(folder, `${state.id}.json`), JSON.stringify(archive), assertCanWrite);
+                assertCanWrite();
+                // Both copies from one rule, so the two records a crash leaves behind agree on what the rail
+                // decided and hydrate reads one answer rather than a contradiction between them.
+                await store.save(withRailFields(savedSessionFields(cached), predecessor, carryFiling), assertCanWrite);
+                assertCanWrite();
+                if (saves.get(state.id) === pending)
+                    dirtyCompleted.delete(state.id);
+            }
+            finally {
+                await releaseRailLock?.().catch(() => { });
+            }
+        }).catch(error => {
+            // Invalidate before exposing a rejected required write to successors in
+            // the queue: their snapshots may still contain this rejected prompt.
+            if (required && generation === (saveGenerations.get(state.id) ?? 0))
+                invalidateSaves(state.id);
+            throw error;
+        });
+        saves.set(state.id, pending);
+        void pending.finally(() => { if (saves.get(state.id) === pending)
+            saves.delete(state.id); }).catch(() => { });
+        return pending;
+    };
+    /**
+     * Persist the state a finished run left behind.
+     *
+     * A completed turn is not a checkpoint. The best-effort save skips its round while another writer holds
+     * this session's mutation lock, and a promise that resolves having written nothing tells finalization
+     * nothing: the run reports done while the durable record still says the prompt is running, and an exit
+     * before the next save loses the turn the user just watched finish. So this asks for the required save,
+     * which reports the contention instead of swallowing it, and gives the other writer's release a bounded
+     * chance. A write that fails for any other reason still rejects, because the finalizer's reporting of it
+     * — the notice on the session and the error it logs — is the answer the user gets today and must keep
+     * getting. Only contention is sat on, and only briefly.
+     */
+    const persistCompleted = (completed) => {
+        const settle = async (budgetMs) => {
+            const deadline = Date.now() + budgetMs;
+            let retried = false;
+            for (;;) {
+                try {
+                    await save(completed, true);
+                    return true;
+                }
+                catch (error) {
+                    // A newer save owns this state now, so that path owes the durability, not this one. Losing
+                    // ownership means the tab is gone, and retrying a save the close drain will not want is noise.
+                    if (error instanceof Error && error.message === 'Session save was invalidated')
+                        return false;
+                    if (lostOwnership.has(completed.id))
+                        return false;
+                    // A write that really failed has nothing to wait out. It gets the single immediate retry the
+                    // finalizer has always made, and then rejects so the finalizer can report it.
+                    if (!(error instanceof SessionSaveContendedError)) {
+                        if (retried)
+                            throw error;
+                        retried = true;
+                        continue;
+                    }
+                    if (Date.now() >= deadline)
+                        return false;
+                    await new Promise(done => setTimeout(done, 250));
+                }
+            }
+        };
+        // Two seconds of patience covers the case that actually happens — a peer finishing its own write —
+        // and lands the turn before the run reports out. Past that the retry goes detached: a finished run
+        // must not look hung because persistence is contended, and a turn that never lands stays dirty for
+        // the close-time drain, which is the point the old skip failed.
+        // The detached pass has no listener left to tell: the run is already reported done. The state stays
+        // dirty, so the close-time drain is what answers for it if this never lands.
+        return settle(2_000).then(landed => { if (!landed)
+            void settle(60_000).catch(() => { }); });
+    };
+    // Append-only trajectory recording remains on the event path. Coalesce the
+    // expensive full archive checkpoints, then flush all state at run completion.
+    const checkpoint = (state) => {
+        if (checkpoints.has(state.id) || lostOwnership.has(state.id))
+            return;
+        checkpoints.set(state.id, setTimeout(() => {
+            void save(state).catch(error => console.error('Browser history checkpoint failed:', sanitizer.sanitize(error instanceof Error ? error.message : String(error))));
+        }, 1000));
+    };
+    /**
+     * Rename, file away, or delete a saved session: the desktop rail's own changes, made from this surface.
+     *
+     * The rules are the app server's (`renameSession`, `setSessionArchived`, `deleteSession`): the primary
+     * record is changed under the per-session mutation lock, and a session with a run in flight anywhere is
+     * refused, because that run saves the record it captured and would undo the change — or, for a delete,
+     * recreate the session. A session another process holds live (a terminal, another browser workspace) is
+     * refused too: that owner's state would keep showing, and re-saving, what it had. This surface's own
+     * idle state is updated alongside the record, because hydrate answers from it; its later saves carry
+     * the name pin and the filing forward from the record (`withRailFields`).
+     *
+     * Two fences hold for the whole change. In this process, `managing` keeps a prompt from being accepted
+     * until the change is done (`execute` checks it in the same step that marks the session running), so a
+     * delete cannot be followed by an acceptance save that recreates the session. Across processes, a
+     * session this application does not own has its ownership lease taken for the duration — the lease
+     * another browser workspace must hold to prompt it — and a live owner that cannot be reached refuses
+     * the change rather than being taken for absent.
+     */
+    const managing = new Set();
+    const manageSession = async (id, change, body, live) => {
+        const name = change === 'rename' && typeof body.name === 'string' ? body.name.trim() : '';
+        if (change === 'rename' && (!name || name.length > 200))
+            throw new Error('Enter a name up to 200 characters');
+        if (change === 'archive' && typeof body.archived !== 'boolean')
+            throw new Error('archived must be true or false');
+        const verb = change === 'archive' ? (body.archived ? 'archive' : 'unarchive') : change;
+        const assertIdle = () => { if (running.has(id))
+            throw new Error(`That session is running. Stop the run or wait for it to finish, then ${verb} it.`); };
+        assertIdle();
+        if (managing.has(id))
+            throw new Error('That session is already being changed. Wait a moment, then try again.');
+        managing.add(id);
+        let releaseLease;
+        try {
+            const otherOwner = new Error(`That session is open in a terminal or another browser workspace. Close it there, then ${verb} it.`);
+            if (!bridges.has(id)) {
+                if (live.some(endpoint => endpoint.state.id === id))
+                    throw otherOwner;
+                const owners = join(directory, 'browser-owners');
+                await mkdir(owners, { recursive: true, mode: 0o700 });
+                try {
+                    releaseLease = await lockfile.lock(join(owners, id), { realpath: false, stale: 10000, update: 2000, onCompromised: () => { } });
+                }
+                catch {
+                    throw otherOwner;
+                }
+                try {
+                    await assertBrowserSessionUnowned(directory, id);
+                }
+                catch (error) {
+                    throw error instanceof Error && error.message.startsWith('Session is owned') ? otherOwner : error;
+                }
+            }
+            await changeSession(id, change, body, name, verb, assertIdle);
+        }
+        finally {
+            await releaseLease?.().catch(() => { });
+            managing.delete(id);
+        }
+    };
+    const changeSession = async (id, change, body, name, verb, assertIdle) => {
+        if (await sessionHasOpenRun(directory, id))
+            throw new Error(`That session is running in another window. Cancel the run or wait for it to finish, then ${verb} it.`);
+        if (change === 'delete') {
+            // A queued checkpoint would write the record back after the removal. Invalidated, it settles without
+            // writing; it is awaited before the lock is taken, because the save itself takes that lock.
+            invalidateSaves(id);
+            await saves.get(id)?.catch(() => { });
+        }
+        let release;
+        try {
+            release = await acquireSessionMutationLock(directory, id);
+        }
+        catch (error) {
+            if (error instanceof SessionMutationLockHeldError)
+                throw new Error('That session is being changed in another window. Wait a moment, then try again.');
+            throw error;
+        }
+        try {
+            // A prompt accepted while the lock was being taken owns the session now, and so does a desktop or
+            // terminal run that published its claim while this request waited: preparing a run holds this same
+            // lock until its claim is written, so the answer read here is the one that counts.
+            assertIdle();
+            if (await sessionHasOpenRun(directory, id))
+                throw new Error(`That session is running in another window. Cancel the run or wait for it to finish, then ${verb} it.`);
+            const primaryPath = join(directory, 'sessions', `${id}.json`);
+            const raw = await readSnapshot(primaryPath);
+            // A session whose first save reached only this surface's archive has no primary yet.
+            const archiveOnly = raw === undefined ? (await listRecords()).find(record => record.id === id) : undefined;
+            if (raw === undefined && archiveOnly === undefined)
+                throw new Error('Session not found');
+            if (change === 'delete') {
+                // The record goes first, then this surface's copy: a failure in between leaves a session that is
+                // still listed and can be deleted again, never an archive that resurrects a deleted record.
+                await removeSessionSnapshot(primaryPath);
+                await removeSessionSnapshot(join(folder, `${id}.json`));
+                dirtyCompleted.delete(id);
+                const bridge = bridges.get(id);
+                bridges.delete(id);
+                owned.delete(id);
+                const ownerPath = join(directory, 'browser-owners', id);
+                const releaseLease = leases.get(ownerPath);
+                leases.delete(ownerPath);
+                try {
+                    await bridge?.close();
+                }
+                finally {
+                    await releaseLease?.();
+                }
+                return;
+            }
+            let record = archiveOnly;
+            if (raw !== undefined) {
+                try {
+                    record = JSON.parse(raw);
+                }
+                catch {
+                    record = undefined;
+                }
+            }
+            if (!validSavedSession(record) || record.id !== id)
+                throw new Error('That session record is damaged. Delete it, or repair the file in your sessions folder.');
+            const now = new Date().toISOString();
+            // `renamed` pins the name against the automatic titling a first prompt applies; a rename is news,
+            // so it moves the session up the list, while filing is organization and leaves the order alone.
+            const apply = (target) => change === 'rename'
+                ? { ...target, name, renamed: true, updatedAt: now }
+                : { ...target, archived: body.archived };
+            // This surface's copy is what hydrate recovers a crashed run from: the prompt that was running and
+            // the turn it owes. Hydrate trusts it while it agrees with the record (or is the newer of the two),
+            // and reads a record that changed alone as another writer moving on — idle, with that turn dropped.
+            // So while the copy is current, the change goes into it first, naming the record it was made over,
+            // and the record is then written from it: a crash between the two writes leaves the copy as the
+            // newer one, and after both they agree again. A copy another writer already superseded stays as it
+            // is, and only the record changes, as the desktop's rename does.
+            let copy;
+            try {
+                const { previousPrimaryDigest, ...saved } = JSON.parse(await readFile(join(folder, `${id}.json`), 'utf8'));
+                if (validBrowserSession(saved) && saved.id === id)
+                    copy = { ...saved, previousPrimaryDigest };
+            }
+            catch { /* No copy, or an unreadable one: the record alone is the session. */ }
+            const recordDigest = raw === undefined ? undefined : primaryDigest(record);
+            const copyCurrent = copy !== undefined && (recordDigest === undefined || copy.previousPrimaryDigest === recordDigest || primaryDigest(copy) === recordDigest);
+            let updated;
+            if (copy !== undefined && copyCurrent) {
+                const content = apply(copy);
+                delete content.previousPrimaryDigest;
+                await writeSessionSnapshot(join(folder, `${id}.json`), JSON.stringify({ ...content, previousPrimaryDigest: recordDigest }));
+                updated = savedSessionFields(content);
+            }
+            else
+                updated = apply(record);
+            await store.save(savedSessionFields(updated));
+            const state = owned.get(id);
+            if (state && change === 'rename') {
+                state.name = name;
+                state.renamed = true;
+                state.updatedAt = updated.updatedAt;
+            }
+            else if (state)
+                state.archived = updated.archived;
+        }
+        finally {
+            await release().catch(() => { });
+        }
+    };
+    /**
+     * The trajectory logs a session has, newest first: the runtime events this surface records for its
+     * runs; the engine's log under the session's id, where the desktop and this surface's runner record
+     * model calls; and, for a session the terminal created or continued, the terminal's own log, which
+     * the record names by `trajectoryId`.
+     */
+    const trajectoryLogs = async (id, live) => {
+        const record = owned.get(id) ?? (await listRecords()).find(item => item.id === id) ?? live.find(endpoint => endpoint.state.id === id)?.state;
+        if (!record)
+            return undefined;
+        const terminalId = typeof record.trajectoryId === 'string' && record.trajectoryId !== id && /^[A-Za-z0-9_-]{1,64}$/.test(record.trajectoryId) ? record.trajectoryId : undefined;
+        const candidates = [
+            { source: 'browser', folder: 'browser-trajectories', id },
+            { source: 'engine', folder: 'trajectories', id },
+            ...(terminalId === undefined ? [] : [{ source: 'terminal', folder: 'trajectories', id: terminalId }]),
+        ];
+        const found = await Promise.all(candidates.map(async (log) => {
+            const path = join(directory, log.folder, `${log.id}.jsonl`);
+            try {
+                const info = await stat(path);
+                return info.isFile() ? { ...log, path, modified: info.mtimeMs } : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }));
+        return found.filter(log => log !== undefined).sort((a, b) => b.modified - a.modified);
+    };
+    const hydrate = async (session) => {
+        if (owned.has(session.id))
+            return owned.get(session.id);
+        session = savedSessionFields(session);
+        let state = { ...session, status: 'idle', events: [] };
+        try {
+            const { previousPrimaryDigest, ...saved } = JSON.parse(await readFile(join(folder, `${session.id}.json`), 'utf8'));
+            if (validBrowserSession(saved) && saved.id === session.id) {
+                const digest = primaryDigest(session);
+                const independentlyUpdated = previousPrimaryDigest !== undefined && previousPrimaryDigest !== digest && primaryDigest(saved) !== digest;
+                // A matching predecessor proves the archive committed before the
+                // primary write. Any independently updated primary stays authoritative.
+                if (previousPrimaryDigest === digest)
+                    session = savedSessionFields(saved);
+                const interrupted = ['running', 'awaiting-input', 'cancelling'].includes(saved.status);
+                // A stale archive's running status must not outlive a newer primary:
+                // a CLI that completed and exited stays idle, not disconnected.
+                state = { ...saved, ...session, status: independentlyUpdated ? 'idle' : interrupted ? 'disconnected' : saved.status, pending: undefined, prompt: undefined, live: false };
+                if (interrupted && saved.prompt && !independentlyUpdated) {
+                    // The status is what a recovered attempt reads as. A turn that carries only a summary is a turn that
+                    // finished, and the rail would put a green mark on work this very record says was cut off.
+                    const turn = { task: saved.prompt, completion: { summary: 'Run interrupted when its owner disconnected. Inspect partial workspace changes before retrying.', tests: [], status: 'interrupted' } };
+                    // CLI acceptance already saves a synthetic pending turn. Only the
+                    // trailing pending attempt counts: earlier identical tasks are valid.
+                    const hasPending = (history) => {
+                        const last = history.at(-1);
+                        return last !== undefined && last.task === saved.prompt && !last.runId && last.completion.tests.length === 0 &&
+                            [turn.completion.summary, 'This attempt was interrupted or is still running. Verify the workspace before continuing.'].includes(last.completion.summary);
+                    };
+                    if (!hasPending(state.history))
+                        state.history = [...state.history, turn];
+                    if (state.contextHistory !== undefined && !hasPending(state.contextHistory))
+                        state.contextHistory = [...state.contextHistory, turn].slice(-6);
+                }
+            }
+        }
+        catch { /* historic CLI record */ }
+        return state;
+    };
+    const execute = async (state, text) => {
+        // A completed result is already visible while its storage flush finishes.
+        // Queue a continuation behind that flush without accepting late controls.
+        const previousJob = running.get(state.id);
+        if (previousJob && !state.live)
+            await previousJob.done;
+        if (closing)
+            throw new Error('Application is shutting down');
+        if (lostOwnership.has(state.id))
+            throw new Error('Session ownership was lost. Reopen this application before retrying.');
+        if (failedRollbacks.has(state.id))
+            throw new Error('Session storage rollback failed. Repair local session storage and inspect its history before reopening this application.');
+        if (running.has(state.id))
+            throw new Error('Session already running');
+        if (managing.has(state.id))
+            throw new Error('That session is being changed. Try again in a moment.');
+        const before = structuredClone(state);
+        // A name the user set by hand is pinned: titling from the first prompt is for unnamed sessions only.
+        // The pin and the chosen name live on the primary record, and this state may have been hydrated
+        // before they were written — a rail rename while this application held the session idle. The
+        // record is therefore re-read here, where titling would otherwise overwrite the chosen name and
+        // the required save below would drop the pin with it.
+        let pinned;
+        if (!state.history.length) {
+            try {
+                const raw = await readSnapshot(join(directory, 'sessions', `${state.id}.json`));
+                const primary = raw === undefined ? undefined : JSON.parse(raw);
+                if (primary !== undefined && primary.id === state.id && primary.renamed === true && typeof primary.name === 'string')
+                    pinned = primary.name;
+            }
+            catch { /* An unreadable record cannot claim the name was chosen; this state's own pin still governs. */ }
+        }
+        // Asked again after the read, in the same synchronous step that marks the session running below: a
+        // rename, filing or delete that began meanwhile owns the session until it finishes.
+        if (running.has(state.id))
+            throw new Error('Session already running');
+        if (managing.has(state.id))
+            throw new Error('That session is being changed. Try again in a moment.');
+        if (!state.history.length) {
+            if (pinned !== undefined) {
+                state.name = pinned;
+                state.renamed = true;
+            }
+            if (state.renamed !== true)
+                state.name = sessionName(text);
+        }
+        // Work this surface starts comes onto the working rail, the same rule the app server applies
+        // to a resume and to a due wake: live work never hides inside the archived subsection, whose
+        // rows carry no running or pending mark. Clearing here is what makes that intent deliberate
+        // rather than a by-product of whether this state was hydrated before or after the desktop
+        // filed the record away.
+        delete state.archived;
+        delete state.autoArchived;
+        const abort = new AbortController();
+        const job = { abort, detached: false, steering: [], done: Promise.resolve(), answer: undefined };
+        state.status = 'running';
+        state.todos = [];
+        state.prompt = text;
+        state.updatedAt = new Date().toISOString();
+        state.live = true;
+        owned.set(state.id, state);
+        running.set(state.id, job);
+        // A successful submission must already have a recoverable prompt on disk.
+        let acceptanceSucceeded = false;
+        const accepted = (async () => {
+            const archivePath = join(folder, `${state.id}.json`);
+            const primaryPath = join(directory, 'sessions', `${state.id}.json`);
+            let snapshots = [];
+            try {
+                await saves.get(state.id);
+                snapshots = await Promise.all([archivePath, primaryPath].map(async (path) => [path, await readSnapshot(path)]));
+                // The one save that files the session onto the working rail: `execute` cleared the flag
+                // above because the user started this work here.
+                await save(state, true, false);
+                assertOwnership(state.id);
+                acceptanceSucceeded = true;
+            }
+            catch (error) {
+                invalidateSaves(state.id);
+                for (const key of Object.keys(state))
+                    delete state[key];
+                Object.assign(state, before);
+                // Drain even already-submitted replacements before rollback. Guarded
+                // queued snapshots cannot publish after the restored predecessor.
+                await saves.get(state.id)?.catch(() => { });
+                // Another owner may already have published newer history. A rejected
+                // acceptance must never restore snapshots after losing its lease.
+                if (lostOwnership.has(state.id)) {
+                    running.delete(state.id);
+                    throw error;
+                }
+                try {
+                    for (const [path, content] of snapshots.reverse()) {
+                        if (await readSnapshot(path) === content)
+                            continue;
+                        assertOwnership(state.id);
+                        if (content === undefined)
+                            await removeSessionSnapshot(path, writes.guard(() => assertOwnership(state.id)));
+                        else
+                            await writeSessionSnapshot(path, content, writes.guard(() => assertOwnership(state.id)));
+                    }
+                }
+                catch (rollbackError) {
+                    if (lostOwnership.has(state.id))
+                        throw error;
+                    // Never leave the rejected prompt recoverable from a partial archive.
+                    // If even removal fails, report the durability uncertainty and refuse
+                    // further runs in this process instead of treating a retry as safe.
+                    failedRollbacks.add(state.id);
+                    let removed = true;
+                    await removeSessionSnapshot(archivePath, writes.guard(() => assertOwnership(state.id))).catch(() => { removed = false; });
+                    console.error('Browser prompt rollback failed:', sanitizer.sanitize(rollbackError instanceof Error ? rollbackError.message : String(rollbackError)));
+                    throw new Error(`Prompt rejected; session storage rollback failed${removed ? '' : ' and its partial archive could not be removed'}. Repair local storage and inspect session history before reopening this application.`);
+                }
+                finally {
+                    running.delete(state.id);
+                }
+                throw error;
+            }
+        })();
+        job.done = (async () => {
+            await accepted;
+            if (job.detached)
+                return;
+            const trajectory = await createSessionTrajectory({ sessionId: state.id, directory: join(directory, 'browser-trajectories') });
+            trajectory.addSecrets(await refreshSecrets());
+            if (job.detached)
+                return;
+            let currentRunId;
+            const event = async (event) => {
+                if (job.detached)
+                    return;
+                if (typeof event.data.runId === 'string')
+                    currentRunId = event.data.runId;
+                if (/reasoning|thinking\.delta/.test(event.type))
+                    return;
+                const sanitized = trajectory.sanitize(event);
+                state.events.push(sanitized);
+                boundBrowserActivity(state.events);
+                if (event.type === 'graph.todos.updated')
+                    state.todos = sanitized.data.todos;
+                await trajectory.recordEvent(event);
+                state.updatedAt = new Date().toISOString();
+                checkpoint(state);
+            };
+            let questionQueue = Promise.resolve();
+            const ask = (kind, question, signal, choices) => {
+                const answer = questionQueue.then(() => new Promise((resolve, reject) => {
+                    abort.signal.throwIfAborted();
+                    signal.throwIfAborted();
+                    const pending = { id: randomUUID(), kind, question, choices };
+                    state.pending = pending;
+                    state.status = 'awaiting-input';
+                    const cleanup = () => { signal.removeEventListener('abort', cancelled); if (state.pending?.id === pending.id)
+                        state.pending = undefined; job.answer = undefined; state.status = abort.signal.aborted ? 'cancelling' : 'running'; };
+                    const cancelled = () => { cleanup(); reject(signal.reason); };
+                    job.answer = answer => { cleanup(); resolve(answer); };
+                    signal.addEventListener('abort', cancelled, { once: true });
+                }));
+                questionQueue = answer.catch(() => { });
+                return answer;
+            };
+            try {
+                const runTask = options.runTask ?? ((runSession, runTask, runControl) => runBrowserTask(runSession, runTask, runControl, { directory }));
+                const result = await runTask(state, text, { signal: abort.signal, steering: () => job.steering.splice(0), event, ask });
+                if (job.detached)
+                    return;
+                state.status = result.status;
+                state.provider = result.provider;
+                state.model = result.model;
+                // A result that did not succeed must arrive carrying its status: the record's reader cannot tell a
+                // status-less completion from a finished one, and this surface is the only witness to what happened.
+                const terminalRecord = result.completion ?? { summary: result.status === 'cancelled' ? 'Cancelled. Inspect partial workspace changes before retrying.' : `Run ${result.status}: ${result.reason ?? ''}`, tests: [] };
+                state.history.push({ task: text, runId: result.id, completion: result.status === 'succeeded' ? terminalRecord : terminalCompletion(terminalRecord, result.status) });
+                for (const key of ['inputTokens', 'outputTokens', 'requests'])
+                    state.usage[key] += result.usage[key];
+                // Sparse: providers that report no cache counts keep the persisted shape unchanged.
+                const cacheRead = (state.usage.cacheRead ?? 0) + (result.usage.cacheRead ?? 0);
+                if (cacheRead > 0)
+                    state.usage.cacheRead = cacheRead;
+                const cacheWrite = (state.usage.cacheWrite ?? 0) + (result.usage.cacheWrite ?? 0);
+                if (cacheWrite > 0)
+                    state.usage.cacheWrite = cacheWrite;
+                // The run's final widget values are the session's newest, exactly as the CLI's and the
+                // app-server's finalizers treat them: assigning the result's (possibly absent) set both
+                // carries updates and clears values a previous graph left behind, so the record this
+                // browser saves never shows stale sections beside this run's plan.
+                state.widgets = result.widgets;
+            }
+            catch (error) {
+                if (job.detached)
+                    return;
+                state.status = abort.signal.aborted ? 'cancelled' : 'error';
+                state.history.push({ task: text, runId: currentRunId, completion: terminalCompletion({ summary: abort.signal.aborted ? 'Cancelled. Inspect partial workspace changes before retrying.' : String(trajectory.sanitize(error instanceof Error ? error.message : String(error))), tests: [] }, abort.signal.aborted ? 'cancelled' : 'infrastructure_error') });
+            }
+            finally {
+                if (!job.detached) {
+                    state.contextHistory = state.contextHistory === undefined ? state.history.slice(-6) : [...state.contextHistory, state.history[state.history.length - 1]].slice(-6);
+                    state.prompt = undefined;
+                    state.pending = undefined;
+                    state.live = false;
+                    state.updatedAt = new Date().toISOString();
+                    dirtyCompleted.add(state.id);
+                    // Finalization failures must not rewrite the completed run as an
+                    // initialization failure or append a second turn for the same prompt.
+                    const finalized = await Promise.allSettled([persistCompleted(state), trajectory.flush()]);
+                    for (const outcome of finalized)
+                        if (outcome.status === 'rejected') {
+                            const message = `Session finalization failed: ${String(trajectory.sanitize(outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)))}`;
+                            state.events.push({ type: 'browser.notice', time: new Date().toISOString(), data: { message } });
+                            boundBrowserActivity(state.events);
+                            dirtyCompleted.add(state.id);
+                            console.error(message);
+                        }
+                }
+            }
+        })().catch(async (error) => { if (!acceptanceSucceeded || job.detached)
+            return; state.status = 'error'; state.pending = undefined; state.prompt = undefined; state.live = false; state.history.push({ task: text, completion: terminalCompletion({ summary: 'Session initialization failed. Check provider configuration and local session storage, then retry.', tests: [] }, 'infrastructure_error') }); state.contextHistory = state.contextHistory === undefined ? state.history.slice(-6) : [...state.contextHistory, state.history[state.history.length - 1]].slice(-6); dirtyCompleted.add(state.id); await save(state).catch(() => { }); console.error('Browser session initialization failed:', error instanceof Error ? error.message : String(error)); }).finally(() => { if (running.get(state.id) === job)
+            running.delete(state.id); });
+        return accepted;
+    };
+    const server = createServer(async (req, res) => {
+        try {
+            const path = new URL(req.url || '/', origin).pathname;
+            if (!req.headers.host || req.headers.host !== new URL(origin).host || req.headers.origin && req.headers.origin !== origin) {
+                browserReply(res, 403, { error: 'Invalid origin' });
+                return;
+            }
+            const assets = { '/': ['index.html', 'text/html'], '/app.js': ['app.js', 'text/javascript'], '/style.css': ['style.css', 'text/css'], '/andorra-logo.png': ['andorra-logo.png', 'image/png'] };
+            if (req.method === 'GET' && assets[path]) {
+                const [file, type] = assets[path];
+                const content = await readFile(new URL(`./browser-ui/${file}`, import.meta.url));
+                res.writeHead(200, { 'Content-Type': type.startsWith('text/') || type === 'text/javascript' ? `${type}; charset=utf-8` : type, 'Cache-Control': 'no-store', 'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'", 'X-Content-Type-Options': 'nosniff' });
+                res.end(content);
+                return;
+            }
+            if (!browserAuthorized(req, token, origin)) {
+                browserReply(res, 401, { error: 'Reopen using /browser.' });
+                return;
+            }
+            await refreshSecrets();
+            const live = await discoverBrowserSessions(directory);
+            if (req.method === 'GET' && path === '/api/state') {
+                await refreshSettings();
+                const records = await listRecords();
+                const states = await Promise.all(records.map(hydrate));
+                const merged = new Map(states.map(state => [state.id, state]));
+                for (const state of owned.values())
+                    merged.set(state.id, state);
+                for (const endpoint of live)
+                    merged.set(endpoint.state.id, endpoint.state);
+                const cutoff = Date.now() - settings.maxAgeDays * 86400000;
+                const sessions = [...merged.values()].filter(state => state.live || !settings.maxAgeDays || Date.parse(state.updatedAt) >= cutoff).sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+                browserReply(res, 200, { sessions: sessions.map(publicState), settings });
+                return;
+            }
+            const trajectoryRoute = /^\/api\/sessions\/([a-f0-9-]{36})\/trajectory(\/download)?$/.exec(path);
+            if (req.method === 'GET' && trajectoryRoute) {
+                const [, id, download] = trajectoryRoute;
+                const logs = await trajectoryLogs(id, live);
+                if (!logs) {
+                    browserReply(res, 404, { error: 'Session not found' });
+                    return;
+                }
+                const query = new URL(req.url || '/', origin).searchParams;
+                const log = logs.find(item => item.source === query.get('source')) ?? logs[0];
+                if (download) {
+                    if (!log) {
+                        browserReply(res, 404, { error: 'This session has no trajectory yet' });
+                        return;
+                    }
+                    // Record by record through the sanitizer, as every other answer here goes: a key added to the
+                    // configuration after a record was written is still kept out of what leaves this server. The
+                    // record is parsed first, because the sanitizer replaces a whole JSON text above its size limit
+                    // with a plain-text marker — which would turn the large records the panel sends people here for
+                    // into lines that are not JSON. A line that is not JSON (a torn tail) is redacted as text.
+                    const downloadLine = (line) => {
+                        let record;
+                        try {
+                            record = JSON.parse(line);
+                        }
+                        catch {
+                            return String(sanitizer.sanitize(line));
+                        }
+                        return JSON.stringify(sanitizer.sanitize(record));
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/x-ndjson; charset=utf-8', 'Content-Disposition': `attachment; filename="${id}-${log.source}.jsonl"`, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+                    const input = createReadStream(log.path);
+                    const lines = createInterface({ input, crlfDelay: Infinity });
+                    // A client that goes away while the response is backed up never drains it, so the wait also ends
+                    // when the response closes, and the file is released either way.
+                    const closed = new Promise(done => res.once('close', done));
+                    // The headers are out, so a read that fails part way can only cut the download short.
+                    try {
+                        for await (const line of lines) {
+                            if (res.destroyed)
+                                break;
+                            if (!res.write(`${downloadLine(line)}\n`))
+                                await Promise.race([new Promise(done => res.once('drain', done)), closed]);
+                        }
+                        if (!res.destroyed)
+                            res.end();
+                    }
+                    catch {
+                        res.destroy();
+                    }
+                    finally {
+                        lines.close();
+                        input.destroy();
+                    }
+                    return;
+                }
+                const page = log === undefined ? undefined : await readSessionTrajectory(directory, log.id, Number(query.get('offset') ?? 0), undefined, log.folder);
+                browserReply(res, 200, { sources: logs.map(item => item.source), source: log?.source, page: page && { ...page, path: undefined, records: sanitizer.sanitize(page.records) } });
+                return;
+            }
+            if (req.method !== 'POST') {
+                browserReply(res, 404, { error: 'Not found' });
+                return;
+            }
+            if (closing) {
+                browserReply(res, 503, { error: 'Application is shutting down' });
+                return;
+            }
+            const body = await browserBody(req);
+            if (path === '/api/settings') {
+                if (!Number.isInteger(body.maxAgeDays) || Number(body.maxAgeDays) < 0 || Number(body.maxAgeDays) > 36500)
+                    throw new Error('Days must be an integer from 0 to 36500 (0 shows all history)');
+                if (body.theme !== undefined && !['system', 'light', 'dark'].includes(String(body.theme)))
+                    throw new Error('Theme must be system, light or dark');
+                const candidate = { maxAgeDays: Number(body.maxAgeDays), theme: body.theme === undefined ? settings.theme : String(body.theme) };
+                // Settings are global to the shared configuration directory: serialize
+                // the replacement in process and across applications so a stalled write
+                // cannot resume after a newer one was already acknowledged.
+                await writes.run(async () => {
+                    const release = await lockfile.lock(join(directory, 'browser-settings.lock'), { realpath: false, stale: 10000, update: 2000, onCompromised: () => { } });
+                    try {
+                        await writeSessionSnapshot(join(directory, 'browser-settings.json'), JSON.stringify(candidate));
+                    }
+                    finally {
+                        await release().catch(() => { });
+                    }
+                });
+                settings = candidate;
+                browserReply(res, 200, settings);
+                return;
+            }
+            if (path === '/api/sessions') {
+                let projectPath = body.workspace;
+                if (body.projectSessionId !== undefined) {
+                    if (typeof body.projectSessionId !== 'string')
+                        throw new Error('Invalid project session');
+                    // Display paths may be redacted. Resolve the selected project from
+                    // canonical owned/persisted metadata, then an unsaved live CLI session.
+                    const source = owned.get(body.projectSessionId)
+                        ?? (await listRecords()).find(record => record.id === body.projectSessionId)
+                        ?? live.find(endpoint => endpoint.state.id === body.projectSessionId)?.state;
+                    if (!source)
+                        throw new Error('Project session no longer exists. Refresh and retry.');
+                    projectPath = source.workspace;
+                }
+                if (typeof projectPath !== 'string' || !projectPath.trim())
+                    throw new Error('Choose a project folder');
+                const workspace = await realpath(resolve(projectPath));
+                if (!(await stat(workspace)).isDirectory())
+                    throw new Error('Project must be an existing folder');
+                const state = { version: 1, id: randomUUID(), name: 'New coding session', workspace, projectId: projectIdentity(workspace), updatedAt: new Date().toISOString(), history: [], contextHistory: [], usage: { requests: 0, inputTokens: 0, outputTokens: 0 }, status: 'idle', events: [] };
+                await ensureOwner(state, true);
+                try {
+                    await save(state, true);
+                    // This handler is the browser surface's one conversation-creation point: the run path
+                    // only ever reopens a session this stored, so without this the browser's sessions are
+                    // missing from the conversation counts entirely.
+                    // Awaited: the creation handler is not latency-critical, and a queued start that lands
+                    // after the response would race a caller closing the engine on the same home.
+                    await currentGraphSubject().catch(() => undefined).then(subject => reportSessionStarted({ home: directory, surface: configuredSurface('desktop'), workspace, ...(subject === undefined ? {} : { subject }) })).catch(() => { });
+                }
+                catch (error) {
+                    const bridge = bridges.get(state.id);
+                    bridges.delete(state.id);
+                    owned.delete(state.id);
+                    const ownerPath = join(directory, 'browser-owners', state.id);
+                    const release = leases.get(ownerPath);
+                    leases.delete(ownerPath);
+                    // This fresh ID was never acknowledged; discard its partial archive.
+                    // Submit deletion independently of bridge cleanup and retain the lease
+                    // until both settle, even if close fails or shutdown starts meanwhile.
+                    const removal = lostOwnership.has(state.id) ? Promise.resolve() : Promise.allSettled([
+                        removeSessionSnapshot(join(folder, `${state.id}.json`), writes.guard(() => assertOwnership(state.id))),
+                        // The required save can commit the primary and still reject after;
+                        // this fresh id was never acknowledged, so discard that record too.
+                        removeSessionSnapshot(join(directory, 'sessions', `${state.id}.json`), writes.guard(() => assertOwnership(state.id))),
+                    ]).then(results => { const failure = results.find(result => result.status === 'rejected'); if (failure)
+                        throw failure.reason; });
+                    try {
+                        const cleanup = await Promise.allSettled([bridge?.close(), removal]);
+                        const failure = cleanup.find(result => result.status === 'rejected');
+                        if (failure?.status === 'rejected')
+                            throw failure.reason;
+                    }
+                    finally {
+                        await release?.();
+                    }
+                    throw error;
+                }
+                browserReply(res, 201, publicState(state));
+                return;
+            }
+            const manage = /^\/api\/sessions\/([a-f0-9-]{36})\/(rename|archive|delete)$/.exec(path);
+            if (manage) {
+                await manageSession(manage[1], manage[2], body, live);
+                browserReply(res, 200, { ok: true });
+                return;
+            }
+            const match = /^\/api\/sessions\/([a-f0-9-]{36})\/(prompt|steer|cancel|answer)$/.exec(path);
+            if (!match) {
+                browserReply(res, 404, { error: 'Not found' });
+                return;
+            }
+            const [, id, action] = match;
+            const endpoint = live.find(item => item.state.id === id);
+            if (endpoint) {
+                // Acceptance has no deadline: the owner may already be persisting it.
+                // Shutdown only disconnects transport; it cannot reject or undo a run.
+                if (closing) {
+                    res.destroy();
+                    return;
+                }
+                const forwarding = new AbortController();
+                forwardedRequests.add(forwarding);
+                try {
+                    const signal = action === 'prompt' ? forwarding.signal : AbortSignal.any([forwarding.signal, AbortSignal.timeout(5000)]);
+                    const upstream = await fetch(`${endpoint.origin}/${action}`, { method: 'POST', headers: { authorization: `Bearer ${endpoint.token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ ...body, sessionId: id }), signal });
+                    browserReply(res, upstream.status, await upstream.json());
+                }
+                catch (error) {
+                    // A dropped transport after submission leaves the outcome unknown:
+                    // the owner may have durably accepted the prompt and be running it.
+                    // Destroy instead of returning a definite retryable rejection.
+                    if (forwarding.signal.aborted || action === 'prompt') {
+                        res.destroy();
+                        return;
+                    }
+                    throw error;
+                }
+                finally {
+                    forwardedRequests.delete(forwarding);
+                }
+                return;
+            }
+            const record = (await listRecords()).find(item => item.id === id);
+            if (!record) {
+                browserReply(res, 404, { error: 'Session not found' });
+                return;
+            }
+            const state = await hydrate(record);
+            const job = running.get(id);
+            if (action === 'prompt' || action === 'steer') {
+                if (typeof body.text !== 'string' || !body.text.trim() || body.text.length > 100000)
+                    throw new Error('Enter a prompt up to 100000 characters');
+                if (action === 'prompt') {
+                    await ensureOwner(state);
+                    await execute(state, body.text);
+                }
+                else {
+                    if (!job || !state.live)
+                        throw new Error('Session is idle or disconnected');
+                    if (job.abort.signal.aborted)
+                        throw new Error('Session is cancelling');
+                    job.steering.push(body.text);
+                }
+            }
+            else if (action === 'cancel') {
+                cancel(state);
+            }
+            else {
+                if (!job?.answer || !state.pending || body.id !== state.pending.id || typeof body.answer !== 'string')
+                    throw new Error('Question is no longer pending');
+                if (state.pending.choices && !state.pending.choices.some(choice => choice.id === body.answer))
+                    throw new Error('Choose a listed answer');
+                job.answer(body.answer);
+            }
+            browserReply(res, 200, { ok: true });
+        }
+        catch (error) {
+            browserReply(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+    origin = `http://127.0.0.1:${server.address().port}`;
+    return { origin, token, url: `${origin}/#token=${token}`, async close() {
+            closing = true;
+            for (const forwarding of forwardedRequests)
+                forwarding.abort();
+            // A provisional bridge stuck in descriptor publication must lose its
+            // listener now; its acquisition promise is left to the stalled storage.
+            for (const cancellation of acquisitionSignals)
+                cancellation.abort();
+            // An acquisition already waiting on discovery, a lock or bridge setup must
+            // get a bounded grace period. Late arrivals observe closing and dispose of
+            // their own bridge and lease; unpublished leases stay with that cleanup.
+            let acquisitionTimer;
+            try {
+                await Promise.race([
+                    Promise.allSettled([...ownershipAcquisitions]),
+                    new Promise(resolve => { acquisitionTimer = setTimeout(resolve, 2000); }),
+                ]);
+            }
+            finally {
+                clearTimeout(acquisitionTimer);
+            }
+            for (const job of running.values())
+                job.abort.abort();
+            // Providers/tools may ignore abort. Give cooperative runs time to persist
+            // their result, then fence late callbacks before releasing their ownership.
+            let drainTimer;
+            try {
+                await Promise.race([
+                    Promise.allSettled([...running.values()].map(job => job.done)),
+                    new Promise(resolve => { drainTimer = setTimeout(resolve, 2000); }),
+                ]);
+            }
+            finally {
+                clearTimeout(drainTimer);
+            }
+            const interruptedSaves = [];
+            for (const [id, job] of running) {
+                job.detached = true;
+                // Keep the accepted prompt recoverable as an interrupted run. Save the
+                // latest observed events before fencing all later writes from this owner.
+                const state = owned.get(id);
+                if (state)
+                    interruptedSaves.push(save(state));
+                clearTimeout(checkpoints.get(id));
+                checkpoints.delete(id);
+            }
+            // Completed jobs leave running even when both final writes fail. Retry
+            // their retained state while ownership and the bounded flush still apply.
+            for (const id of dirtyCompleted) {
+                const state = owned.get(id);
+                if (state && !running.has(id) && !failedRollbacks.has(id))
+                    interruptedSaves.push(save(state));
+            }
+            // A checkpoint can itself be stuck in storage. Bound the entire flush,
+            // then fence queued saves and atomic replacements before releasing leases.
+            try {
+                await Promise.race([
+                    Promise.allSettled([...saves.values(), ...interruptedSaves]),
+                    new Promise(resolve => { drainTimer = setTimeout(resolve, 2000); }),
+                ]);
+            }
+            finally {
+                clearTimeout(drainTimer);
+            }
+            writes.close();
+            for (const id of owned.keys()) {
+                lostOwnership.add(id);
+                clearTimeout(checkpoints.get(id));
+                checkpoints.delete(id);
+            }
+            // Submitted OS replacements cannot be cancelled: retain discovery and
+            // lease heartbeats until they settle, but close every HTTP listener now.
+            const replacementDrain = writes.replacements.size ? writes.settled() : undefined;
+            const bridgeResults = await Promise.allSettled([...bridges.values()].map(bridge => bridge.close(replacementDrain)));
+            const releaseLeases = () => Promise.all([...leases.values()].map(release => release().catch(() => { })));
+            if (replacementDrain)
+                void replacementDrain.then(releaseLeases).catch(() => { });
+            else
+                await releaseLeases();
+            try {
+                await sanitizer.flush();
+            }
+            finally {
+                server.closeAllConnections();
+                await new Promise(resolve => server.close(() => resolve()));
+            }
+            const failure = bridgeResults.find(result => result.status === 'rejected');
+            if (failure?.status === 'rejected')
+                throw failure.reason;
+        } };
+}
+export function openBrowserUrl(url) {
+    const command = process.platform === 'win32' ? 'rundll32.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    execFile(command, process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url], { windowsHide: true, timeout: 10000 }, error => { if (error)
+        process.stderr.write(`Open ${url} in your browser.\n`); });
+}