@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/app-server.d.ts

@@ -0,0 +1,1039 @@
+import { type ProviderConfig } from './providers.js';
+import { removeCodexAccount } from './codex-auth.js';
+import { CodexAccountAuth } from './codex-browser-auth.js';
+import { AnthropicConsoleAuth } from './anthropic-console-auth.js';
+import { checkGraphModelHealth } from './graph-health.js';
+import { loadAccessibleGraph } from './membership.js';
+import { type SavedSession } from './sessions.js';
+import { type GhRunner } from './pull-requests.js';
+import { type Completion, type RunResult } from './runtime.js';
+import { type AppServerErrorCode } from './app-server/protocol.js';
+/**
+ * `andorra app-server --stdio`: the engine a non-TUI client drives.
+ *
+ * The transport, the wire types, and the client-side mirror live in `./app-server/protocol.ts` and
+ * `./app-server/workspace.ts`. This module owns the state a client cannot: the active run, the
+ * approval and question exchanges inside it, open terminals, the graph editor server, and the
+ * lazily created code-intelligence manager.
+ *
+ * One run at a time
+ * -----------------
+ * A process owns at most one run. The TUI is one run by construction and a second concurrent run
+ * would need the durable multi-run runtime the roadmap defers, so `run.start` reports `busy`
+ * instead of quietly interleaving two runs' approvals and journals.
+ *
+ * Nothing here prints to stdout except protocol lines: a stray write would corrupt the stream.
+ * Diagnostics go to stderr.
+ */
+declare class AppServerError extends Error {
+    readonly code: AppServerErrorCode;
+    constructor(code: AppServerErrorCode, message: string);
+}
+/**
+ * Merge a client's provider list with the stored secrets.
+ *
+ * The client reads providers through `configView`, which deliberately omits every `apiKey`, so a
+ * round trip that replaced the array wholesale would delete the credentials of every provider the
+ * user did not retype: making another provider active or removing one would break the rest. An entry
+ * that names no key therefore keeps the stored one, and an explicit `null` is how a client asks for
+ * one to be removed. The configured model list is carried over the same way, because a client written
+ * before that field existed reads an entry without it and cannot send back what it never saw.
+ *
+ * `streamIdleTimeoutMs` follows the same retain-on-omit rule, because a desktop build from before the
+ * field exists cannot name it: reconstructing the provider from its entry alone would silently delete
+ * the stored bound and restore the indefinite stall the field exists to prevent. A client that wants
+ * the bound gone names it as `null` rather than leaving it out. The per-model context windows follow
+ * that rule too: an older client's save must not erase the limits a newer one stored, and `null`
+ * removes the map.
+ *
+ * Retention stops where the type cannot hold the value. Codex accepts neither a key nor a stream bound,
+ * and the clients that leave both out rather than naming the removal — one built before the bound
+ * existed cannot name it at all — are exactly the ones converting a provider to Codex. Carrying either
+ * value into the new entry made `validateConfig` refuse the whole save over fields the type does not
+ * have, so a Codex entry starts without them. A model list is not one of those: the configuration
+ * allows it on Codex, so it is retained for that type like any other.
+ *
+ * A Codex entry's account slot and its recorded email follow the retain-on-omit rule with the same
+ * urgency: a client that omits the slot has simply never seen it — the provider view does not report
+ * it — and dropping it on save would silently point a second account at the default home's sign-in.
+ */
+export declare function mergeProviderSecrets(stored: ProviderConfig[], incoming: unknown[]): ProviderConfig[];
+/**
+ * Whether a failed wake delivery is final for that wake.
+ *
+ * A delivery gets two kinds of answer. One describes the request: an unknown provider or graph, a task the
+ * protocol will not accept, a session record that is no longer there at all, a remote workspace nothing may be
+ * run in, a method the engine does not have. The same prompt would be refused the same way a minute from now, so
+ * the wake is spent and the row must stop saying the session is waiting on it.
+ *
+ * A project folder that is not there *this moment* is not that answer. Folders come back: a checkout that has not
+ * landed, a share that is unreachable, a directory moved and moved again. A delivery that spent the wake on the
+ * first `ENOENT` would throw away a continuation the agent asked for, over a condition that clears. The start
+ * refuses a missing folder as a plain filesystem failure rather than a named protocol refusal, and that is the
+ * classification: `test/app-server.test.ts` ("a wake survives a delivery the engine could not start") takes an
+ * owed workspace out of the world and pins the rest - the wake stays owed, the row keeps its clock, no empty
+ * `timers.updated` says the wait is over, and the prompt arrives once the folder does.
+ *
+ * The other kind describes the moment, and every one of them clears: `engine-busy` and `busy` while another
+ * task or a `workspace.checkout` holds the engine, `cancelled` from a shutdown in progress (the wake is on
+ * disk, so the next engine process picks it up again), `storage` and `network` from inside the preparation,
+ * and — the one that costs a prompt most easily — a raw filesystem error, because the start re-throws the save
+ * when the session snapshot cannot be written. A deadline says the earliest a prompt may be given, not that it
+ * may be given once, so anything that is not a refusal of the request is waited out. Unclassified failures
+ * belong here: an error the engine never got to name is a failure of the moment, and losing the prompt the
+ * agent asked to be woken for is the more expensive guess.
+ */
+/** Exported because the table is the part a delivery must not get wrong; the protocol test pins it. */
+export declare function isFinalWakeRefusal(error: unknown): boolean;
+/**
+ * The account a finished run leaves on the session turn.
+ *
+ * A graph that finished one node before it was cancelled, exhausted, or failed in the next
+ * returns that node's completion alongside the non-success status. The status is the attempt's
+ * last word — the client branches on it to keep a stopped attempt's activity visible — so the
+ * retained completion carries it too; without the stamp a stopped attempt folds like a done turn.
+ *
+ * `closedWithRun` says the abort came from the app going away rather than from a Stop. Closing is
+ * not the person giving up on the attempt: it is recorded as `interrupted`, the same status startup
+ * recovery gives a run whose engine was killed, so it reads as stopped work to resume (the row's
+ * mark and the Resume control both key on it) instead of a stop that was asked for.
+ */
+export declare function finalCompletion(result: RunResult | undefined, aborted: boolean, failure: unknown, closedWithRun?: boolean): Completion;
+/**
+ * The session as it was before this run's in-flight marker: the marker turn out of both histories.
+ *
+ * The marker is written into history and contextHistory together - one is the transcript a client reads, the
+ * other the model context a later run seeds from - so an abandoned start has to remove it from both. Stripping
+ * only the transcript leaves the two disagreeing: the rail shows the session as it was, while the next attempt
+ * seeds from a turn reporting work this run never did, and is free to repeat it.
+ */
+export declare function withoutRunMarker(record: SavedSession, runId: string): SavedSession;
+export interface AppServerOptions {
+    directory?: string;
+    output?: NodeJS.WritableStream;
+    error?: NodeJS.WritableStream;
+    /** Overridable so a test can answer the model preflight without reaching a provider. */
+    checkGraphHealth?: typeof checkGraphModelHealth;
+    /** Overridable so a test can run a graph whose access rules it cannot meet. */
+    loadGraph?: typeof loadAccessibleGraph;
+    /** Provider authentication is owned here, independently of the Andorra account sign-in. */
+    codexAuth?: Pick<CodexAccountAuth, 'start' | 'status' | 'cancel' | 'logout' | 'close'>;
+    /** Overridable so a test can watch a retired slot without reaching the Codex CLI. */
+    removeCodexAccount?: typeof removeCodexAccount;
+    /** Claude Console sign-in for Anthropic providers; overridable so a test never spawns `ant`. */
+    anthropicAuth?: Pick<AnthropicConsoleAuth, 'start' | 'status' | 'cancel' | 'logout' | 'discard' | 'close'>;
+    /** Overridable so a test can answer `gh` without reaching GitHub. */
+    gh?: GhRunner;
+    /** How often the pull request watcher polls; a test shortens it. */
+    pullRequestPollMs?: number;
+}
+export declare class AppServer {
+    private automationCheck?;
+    /** The daily auto-archive pass; a change to the setting runs one immediately as well. */
+    private autoArchiveCheck?;
+    /** The tail of the auto-archive passes, so a settings change never runs one over another. */
+    private autoArchivePass;
+    private readonly automationTasks;
+    private readonly manualAutomationTasks;
+    private readonly automationController;
+    private readonly directory;
+    private readonly output;
+    private readonly error;
+    private readonly checkGraphHealth;
+    private readonly loadGraph;
+    private readonly codexAuth;
+    private readonly anthropicAuth;
+    /** Retires a removed provider's slot home; a seam so a test never has to spawn the Codex CLI. */
+    private readonly retireCodexAccount;
+    /** The `gh` the pull request settings and watcher run through. */
+    private readonly gh;
+    /** Polls the PRs whose sessions asked for Auto-fix or Auto-archive; one engine per home actually polls. */
+    private readonly pullRequestWatcher;
+    /** The wakes this engine armed for Auto-fix, checked against the PR record again before delivery. */
+    private readonly autoFixWakes;
+    /**
+     * The account's graph sync, so a graph saved on another machine is listed here too. A first pass that
+     * outlasts the listing's bounded wait publishes `graphs.changed`: that listing already answered from
+     * the copy on disk, and the surface behind it has to read again to see what the pass restored.
+     */
+    private readonly graphSync;
+    private readonly terminals;
+    /** Holds a flooding shell's output back while the protocol stream is behind. */
+    private readonly flow;
+    /** Panel browsers: interactive session-owned pages, separate from the agent's qa.browser_session tool. */
+    private readonly browserViews;
+    /** Pending approval and question exchanges, keyed by the id the client answers with. */
+    private readonly pending;
+    /** Pending panel-browser relay exchanges, keyed by the id the desktop answers with. */
+    private readonly panelRelays;
+    /** Panel operations executing on this engine, keyed by the relay that asked for them. */
+    private readonly panelOperations;
+    /**
+     * The runs those operations answer with, keyed the same way.
+     *
+     * Every window attached to a paired machine receives the same request frame, so the same relay id
+     * can arrive twice. A repeated id joins the run already going rather than pressing the key or
+     * opening the tab a second time.
+     */
+    private readonly panelOperationRuns;
+    /** Requests in flight: shutdown waits for them rather than exiting under their I/O. */
+    private readonly requests;
+    private run?;
+    private readonly originalModelGraphs;
+    /**
+     * The attempt whose work is over and whose finalizer is still putting it away.
+     *
+     * The live-run slot is released before the terminal events go out — a client that chains runs sends
+     * its next `run.start` the moment it sees `run.completed`, and that start must not meet `engine-busy`
+     * while the engine is only tidying up — so during the tail `run` no longer names the attempt, but
+     * its open claim still stands and the merged save has just landed. A rename that arrives in that
+     * window belongs to this process all the same: naming the finishing attempt is how `renameSession`
+     * keeps excusing its claim instead of refusing the user's own run as "another window".
+     */
+    private finishingRunId;
+    /** The session the finishing attempt belongs to, so the excuse above is not handed to a stranger. */
+    private finishingSessionId;
+    /**
+     * Why the active run's controller was aborted — finalization reads it to tell a Stop the person
+     * pressed from the app being closed while the attempt was still running. Cleared when a run starts.
+     */
+    private runAbort?;
+    /** Set synchronously while a start is being prepared, so two starts in one tick cannot both pass the guard. */
+    private starting;
+    /**
+     * Self-wake registry for this engine, shared by the runs it serves.
+     *
+     * Engine-wide rather than per run on purpose: a wake armed by a task is expected to arrive after that
+     * task is over, which is the entire point of arming one. Every wake carries the session that armed it, so
+     * the prompt — and the wait a row draws for it — goes back to that session, not to whichever one happens
+     * to be running: an engine serves many sessions over its life, and two of them can be waiting at once.
+     * The CLI gets the same tool through a registry of its own; here the engine is also the deliverer,
+     * because a window has no loop to carry a wake in.
+     */
+    private readonly timers;
+    /** Engine timer for the next deadline, so a wake due while a run is in flight is retried. */
+    private timerCheck?;
+    /** One delivery pass at a time, so a due callback cannot start a second one. */
+    private timerDeliveryTask?;
+    /**
+     * A branch switch in flight, held until it completes.
+     *
+     * Switching the tree and starting a run are separate requests, and the checkout awaits Git twice:
+     * a start arriving in that window used to pass the busy guard, launch the agent, and then have the
+     * tree switched underneath it — so the branch the changes land in is not the one the task started
+     * on. The reservation is taken synchronously and refused, not queued: a run that waits would begin
+     * against a repository whose branch the user has stopped describing.
+     */
+    private checkout?;
+    /** Memoized creation of the run-record directory, which this mode must do for itself. */
+    private runRecordsReady?;
+    /**
+     * The session a `run.resume` is preparing: the record is read and will be saved by the resumed
+     * run, so a rename or delete accepted in that window is silently reverted. `this.run` does not
+     * cover it yet — the run is installed only when preparation ends.
+     */
+    private startingSession?;
+    /**
+     * Runs whose journal sink failed mid-attempt. The journal keeps being written after the failure,
+     * so it looks complete; this is what marks the attempt as one no resume may replay (the record
+     * and a marker file carry it past a crash).
+     */
+    private readonly journalFailures;
+    /**
+     * Runs whose checkpoint sink failed mid-attempt. A checkpoint is the conversation a resume
+     * re-enters the node with, so a run whose checkpoint could not be written is one no resume may
+     * replay: the resume would re-enter the node from its opening task and repeat the tool calls it
+     * had already made. The record and a marker file carry the failure past a crash.
+     */
+    private readonly checkpointFailures;
+    /**
+     * The session trajectory of the run in flight: one sanitized debug log per session
+     * (`trajectories/<sessionId>.jsonl` in this home), appended by every run and resume of that
+     * session. Unlike the per-run journal it spans attempts, and it records the model calls
+     * themselves — requests, responses, errors — where the journal stays the engine's own resume
+     * record. Cleared when the run's final marker has been written and flushed.
+     */
+    private trajectory?;
+    /** Tail of the configuration write queue; see `serializeConfig`. */
+    private configWrites;
+    /** Tail of each Codex slot home's lifecycle; a retirement and a sign-in on one slot never interleave. */
+    private readonly slotWrites;
+    /** The run in flight, retained so shutdown can wait for its bookkeeping instead of racing it. */
+    private runTask?;
+    /**
+     * Resolvers waiting for a run's first provider answer — or for its end, whichever comes first.
+     *
+     * Automatic titling holds until then: the run's first request must reach a serializing endpoint
+     * ahead of the naming request, and after that answer the run executes its turn's tools while the
+     * provider is free. Waiting for the whole run instead would leave a session's name as the local
+     * word-slice for the entire task, and a stopped task would never be named at all.
+     */
+    private readonly titleReleases;
+    /** Automatic title requests on the wire, by session: new work must never queue behind one. */
+    private readonly sessionTitles;
+    /** Bumped whenever new work starts; a title begun under an older generation never runs. */
+    private workGeneration;
+    /** Sign-in and discovery controllers, aborted at shutdown so neither outlives the client. */
+    private readonly operations;
+    /** A start still being prepared, awaited and refused at shutdown. */
+    private prepareTask?;
+    /** The poll for runs whose holder was still shutting down when this engine started; see `watchForeignEngineShutdown`. */
+    private foreignEngineWatch?;
+    private editor?;
+    /** The editor start in flight, so two opens cannot race into two servers. */
+    private editorTask?;
+    private codeIntel?;
+    /**
+     * The remote-serve outcome this engine holds: either the listener whose lock and descriptor are
+     * ours to release at close, or the record that this installation has nothing to serve.
+     */
+    private remoteServe?;
+    /**
+     * Outbound engine links, one per paired workspace this engine relays for its client.
+     *
+     * A link is the long-lived event stream to the paired machine plus the connection id its requests
+     * identify as; the frames it receives are re-emitted on this engine's own stream as
+     * `remote.engine.event`, which is how a paired machine's engines reach the desktop without the
+     * desktop ever speaking TLS itself.
+     */
+    private readonly engineLinks;
+    /** The last grant each workspace's live probe reported, for offline views (see remoteWorkspaceState). */
+    private readonly lastKnownGrants;
+    /** Tail of the queue serializing serve/lock transitions; see `serializeRemote`. */
+    private remoteOps;
+    private closed;
+    /**
+     * Whether events still reach the protocol stream. Unlike `closed`, this stays open across the
+     * shutdown wait: the run finalizer settles during that window, and a client that stayed connected
+     * to ask for the stop — an engine stop with the app still running — is exactly the one that has
+     * to hear the terminal story. What the finalizer emits is normalized to agree with the record it
+     * just wrote, so the event and the next `runs.list` tell the same one.
+     */
+    private emitsStopped;
+    /** The last run's finish enqueue; close() waits for it before draining the outbox. */
+    private telemetrySettle;
+    onStop?: () => void;
+    constructor(options: AppServerOptions & {
+        output: NodeJS.WritableStream;
+        error: NodeJS.WritableStream;
+    });
+    private emit;
+    private log;
+    /** The handshake every client waits for before it sends anything. */
+    ready(): Promise<void>;
+    /** Queue one auto-archive pass behind any pass still running. A failure is logged, never thrown. */
+    private reapSessions;
+    /**
+     * Archive the sessions idle past the configured number of days, and return to the rail the ones a
+     * previous pass archived that no longer qualify (the setting was raised or turned off). Sessions the
+     * user archived by hand carry no reaper mark, so they are never returned.
+     *
+     * A session with a run in flight or a wake armed is skipped, for the reason `setSessionArchived`
+     * refuses it: the run saves the record it captured and would revert the flag, and a filed row hides
+     * the approval or the wake it is waiting on. A wake armed by another engine is invisible to this
+     * process's registry, so the claim arming wrote — swept here once its owner is gone — is what holds
+     * the session too. Every change is re-planned against the record and the setting read under the
+     * session's mutation lock: another window's pass, a run that just started, a threshold another
+     * engine saved (or the reaper another turned off) after this pass opened, or a manual filing that
+     * landed since the list was read is never overwritten.
+     */
+    private autoArchiveSessions;
+    /**
+     * The handshake payload, built once for the `ready` event and `host.info` so the two cannot drift:
+     * a client that read one and then the other would otherwise see different capabilities, and the
+     * capability is what decides whether it offers a control at all.
+     */
+    private hostInfo;
+    private version;
+    /**
+     * Parse and answer one input line. Never throws: every failure becomes a response.
+     *
+     * The request is tracked while it runs, because lines are read concurrently and `close()` has to be able
+     * to wait for the work a shutdown would otherwise cut through — a read still in progress when the process
+     * exits, or a state-changing request finished after the client was told the engine had stopped.
+     */
+    handle(line: string): Promise<void>;
+    private dispatchLine;
+    private write;
+    private dispatch;
+    private store;
+    /**
+     * Canonicalize a workspace the way session records are stored.
+     *
+     * `sessions.create` and `run.start` record the real path, but `SessionStore.list` compares
+     * lexically, so a project added through a symlink, a junction, or a differently cased Windows path
+     * would list nothing even though its sessions exist. A folder that no longer exists is passed
+     * through unchanged: it simply has no sessions.
+     */
+    private listableWorkspace;
+    /**
+     * The sessions a client's rail lists: one workspace, or several in one pass.
+     *
+     * Reading the store means reading and parsing every session record it holds, so a client that asked
+     * once per project paid that whole scan per project — with P projects and S saved sessions, P × S
+     * reads and parses to fill one tree. The batched form canonicalizes each requested path exactly as
+     * the single form does, reads the store once, and answers with the same summaries grouped by the
+     * path the client asked for, so it can file each group under its own row.
+     */
+    private listSessions;
+    /**
+     * Run a configuration change as a read-modify-write with nothing interleaved.
+     *
+     * Requests are answered concurrently by design, so two saves that each loaded the file and then
+     * wrote their own merge would silently discard one another: toggling two settings in quick
+     * succession would keep only the second. Every write to the configuration file goes through here.
+     */
+    private serializeConfig;
+    /**
+     * Run one Codex slot home's lifecycle step after every earlier one has settled.
+     *
+     * A slot home is created by a sign-in and deleted by a retirement, and the two requests can arrive
+     * at once. Ordering them per slot is what keeps a retirement from deleting a home that a sign-in
+     * began after the provider was re-created, without serializing unrelated accounts against each other.
+     */
+    private slotLock;
+    private setConfig;
+    /** Manage the extension folders shared by the CLI and desktop. */
+    private extensionKind;
+    private skillResources;
+    private skillRead;
+    private skillWrite;
+    private installExtension;
+    private removeExtension;
+    private setExtensionEnabled;
+    /** Preserve MCP credentials when toggling or deleting an existing entry. */
+    private mutateMcp;
+    /**
+     * Apply one provider change inside the serialized configuration transaction.
+     *
+     * A client cannot do this atomically for itself: it would read the configuration, change the list, and
+     * write it back, and the engine treats a `providers` array as a replacement — so a change the CLI or
+     * another window made between the two requests would be deleted by the write. The read-modify-write
+     * happens here, under the same queue that orders every configuration write, which makes one provider
+     * edit indivisible.
+     *
+     * Exactly one operation per call: `upsert` (one provider entry, by id), `remove` (an id), or
+     * `clearKey` (drop one provider's saved secret). `active` may accompany an upsert.
+     */
+    private updateProviders;
+    /**
+     * Delete the Claude Console logins of providers a committed configuration no longer signs in.
+     *
+     * The configuration is read again first: an overlapping request can re-create the provider with
+     * sign-in before this runs, and that provider's fresh login is not this removal's to delete.
+     */
+    private retireAnthropicAccounts;
+    /**
+     * Delete the slot homes a committed configuration no longer names.
+     *
+     * Each retirement takes the slot's lock, which a sign-in also takes, and re-reads the configuration
+     * before deleting: an overlapping request can re-create the provider and sign the slot in before
+     * this removal finishes, and that fresh session is not the retired one's to delete.
+     */
+    private retireSlots;
+    private discoverModels;
+    /** Local-client only. The remote engine relay deliberately does not admit these methods. */
+    private providerAuth;
+    /**
+     * Claude Console sign-in for one configured Anthropic provider. Local-client only, like Codex
+     * sign-in: the remote engine relay does not admit these methods.
+     */
+    private anthropicProviderAuth;
+    /**
+     * Record the account email a sign-in just verified on the provider entry that names it.
+     *
+     * The label that tells two linked accounts apart is derived from this stored email, and a window
+     * can sign in from the provider's detail panel where no form save follows. Best effort: a
+     * configuration that cannot be written must not turn a completed sign-in into an error.
+     */
+    private recordCodexEmail;
+    /**
+     * Test one provider's connection exactly as configured, for the settings surface's Test button.
+     *
+     * `model` names one model to check instead of the provider's active one: the probe is the same
+     * listing either way, and `modelAvailable` then answers whether that model is on offer. The
+     * override never reaches the stored configuration.
+     *
+     * The probe is read-only and spends no tokens, and its deadline is the operation's own rather than
+     * the client's request deadline: a test that outlives the window that asked for it is a test whose
+     * answer the window can no longer show.
+     */
+    private testProviderEndpoint;
+    /** Run one long operation whose cancellation shutdown owns, optionally with its own deadline. */
+    private operation;
+    private accountStatus;
+    /**
+     * The signed-in account's own profile.
+     *
+     * The profile lives in the account service, so it follows the account rather than the machine:
+     * the same profile is the same on every installation that signs in.
+     */
+    private accountProfile;
+    /** Save the profile fields the owner changed. */
+    private updateAccountProfile;
+    /** What this account has done on this machine, in totals. */
+    private sessionStats;
+    private signIn;
+    private signOut;
+    private publishAccount;
+    /**
+     * The log a session's conversation was written to.
+     *
+     * A session the window started writes to the log named after its own id. A session the terminal
+     * created or continued writes to the log of that terminal's process, whose name is not the
+     * session's id, and the record names that log. The name is a file stem, never a path, so it can
+     * only name a log in this home.
+     */
+    private trajectoryIdOf;
+    private readSession;
+    /**
+     * The session behind a due wake, or `undefined` only when its record is genuinely not there.
+     *
+     * `readSession` is written for a client asking about a session, so a missing file, a lock, a permission
+     * problem and a half-written record all answer "that session no longer exists". For a delivery that answer
+     * is destructive: the wake would be spent - and its prompt lost - on a condition that clears by itself.
+     * Only a file that is not there is treated as a deleted session here; everything else is thrown so the
+     * caller can put the wake back and try again on the retry the registry gives a wake already due.
+     */
+    private readSessionForWake;
+    /**
+     * Run a session mutation as one step against every other writer of this home.
+     *
+     * A mutation is a read-modify-write of the whole record, so two that overlap lose one — and one
+     * that lands after a delete recreates what the user removed. The lock spans exactly the busy
+     * check, the fresh read, and the save; the check has to sit inside it, since the state it reads is
+     * the state the mutation is about to overwrite. A session held by another writer past the wait is
+     * answered `busy` rather than racing it.
+     */
+    private withSessionMutation;
+    private createSession;
+    private renameSession;
+    /**
+     * Persist a finished run's record without reverting what the user changed while it ran.
+     *
+     * The finalizer builds its record from the snapshot captured at startup, but a rename is now
+     * accepted mid-run: a bare save would put the old name back, and dropping the `renamed` pin with
+     * it would let the automatic title overwrite a name the user chose after the run settled. So the
+     * save re-reads the record under the same per-session mutation lock the user's own renames take.
+     * The fields this process owns — the turns, usage and widgets the run just produced — are written
+     * from the captured record; everything the user can edit stays with what is on disk. A read that
+     * finds nothing saves the captured record unchanged, as before: losing the finished turn would be
+     * the worse outcome. The lock is taken with retries because a rename's critical section is one
+     * small read-modify-write, and momentary contention must not turn a finished run into an unsaved
+     * one.
+     *
+     * The finalizer's summary-carrying events publish through `publish`, inside the same critical
+     * section as the save. Publishing after the lock would let a rename land in between: it would
+     * save and publish its new name, and the finalizer would follow with the older snapshot it
+     * holds, so the client's unconditional upsert would briefly revert the row the user just renamed.
+     */
+    private saveFinalizedSession;
+    /**
+     * Put a session away from (or back onto) the rail without deleting it.
+     *
+     * Archive is organization, not content: unlike rename it does not touch `updatedAt`, so archiving a
+     * session never reorders the list a user is reading. It is refused while the session owns a run for
+     * the same reason rename is — `executeRun` saves the record it captured at startup, which would
+     * silently revert the flag when the run finished, and a row that vanished mid-run would strand the
+     * approval it is waiting for.
+     */
+    private setSessionArchived;
+    private deleteSession;
+    /**
+     * Start one run and answer immediately with its identity.
+     *
+     * The execution continues in the background and reports through events, so a client can cancel,
+     * answer an approval, or open a terminal while the model works.
+     */
+    private startRun;
+    /**
+     * Resume a stopped attempt: a new run on the same session, continuing where the attempt stopped.
+     *
+     * The attempt being resumed has to be a recorded one whose process is gone: `succeeded` has
+     * nothing left to do, and `running` with a live pid is the original still working, not a stopped
+     * attempt. The session is not forked the way an explicit `run.start` resume-branch forks it:
+     * a resumed attempt belongs on the same timeline as the attempt it continues, so both turns —
+     * the stopped one and the new one — stay visible together. The new run gets its own id, its own
+     * journal, and its own open record; `resumedFrom` on both records names the lineage. Everything
+     * after this point is `run.start`'s own path — same events, same client run flow, one-run-per-
+     * engine guard included.
+     */
+    private resumeRun;
+    /**
+     * Switch the working tree to a branch, holding the tree for the whole operation.
+     *
+     * One run at a time, in both directions: a switch is refused while a run or a prepared start
+     * exists, and a start is refused while a switch is in flight. The reservation is taken before the
+     * first await, because the workspace resolution in between is exactly the window a `run.start`
+     * could otherwise slip through.
+     */
+    private switchBranch;
+    /** Refuse to continue work whose engine is shutting down. */
+    private assertRunning;
+    /**
+     * Start one run. `internal` is never client-supplied — it is how `run.resume` tells this
+     * method to continue an existing session in place instead of forking, which stopped
+     * attempt the new run continues, the message sent with that continuation, and the
+     * attachments the continued message carried.
+     *
+     * The wrapper owns the spools this request created: attachment resolution spools pastes and
+     * clipboard images before provider, permission, session, graph, and resume validation run. If any
+     * later check refuses the start — most simply when no provider is configured — the request has
+     * created no run and no persisted owner, and up to ~50 MB of the user's data would otherwise sit
+     * in the spool until the retention prune. Every rejection below propagates through here, and
+     * every spool this request wrote is deleted; a successful start owns its spools as part of the
+     * run. `prepareRunValidated` is the body: the wrapper exists only to own that cleanup.
+     */
+    private prepareRun;
+    /**
+     * The graph this run executes, with the model's override applied when the run asked for one.
+     *
+     * The override rewrites the copy the run reads, never the saved graph: a run that overrides
+     * every node must not change what the next run of the same graph does. Applying it here — where
+     * the graph is loaded — is what keeps the runner, the resume guard and the health preflight from
+     * disagreeing about the model a node runs, because all three read this same graph.
+     */
+    private graphForRun;
+    private prepareRunValidated;
+    /**
+     * Name a brand-new session from its first prompt with one bounded model request.
+     *
+     * The session already displays its local name, so this only upgrades it: any failure keeps the
+     * local name and never touches the run. The request is queued behind the run's first provider
+     * answer — the one inference turn a serializing endpoint must not be made to wait for — and goes
+     * out while the run executes that turn's tools, so the row carries the real name for the task
+     * instead of its first words cut off, and a task the user stops early is still named. The title
+     * does not belong to the run's lifetime either: stopping the run leaves it generating.
+     *
+     * The record on disk is read back under the lock the user's own renames take, so a name chosen
+     * once the run is over is never momentarily reverted, a session claimed by another run is left to
+     * that run's snapshot, and a deleted session is never recreated on the rail. While this run is
+     * still working, the save is written underneath it: the finalizer merges the record it finds, so
+     * the finished attempt keeps the name this saved.
+     */
+    private titleSessionFromPrompt;
+    /**
+     * Let a title request that was waiting for its run go ahead: the run answered the provider for the
+     * first time, or ended without ever doing so.
+     */
+    private releaseTitleWaiter;
+    /** Abort title requests still on the wire: new work is about to need the provider itself. */
+    private cancelSessionTitles;
+    private executeRun;
+    /**
+     * The run's adapter, with each call's reasoning published to the connected window.
+     *
+     * Reasoning is display-only: those events go to the client and are deliberately never written to
+     * the run journal, the session record, or the trajectory (see `app-server/reasoning.ts`). A call
+     * made outside a run has no stream to publish into, so it is left as an adapter that simply does
+     * not report reasoning.
+     */
+    private reasoningAdapter;
+    /**
+     * The adapter a run resolves, recorded into the session's trajectory: every model call of the
+     * run — request, response, error — lands in the per-session debug log with the run and provider
+     * that made it. The trajectory wrap sits outside the reasoning wrap for the same reason the
+     * CLI's does: reasoning is display-only and never reaches records. Calls made outside a run
+     * (no trajectory open) pass through unchanged.
+     */
+    private tracedAdapter;
+    /**
+     * Serialize all writes to a live run's JSON record, including the preflight shape stamp,
+     * accepted model selections, and the terminal result. The recovery reader can then see
+     * either the old selection or the fully durable new one, never an overlapping stale write.
+     */
+    private serializeRunRecordWrite;
+    /** Change the next model turn without aborting a stream or replaying tools. */
+    private setRunModel;
+    private resolveModel;
+    /**
+     * The client-visible configuration with the plan-aware analytics answer.
+     *
+     * Resolved on every read rather than cached: the account can sign in, sign out, or confirm a plan
+     * between two reads, and a settings page that showed a stale opt-out is exactly the disagreement
+     * the plan gate exists to remove.
+     */
+    private analyticsConfigView;
+    private resolveProvider;
+    /**
+     * One code-intelligence manager per workspace, reused across runs and released at shutdown.
+     *
+     * Two guards come from the terminal path and exist for the same reasons here: Read Only mode
+     * suspends indexing because the cache requires writes, and a project that *is* the user's home
+     * directory never indexes automatically, because a desktop user can pick any folder and
+     * recursively crawling a personal tree must not be an implicit side effect of opening the app.
+     */
+    private codeIntelligence;
+    /** Code-intelligence events belong to the active run's stream when one is running. */
+    private runEvent;
+    /**
+     * Journal first, then the client: a client that missed an event can re-read the record.
+     *
+     * `runs/` is created here rather than assumed: the terminal client creates it during startup,
+     * and this mode returns before that code runs, so a fresh configuration home would otherwise
+     * fail every append with ENOENT and silently produce no record at all.
+     */
+    private recordRunEvent;
+    private ensureRunRecords;
+    private interaction;
+    private approve;
+    private ask;
+    private settleApproval;
+    /**
+     * How a run engine without the panel browser asks the desktop to run its
+     * agent's panel operations on the engine that owns the panel. The request
+     * travels as a `browser.panel.request` event and the desktop answers through
+     * `browser.panel.result` — the same exchange shape an approval uses.
+     */
+    private panelBrowserRelayFor;
+    private settlePanelRelay;
+    private settleAnswer;
+    private cancelRun;
+    /**
+     * Queue a message into the live attempt's steering channel.
+     *
+     * The runtime polls that channel at turn boundaries and injects each message into the node's own
+     * conversation, so the attempt redirects without being cancelled and the node keeps the plan and
+     * context it built. Nothing is delivered by this call: the answer says the message is queued, and
+     * `run.steered` announces it so every window draws the user's own row immediately. What the run
+     * never read is reported on its terminal event, so a message that arrived too late is returned
+     * to the composer instead of disappearing.
+     *
+     * `runId` must name the attempt this engine is actually running. A message for any other attempt
+     * — one that already finished, or another engine's — is refused rather than queued, because a
+     * queue nobody polls would look exactly like a delivered message.
+     */
+    private steerRun;
+    /**
+     * The directory an account's graphs live in, with the identity it was chosen for.
+     *
+     * The two travel together because they are one decision: a caller that read the subject again afterwards
+     * could label one account's names with another's identity if the credentials changed while the listing
+     * was being read.
+     *
+     * The account's cloud copy is brought current first, the way the CLI's graph editor does it: a graph
+     * saved on another machine reaches this one only through a sync, and the window lists graphs without
+     * ever opening the editor. The wait is bounded and a sync that fails leaves the copy already here.
+     *
+     * Ownership is decided here too. A directory no account has claimed is shared, so a sync that ran
+     * there would restore account A's cloud graphs into it and account B's install would then upload
+     * them into B's account. `graphStorageAccess` claims an unclaimed directory for a confirmed account —
+     * the account the builder claims it for — and reports the ones that are still shared.
+     */
+    private graphDirectory;
+    /**
+     * Whether the account service confirms this account, paid or free.
+     *
+     * The verdict is only definitive for the account it names: an answer that arrived while the
+     * credentials changed describes the other account, and claiming this installation's graph directory
+     * for it would bind legacy local graphs to an account that is no longer signed in.
+     */
+    private currentAccountIsConfirmed;
+    private listGraphs;
+    /**
+     * The shareable file of one library Agent, for the desktop's Share action to write into the
+     * user's Downloads folder. Agents live in this home's own library, not an account's graph
+     * store, so no account attribution applies; only the id crosses from the editor frame.
+     */
+    private exportAgent;
+    private getGraph;
+    /**
+     * Persist the installation's graph selection.
+     *
+     * The Andorra preset is selectable per run but not storable: the configuration schema admits only
+     * word-character graph ids, so `:andorra` would make the next config load fail. The desktop keeps
+     * that choice per project instead and passes it to `run.start`.
+     */
+    private selectGraph;
+    private openEditor;
+    private closeEditor;
+    /**
+     * Run a serve/lock transition behind every other one this process has queued.
+     *
+     * Two concurrent `remote.hosting.status` calls would otherwise race the same serve lock from one
+     * process: the loser sees a busy lock whose descriptor the winner has not written yet and
+     * reports the listener this engine is starting as a foreign one. `startRemoteServe` and the
+     * status handler — the two paths that can start a listener — share this queue.
+     */
+    private serializeRemote;
+    /**
+     * Bring up or adopt this installation's remote listener, holding it until close.
+     *
+     * Called once at engine startup, after which a paired machine can reach this one while the
+     * desktop is open. With no devices and no active invitation the ensure resolves to not-serving
+     * without binding a port, so an unpaired install pays nothing; a later Settings-open grows the
+     * listener through the status handler, which queues behind this one.
+     */
+    startRemoteServe(): Promise<void>;
+    /** A peer-side failure as a wire error; the UI branches on `status`, not on these codes. */
+    private remoteError;
+    /** The failure kinds that mean "this address did not answer" — all others end the host sequence. */
+    private remoteStatusFailure;
+    /**
+     * Run one peer call against the workspace's hosts in order, trying the next address only when
+     * this one was unreachable. An identity or authorization answer is about the machine, not the
+     * address: probing a second host would repeat it or paper over a certificate swap with an older
+     * address that still answers.
+     *
+     * The failure is converted for RPC boundaries that throw it at the window. A liveness probe is
+     * not one of those — it reads the failure's kind to report `offline`/`unauthorized`/
+     * `identity-changed` — so it asks for the peer error itself via `preservePeerError`; converting
+     * would flatten every kind into a generic network error and the status surface would never see a
+     * state other than `unknown`.
+     */
+    private peerCall;
+    /**
+     * The peer target for a stored workspace, with the hosts to try in order: the operator's
+     * host override first (moving the target without touching trust — identity is the pinned
+     * fingerprint), then every address the pairing code advertised.
+     */
+    private remoteTarget;
+    /** The stored workspace as the wire sees it: never the device token, never the certificate. */
+    private remoteWorkspaceView;
+    /**
+     * The host-side Settings surface, and the call that starts hosting.
+     *
+     * The listener a status call starts belongs to this engine until close — that is what makes the
+     * desktop closing read as offline to peers unless a standalone `andorra remote serve` owns the
+     * lock; an adopted handle releases to nothing, so there is nothing to hold.
+     */
+    private remoteHostingStatus;
+    /**
+     * Replace the live invitation with a fresh one — the Settings page's "New code" action.
+     *
+     * The status call replaces an invitation only after it expires or is redeemed, so a code that was
+     * pasted somewhere it should not have been stays redeemable for the rest of its ten minutes. This
+     * is the explicit way to invalidate it: the previous token stops working the moment the new
+     * invitation is written, and the answer is the same hosting snapshot the page already renders.
+     */
+    private remoteHostingInvitationFull;
+    private remoteHostingInvitationRegenerate;
+    private remoteShareAdd;
+    private remoteShareRemove;
+    private remoteDeviceRevoke;
+    /**
+     * Raise a paired device to full owner authority, and answer with the refreshed hosting snapshot.
+     *
+     * The grant is the Settings alternative to revoke-and-re-pair the product contract names; like a
+     * full-scope invitation it is refused over cleartext hosting, because the token that would carry
+     * the authority travels the wire unencrypted there.
+     */
+    private remoteDeviceGrant;
+    /**
+     * Open (or replace) this engine's relay link to one paired workspace.
+     *
+     * Idempotent per connection id — the desktop reconnects after its own restarts and must not pay
+     * for a second stream while the first still runs. The answer carries what the peer's identity
+     * probe said (including the engine capabilities its relay serves), which is what the desktop uses
+     * to decide which controls the link can honor.
+     */
+    private remoteEngineConnect;
+    /** End this engine's relay link to one workspace, if it holds one. */
+    private remoteEngineDisconnect;
+    /**
+     * One workspace's event stream, held until the link is replaced or disconnected.
+     *
+     * A stream that ends is retried after a pause — a serve restarting, a machine rebooting — but only
+     * while the stored pairing is still the one the link was opened for, and never for the verdicts a
+     * retry would repeat forever: an identity change or a revocation is reported to the window as a
+     * closed link instead.
+     */
+    private runEngineLink;
+    /**
+     * One relayed engine request: a full-grant pairing's client surface, proxied through the same
+     * host walk every other peer call uses, with the caller's own deadline carried across so a slow
+     * method keeps the budget the desktop granted it.
+     */
+    private remoteEngineRequest;
+    /**
+     * Every paired workspace with a live liveness probe.
+     *
+     * The probes run together because each is bounded by the client's own timeout; a workspace whose
+     * machine is asleep costs one timeout, not one per remaining workspace. A successful probe also
+     * refreshes the identity fields from the peer itself, so a rebuilt machine shows its new name.
+     */
+    private remoteWorkspacesList;
+    /**
+     * One workspace's state, probed against the peer addresses the listing would walk.
+     *
+     * Shared by the listing and the single-workspace re-check: a window watching a machine that is
+     * not online asks for that one workspace, and must reach the same answer a full listing would
+     * have produced for it — the same address order, the same failure kinds, the same identity fields.
+     */
+    private remoteWorkspaceState;
+    /**
+     * Re-probe one paired workspace.
+     *
+     * A missing id is the window's stale view of a pairing removed elsewhere, answered as not-found so
+     * the client drops the row instead of treating an unknown workspace as an unreachable machine.
+     */
+    private remoteWorkspaceProbe;
+    /**
+     * The fields a probe answer depends on, as one comparable value.
+     *
+     * The cached identity fields are deliberately absent: they describe the machine as some earlier
+     * answer saw it, not what this walk was asked to reach, and only pairing writes them. Everything
+     * listed here is a fact about the target, so a difference means the answer above is not this row's.
+     */
+    private remoteProbeIdentity;
+    /**
+     * What a link's reconnect must agree on: trust and addressing. The display label is not among
+     * them — a rename while a run's link is live is not a pairing replacement, and closing the link
+     * for one would abandon work over a cosmetic edit.
+     */
+    private remoteTrustIdentity;
+    /**
+     * Redeem a pasted pairing code and store the workspace.
+     *
+     * The credential and the pinned certificate come back from the redemption itself; the invitation
+     * is single-use, so the peer rejects a second redemption of the same code. Nothing here is
+     * retried against another host after a refusal: a refused invite stays refused.
+     */
+    private remoteWorkspaceAdd;
+    private remoteWorkspaceRemove;
+    private remoteWorkspaceRename;
+    /**
+     * Move a workspace's target address without touching its trust anchor.
+     *
+     * The override is what a DHCP lease change asks for: the fingerprint pin still decides which
+     * machine is the paired one, so pointing at a new address cannot adopt a different certificate.
+     * A null host removes the override and falls back to the advertised addresses.
+     */
+    private remoteWorkspaceSetHost;
+    /**
+     * Everything a peer will let this device browse: its registered projects and its explicit
+     * shares. Labels are the peer's chosen display names — absolute paths never cross the wire.
+     */
+    private remoteRootsList;
+    private remoteProjectsFetch;
+    private remoteBrowse;
+    private remoteOwnerRoots;
+    private remoteOwnerBrowse;
+    private remoteOwnerAddProject;
+    private listProjects;
+    /**
+     * Register a project folder, canonicalized so the registry and a peer's root ids agree.
+     *
+     * realpath makes `projects.add` idempotent across junctions, symlinks, and Windows drive-letter
+     * case, and it is the same canonical form `projectRootId` hashes — so the id a peer derives and
+     * the id this machine hosts cannot drift apart by spelling.
+     */
+    private addProject;
+    private removeProject;
+    /** The wakes one session is waiting on, in the shape a client draws them in. */
+    private timersFor;
+    /**
+     * A session summary plus what only this process knows: the wakes it is holding, and whether a run of
+     * this session is in flight.
+     *
+     * A row reads its task's story off the saved record, and the saved record lags a live run — the turn
+     * being written is not in the file yet, so the last saved one still reads as finished. Naming the run
+     * here is what keeps a session that is working from being drawn as a task that is done with you.
+     */
+    private summary;
+    /**
+     * The summary a completed or failed run publishes, built without the live-run override.
+     *
+     * The terminal story is the saved record's: a completion says the session is done (or waiting on an
+     * armed wake), never running. Building the payload from the record alone keeps that true whatever
+     * the engine's live-run slot holds at the instant of the emit, rather than relying on the slot
+     * having been released a statement earlier in the finalizer.
+     */
+    private terminalSummary;
+    /**
+     * Every wake this process is holding, grouped by the session that armed it.
+     *
+     * The desktop runs one engine per task, so the wakes a session is waiting on can live in a process its
+     * `sessions.list` never reaches: the primary answers for every session on disk and knows only its own
+     * registry. This is how a window that has just reloaded asks each engine it reattached to what it is still
+     * holding — without it a row whose wake is alive loses its clock, and the user has no way to see that the
+     * task is still coming back.
+     */
+    private listTimers;
+    /** Say what a session is waiting on. An empty list is a real answer: it is what ends a wait. */
+    private emitPullRequest;
+    /**
+     * Start tracking `ref` for the session. A PR already tracked under the same URL keeps its settings, so a
+     * repeated `gh pr create` (which reports the existing PR) never switches off what the user turned on.
+     */
+    private attachPullRequest;
+    private updatePullRequest;
+    private dismissPullRequest;
+    /**
+     * Withdraw an Auto-fix wake this engine holds. One held by another engine is not reachable from here; that
+     * engine checks the record again before it delivers (`deliverDueTimers`), and finds the wake unwanted.
+     */
+    private cancelAutoFixWake;
+    /** The `pull_request` tool's view of one session's PR; `carry` is the calling run's selections. */
+    private pullRequestControl;
+    /**
+     * Hand an Auto-fix prompt to the session through the same wake a `set_timer` arms, under the selections the
+     * session's PR was configured from: without them the continuation would run under whatever graph and model
+     * the configuration names today, with different tools than the work it is fixing.
+     */
+    private wakeForPullRequest;
+    private emitTimers;
+    /**
+     * Publish what a session whose run just ended is waiting on, and arm the next deadline.
+     *
+     * A wake still armed means the session is waiting rather than finished, and the engine is the only thing
+     * left that can deliver it. Nothing armed means the row is free to read as completed.
+     */
+    private settleSessionTimers;
+    /** Arm the next deadline check, across every session this engine holds wakes for. */
+    private armTimerCheck;
+    /**
+     * When this engine should next look for a due wake, across every session it holds wakes for.
+     *
+     * Not the same thing as the soonest deadline: a wake a delivery handed back is not looked at again until the
+     * beat it came back for has passed, which the registry records on the wake itself. One sweep serves every
+     * session this engine has served, so a sweep that read the floor as the deadline would keep arriving at the
+     * wake that cannot be delivered, and reach the ones that can only after it.
+     */
+    private nextWakeLook;
+    /** Begin a delivery pass when none is going. Called by the registry's due callback and by the check. */
+    private checkTimers;
+    /**
+     * Give every wake that has come due to the session that armed it, one run at a time.
+     *
+     * Each is started on the path a task submitted over the socket takes, so a client sees one lifecycle for
+     * both and the row moves from waiting to running on its own. A wake waits out a run that is already going:
+     * a deadline says the earliest a prompt may be given, not the moment it is, and a session whose engine is
+     * busy is not that moment. A wake whose session has been deleted is dropped — it has no conversation left
+     * to return to. A delivery the engine refuses because it is already busy is put back and tried again: that
+     * refusal describes the moment, not the task. Any other refusal is reported and left spent, rather than
+     * retried on a deadline forever; the row stops saying the session is waiting on it. A wake whose session
+     * cannot be read is put back for the beat its restore armed it for, and the pass carries on: one session's
+     * unreadable record says nothing about what another session is owed.
+     */
+    private deliverDueTimers;
+    /**
+     * Re-reconcile the runs a foreign engine still owned when this one started, once that engine exits.
+     *
+     * Startup recovery leaves an open record alone while its pid is alive, because a second engine on
+     * this home may genuinely be running it. In the close-and-immediately-reopen flow that holder is
+     * the engine that was shutting down: by the time it exits, this engine has already answered
+     * `sessions.list` with the stale `running`, and the rail reloads nothing on its own — so neither
+     * the spinner nor the interruption mark would show until the window reloads. Poll each holder, and
+     * as soon as one exits, re-run recovery scoped to exactly the records this watch captured
+     * (`onlyRunIds`), then republish the sessions those records name: a window already holding the
+     * stale row gets the correction as an ordinary `session.updated`, and a client that connects later
+     * reads the corrected record off disk. The scoping is what keeps this safe next to live work: this
+     * engine may have started its own run by the time a predecessor dies, and an unscoped sweep — whose
+     * pid check treats a record owned by this very process as stale — would stamp that active attempt
+     * `interrupted` and hand out a Resume for work that is still running. A holder that outlives the
+     * wait is accepted as a genuinely running engine — its work is left exactly as recovery intended.
+     */
+    watchForeignEngineShutdown(owners: {
+        runId: string;
+        pid: number;
+        sessionId: string | undefined;
+    }[]): void;
+    /** Release everything this process owns. Safe to call twice. */
+    close(): Promise<void>;
+}
+/** Run the engine until stdin closes or a client asks for shutdown. Returns the process exit code. */
+export declare function runAppServer(options?: AppServerOptions & {
+    input?: NodeJS.ReadableStream;
+}): Promise<number>;
+export { AppServerError };