@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/host.js

@@ -0,0 +1,625 @@
+/**
+ * The Code-thread host inside `prohost agent run`: one object the harness
+ * starts when this machine's owner has turned hosting on
+ * (`prohost agent code-host enable`), and hands the three events it serves —
+ * `code_thread.start_requested`, `.input_requested` and `.approval_decided`.
+ *
+ * Off — the default — the harness never builds one: no tmux, no relay socket,
+ * no local server, no host stats, and the events are acknowledged as ignored.
+ */
+import { writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { prohostHome } from '../agent/credentials.js';
+import { ActivityReporter } from './activity.js';
+import { AGENT_BINARIES, agentCapabilities, installedAgents, resolvesOnPath } from './agents.js';
+import { CodeThreadCheckouts } from './checkouts.js';
+import { event, fileEventSink, writeHookConfig } from './events.js';
+import { foldersStamp, reportFolders } from './folders.js';
+import { codexNotifyOverride, installHookFiles } from './hooks.js';
+import { HostStatsSampler } from './host_stats.js';
+import { acknowledgeCompletedApproval, completedApprovals, decide, hookDecides, menuState, readWaiter } from './decision.js';
+import { DeliveryLedger } from './ledger.js';
+import { LocalTerminalServer } from './local_server.js';
+import { loadNodePty } from './pty.js';
+import { CodeHostRelay } from './relay.js';
+import { codeHostDir, codeHostInstanceId, ensurePrivateDir, loadSettings } from './settings.js';
+import { CodeTerminals, execTmux } from './terminals.js';
+import { APPROVAL_DECISIONS, isValidId, socketNameFor, TMUX_CONF } from './tmux.js';
+export const EVENT_CODE_THREAD_START_REQUESTED = 'code_thread.start_requested';
+export const EVENT_CODE_THREAD_INPUT_REQUESTED = 'code_thread.input_requested';
+export const EVENT_CODE_THREAD_APPROVAL_DECIDED = 'code_thread.approval_decided';
+/**
+ * Declared in `runtime_status.capabilities` while this harness hosts threads.
+ * Versioned with the contract the server relies on (`remote_terminal`, 409
+ * refusals; a prompt's own `hook_decision` capability says how its decision is
+ * answered): an older CLI's `code_threads` is not listed.
+ */
+export const CODE_THREADS_CAPABILITY = 'code_threads_v2';
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} while the owner allows remote
+ * terminals. It rides the `/ws/webhooks` socket into the pairing's row in
+ * Postgres, where the backend API reads it (hosts listing, shell create,
+ * terminal-token) whatever fleet and Redis it runs against.
+ */
+export const REMOTE_TERMINAL_CAPABILITY = 'remote_terminal';
+/**
+ * Declared with the instance id appended (`host_instance_<32 hex>`) beside
+ * {@link CODE_THREADS_CAPABILITY}: the server binds each thread to the
+ * instance that accepted its start and routes its frames only there.
+ */
+export const HOST_INSTANCE_CAPABILITY_PREFIX = 'host_instance_';
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} by a host that starts threads
+ * in a folder (`folder` / `separateCopy` in `code_thread.start_requested`, the
+ * opened-folders list, `code_host_folders` on the status frame). The server
+ * sends a folder start only to a socket that declared it.
+ */
+export const CODE_THREAD_FOLDERS_CAPABILITY = 'code_thread_folders';
+function text(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** `code_thread.start_requested` data (camelCase per the contract), or `null`. */
+export function parseStartRequest(data) {
+    const codeThreadId = data.codeThreadId;
+    const terminalId = data.terminalId;
+    if (!isValidId(codeThreadId) || !isValidId(terminalId))
+        return null;
+    // An agent this CLI doesn't know is reported as a failed start, not dropped.
+    const agent = (text(data.agent) ?? 'claude_code');
+    // A folder start (`folder` set): in place, or in a separate copy. Anything but a non-empty string
+    // is a repository thread, as from a server before folders.
+    const folder = text(data.folder) || undefined;
+    return {
+        codeThreadId,
+        terminalId,
+        goal: text(data.goal) ?? '',
+        repo: text(data.repo) ?? '',
+        branch: text(data.branch) || undefined,
+        agent,
+        ...(folder ? { folder, separateCopy: data.separateCopy === true } : {}),
+    };
+}
+/** `code_thread.input_requested` data, or `null`. */
+export function parseInputRequest(data) {
+    const { codeThreadId, terminalId } = data;
+    const value = text(data.text);
+    if (!isValidId(codeThreadId) || !isValidId(terminalId) || value === undefined)
+        return null;
+    return { codeThreadId, terminalId, text: value };
+}
+/** `code_thread.approval_decided` data, or `null`. */
+export function parseApprovalDecision(data) {
+    const { codeThreadId, terminalId, approvalId, decision } = data;
+    if (!isValidId(codeThreadId) || !isValidId(terminalId))
+        return null;
+    if (typeof approvalId !== 'string' || !approvalId || approvalId.length > 128)
+        return null;
+    if (typeof decision !== 'string' || !APPROVAL_DECISIONS.has(decision))
+        return null;
+    return { codeThreadId, terminalId, approvalId, decision: decision };
+}
+/** A start ran (or failed) but ProhostAI hasn't heard: redeliver, don't ack. */
+/**
+ * A reply or decision this Mac refuses before typing anything, with the reason
+ * the server shows on the thread (the harness acks it 409 + `reason`, and the
+ * server hands the reply or decision back instead of counting it delivered).
+ */
+export class RefusedDeliveryError extends Error {
+    reason;
+    constructor(reason) {
+        super(`refused: ${reason}`);
+        this.reason = reason;
+    }
+}
+export class UnreportedOutcomeError extends Error {
+    constructor(codeThreadId) {
+        super(`the outcome of code thread ${codeThreadId.slice(0, 12)}'s start has not reached ProhostAI yet`);
+    }
+}
+/**
+ * How long a reply waits for a hook to apply the decision it was handed (it prints it and exits
+ * within a poll, 100 ms) before it is sent again later instead of typed.
+ */
+export const DECISION_APPLY_WAIT_MS = 2_000;
+/** A `remote off` ends open terminals within this long. */
+export const SETTINGS_POLL_MS = 2_000;
+/** How often live terminals' worktree lanes are marked in use (pruning is after 14 idle days). */
+export const LANE_REFRESH_MS = 3_600_000;
+export class CodeHost {
+    options;
+    terminals;
+    env;
+    stats;
+    deliveries;
+    relay;
+    local;
+    watcher;
+    laneKeeper;
+    remoteAllowed = false;
+    recoveringPermissions = false;
+    events;
+    /** Set while the relay refuses this pairing (revoked key, inactive pairing). */
+    pairingRefused;
+    /** Whose pairing this is, from the relay's last `auth_ok`; the desktop socket is bound to it. */
+    identity;
+    stopped = false;
+    instanceId;
+    log;
+    checkouts;
+    /** What {@link offeredRepos} answers, read at {@link start}. */
+    offered;
+    /** `folders.json` as last seen by the settings poll: a change re-sends the status frame. */
+    foldersSeen = '';
+    /** Hosting (`enabled`) as last seen on disk: `code-host disable` closes the desktop socket at once. */
+    enabledSeen = true;
+    /** `code-host/activity.json`, for the desktop app's keep-awake (`activity.ts`). */
+    activity;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.log = options.log ?? (() => { });
+        const home = prohostHome(this.env);
+        const dir = codeHostDir(this.env);
+        const confPath = path.join(dir, 'tmux.conf');
+        ensurePrivateDir(dir);
+        writeFileSync(confPath, TMUX_CONF, { mode: 0o600 });
+        const hookFiles = installHookFiles(options.nodePath ?? process.execPath, options.cliEntrypoint, this.env);
+        this.stats = new HostStatsSampler({ slots: options.slots });
+        this.deliveries = new DeliveryLedger(this.env);
+        this.checkouts = new CodeThreadCheckouts({ repos: options.repos, env: this.env, log: this.log });
+        this.instanceId = codeHostInstanceId(this.env);
+        this.activity = new ActivityReporter(this.env);
+        this.events = options.events ?? fileEventSink(this.env);
+        this.terminals = new CodeTerminals({
+            home,
+            socket: socketNameFor(home),
+            confPath,
+            tmux: options.tmux ?? execTmux(),
+            spawnPty: options.spawnPty ?? loadNodePty,
+            checkouts: this.checkouts,
+            events: this.events,
+            hookFiles: { claudeSettings: hookFiles.claudeSettings, claudeInvocationSettings: hookFiles.claudeInvocationSettings,
+                hookShim: hookFiles.shim, codexNotify: codexNotifyOverride(hookFiles.shim) },
+            accountEnv: options.accountEnv,
+            agentInstalled: (agent) => resolvesOnPath(AGENT_BINARIES[agent], this.env),
+            authorized: () => this.authorized(),
+            remoteControlAllowed: () => this.settings().allowRemoteTerminal,
+            log: this.log,
+        });
+    }
+    settings() {
+        return loadSettings(this.env);
+    }
+    remoteTerminalAllowed() {
+        return this.settings().allowRemoteTerminal;
+    }
+    instanceCapability() {
+        return `${HOST_INSTANCE_CAPABILITY_PREFIX}${this.instanceId}`;
+    }
+    /**
+     * Only the agents a start would accept: installed here, and runnable on this harness's login
+     * (`accountEnv`: a Claude Code harness hosts no Codex thread). A host-only daemon has no login of
+     * its own and runs whichever is installed.
+     */
+    agentCapabilities() {
+        const accountEnv = this.options.accountEnv;
+        return agentCapabilities(installedAgents(this.env).filter((agent) => !accountEnv || accountEnv(agent).ok));
+    }
+    offeredRepos() {
+        return this.offered;
+    }
+    openedFolders() {
+        return { folders: reportFolders(this.env), home: os.homedir() };
+    }
+    /** The latest host stats, for the heartbeat. Sampled by the relay loop and on demand. */
+    latestStats() {
+        return this.stats.latest();
+    }
+    async sampleStats() {
+        return this.stats.sample();
+    }
+    async start() {
+        // What a person may pick for a thread here: read once, the checkouts are this process's.
+        this.offered = await this.checkouts.offered();
+        // The tmux.conf was just rewritten (constructor): a server from before this start still runs the old one.
+        await this.terminals.reloadConfig();
+        const adopted = await this.terminals.adopt();
+        const settings = this.settings();
+        this.log(`    ⚙ hosting Code threads${adopted ? ` (${adopted} running, re-adopted)` : ''} — remote terminal ` +
+            (settings.allowRemoteTerminal ? 'ALLOWED' : 'off (prohost agent code-host remote on)'));
+        void this.stats.sample();
+        if (this.options.relay !== false) {
+            this.relay = new CodeHostRelay({
+                baseUrl: this.options.baseUrl,
+                apiKey: this.options.apiKey,
+                machineId: this.options.machineId,
+                instanceId: this.instanceId,
+                machine: this.options.machine,
+                clientVersion: this.options.clientVersion,
+                settings: () => this.settings(),
+                stats: () => this.stats.sample(),
+                terminals: this.terminals,
+                onHostToken: (token, expiresAt) => writeHookConfig({ version: 1, endpoint: this.options.baseUrl, token, expires_at: expiresAt }, this.env),
+                onAuthorization: (authorized, reason, identity) => void this.onAuthorization(authorized, reason, identity),
+                onDisconnected: () => void this.onRelayDisconnected(),
+                log: this.log,
+            });
+            this.relay.start();
+        }
+        this.remoteAllowed = settings.allowRemoteTerminal;
+        this.enabledSeen = settings.enabled;
+        this.foldersSeen = foldersStamp(this.env);
+        await this.startLocal();
+        this.reportActivity();
+        this.watcher = setInterval(() => {
+            void this.applySettings();
+            void this.recoverCompletedPermissions();
+            this.reportActivity();
+        }, this.options.settingsPollMs ?? SETTINGS_POLL_MS);
+        this.watcher.unref?.();
+        // A terminal left alone for weeks still lives in tmux: keep its worktree from being pruned as idle.
+        this.laneKeeper = setInterval(() => void this.terminals.refreshLiveLanes(), LANE_REFRESH_MS);
+        this.laneKeeper.unref?.();
+    }
+    /**
+     * Whether an agent here is mid-turn, written for the desktop app's keep-awake (`activity.ts`) —
+     * only while hosting is on; turned off, the file goes.
+     */
+    reportActivity() {
+        if (this.stopped || !this.settings().enabled) {
+            this.activity.clear();
+            return;
+        }
+        this.activity.tick(this.terminals.list().map((record) => record.terminalId));
+    }
+    /** The daemon outlives timed-out/killed hooks and retries recovery after reconnect or restart. */
+    async recoverCompletedPermissions() {
+        if (!this.authorized() || this.recoveringPermissions)
+            return;
+        this.recoveringPermissions = true;
+        try {
+            for (const record of this.terminals.list()) {
+                if (record.agent !== 'claude_code')
+                    continue;
+                for (const approvalId of completedApprovals(record.terminalId, this.env)) {
+                    if (!this.authorized())
+                        return;
+                    const original = readWaiter(record.terminalId, approvalId, this.env)?.permissionRequest;
+                    if (!original)
+                        continue;
+                    // Keep its original event fence and deadline; a late replay must not renew the hook's wait.
+                    const ingest = await this.events.post(record.codeThreadId, {
+                        ...original, data: { ...original.data, sentAtMs: Date.now() },
+                    });
+                    if (ingest < 200 || ingest >= 300)
+                        break;
+                    const status = await this.events.post(record.codeThreadId, event('permission_resolved', { approvalId }));
+                    if (status < 200 || status >= 300)
+                        break;
+                    acknowledgeCompletedApproval(record.terminalId, approvalId, this.env);
+                }
+            }
+        }
+        catch {
+            this.log('    ! permission recovery could not be reported; retrying on the next poll');
+        }
+        finally {
+            this.recoveringPermissions = false;
+        }
+    }
+    /**
+     * The switches as the desktop socket must see them: no remote terminal while
+     * the relay refuses this pairing, whatever the file says — a revoked
+     * pairing closes every way in, not only the relay's.
+     */
+    desktopSettings() {
+        const settings = this.settings();
+        return this.pairingRefused ? { ...settings, allowRemoteTerminal: false } : settings;
+    }
+    /**
+     * Whether this host may act for ProhostAI now: running, and the relay has
+     * not refused the pairing. A refusal holds until the next `auth_ok`, and
+     * gates everything the event socket asks for as well as every attach.
+     */
+    authorized() {
+        return !this.stopped && this.pairingRefused === undefined;
+    }
+    /** The relay authorized or refused this machine (see `CodeHostRelayOptions.onAuthorization`). */
+    async onAuthorization(authorized, reason, identity) {
+        // A frame already in flight when the host stopped reopens nothing.
+        if (this.stopped)
+            return;
+        const wasAuthorized = this.authorized();
+        if (!authorized) {
+            const first = this.pairingRefused === undefined;
+            this.pairingRefused = reason ?? 'refused';
+            // A refused pairing stops saying it hosts Code threads, at once: the server lists and
+            // admits a Mac on that declaration, and this host would refuse every start.
+            if (wasAuthorized)
+                this.options.onRemoteChanged?.();
+            if (first && this.local)
+                this.log(`    ⏹ closing the desktop fast path: the relay refused this pairing (${this.pairingRefused})`);
+            await this.closeLocal();
+            return;
+        }
+        this.pairingRefused = undefined;
+        if (!wasAuthorized)
+            this.options.onRemoteChanged?.();
+        const changed = identity?.accountId !== this.identity?.accountId || identity?.ownerUserId !== this.identity?.ownerUserId;
+        this.identity = identity;
+        // A different owner (a re-pairing): the old advertisement must go first.
+        if (changed)
+            await this.closeLocal();
+        await this.startLocal();
+    }
+    /**
+     * The relay went away. Whether this pairing is still authorized can't be
+     * known until it answers again, so the desktop socket closes now (its
+     * identity is forgotten) and reopens only on a fresh `auth_ok`. The event
+     * socket's work is not paused: that socket authenticates on its own, and
+     * an explicit refusal (`auth_error`) is what gates it.
+     */
+    async onRelayDisconnected() {
+        if (this.stopped)
+            return;
+        if (this.local)
+            this.log('    ⏸ desktop fast path closed until the relay confirms this pairing again');
+        this.identity = undefined;
+        await this.closeLocal();
+    }
+    async closeLocal() {
+        const local = this.local;
+        this.local = undefined;
+        local?.dropClients();
+        await local?.stop();
+    }
+    /**
+     * The desktop app's socket on 127.0.0.1, served whenever hosting is on — with
+     * the remote switch off as well: then it admits only attaches the relay
+     * vouches for as local (`local_server.ts`).
+     */
+    async startLocal() {
+        if (this.options.localServer === false || this.local || !this.authorized())
+            return;
+        if (!this.settings().enabled)
+            return;
+        // Bound to whose pairing this is, as the relay last confirmed it: only that
+        // user's app window, signed in to that workspace, attaches. Until the
+        // relay has said (or from a relay that doesn't say), there is no socket.
+        const identity = this.identity;
+        if (!identity)
+            return;
+        if (this.options.accountId && this.options.accountId.toLowerCase() !== identity.accountId) {
+            this.log('    ! desktop fast path off: agent.json and the relay disagree on this pairing’s workspace');
+            return;
+        }
+        const local = new LocalTerminalServer({
+            env: this.env,
+            accountId: identity.accountId,
+            ownerUserId: identity.ownerUserId,
+            settings: () => this.desktopSettings(),
+            terminals: this.terminals,
+            log: this.log,
+            // Identity comes from the relay, never from the app page.
+            verifyViewer: (token) => this.relay ? this.relay.verifyViewer(token) : Promise.resolve({ ok: false, reason: 'relay_unavailable' }),
+        });
+        this.local = local;
+        try {
+            await local.start();
+        }
+        catch (err) {
+            if (this.local === local)
+                this.local = undefined;
+            this.log(`    ! desktop fast path unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * The owner's switches, re-read: a terminal attached while remote access was
+     * allowed must not outlive it. Turning it off closes every relay viewer and
+     * every desktop viewer that was admitted as remote; the desktop socket stays
+     * up for local attaches. Turning hosting off (`code-host disable`) closes the
+     * desktop socket (and its `local.json`) too. The opened folders changing
+     * re-sends the status frame.
+     */
+    async applySettings() {
+        const settings = this.settings();
+        const stamp = foldersStamp(this.env);
+        if (stamp !== this.foldersSeen) {
+            this.foldersSeen = stamp;
+            this.options.onCodeHostChanged?.();
+        }
+        if (settings.enabled !== this.enabledSeen) {
+            this.enabledSeen = settings.enabled;
+            if (settings.enabled)
+                await this.startLocal();
+            else {
+                if (this.local)
+                    this.log('    ⏹ closing the desktop fast path: hosting was turned off');
+                await this.closeLocal();
+            }
+        }
+        const allowed = settings.allowRemoteTerminal;
+        if (allowed === this.remoteAllowed)
+            return;
+        this.remoteAllowed = allowed;
+        // Both places the switch is read hear it now: the pairing's socket (the API's hosts list and
+        // terminal-token mint) and the relay's presence (its attach check).
+        this.options.onRemoteChanged?.();
+        this.relay?.statusChanged();
+        // Already up while hosting is on; tried again here in case its last start failed.
+        if (allowed) {
+            await this.startLocal();
+            return;
+        }
+        this.relay?.dropStreams('the remote terminal was turned off');
+        this.local?.dropRemoteClients();
+    }
+    /** Every closer is attempted, whatever the one before it did; never rejects. */
+    async stop() {
+        this.stopped = true;
+        if (this.watcher)
+            clearInterval(this.watcher);
+        if (this.laneKeeper)
+            clearInterval(this.laneKeeper);
+        this.laneKeeper = undefined;
+        this.watcher = undefined;
+        // Hosting stopped: nothing here says this Mac is busy any more.
+        this.activity.clear();
+        const relay = this.relay;
+        const local = this.local;
+        this.relay = undefined;
+        this.local = undefined;
+        try {
+            relay?.stop();
+        }
+        catch (err) {
+            this.log(`    ! stopping the code-host relay: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            local?.dropClients();
+            await local?.stop();
+        }
+        catch (err) {
+            this.log(`    ! stopping the desktop fast path: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Whether this Mac takes `event` at all, read from the owner's switches on
+     * disk now — never cached. Anything that types into a terminal from
+     * ProhostAI (a reply, an approval) or opens a raw shell is remote control of
+     * this machine, so it needs the remote-terminal switch as well as hosting.
+     * The harness answers a refusal 204, as for a machine that doesn't host.
+     *
+     * Hosting itself (`enabled`) is latched for the process: this host exists only
+     * because it was on at startup, and `code-host disable` takes effect when the
+     * agent restarts, as the command says. Never re-read here: the runtime keeps
+     * advertising `code_threads_v2` until then, so a start refused for it would be
+     * acked 204 and leave its thread `starting` for good.
+     */
+    admits(event, data) {
+        if (!this.authorized())
+            return false;
+        const settings = this.settings();
+        // Every start is taken: one this Mac won't run (a shell with the remote switch off) is
+        // reported failed by `handleStart`, never acked 204 and left `starting`.
+        if (event === EVENT_CODE_THREAD_START_REQUESTED)
+            return true;
+        return settings.allowRemoteTerminal;
+    }
+    refusal(event) {
+        if (event === EVENT_CODE_THREAD_START_REQUESTED || !this.authorized())
+            return undefined;
+        const settings = this.settings();
+        return settings.allowRemoteTerminal ? undefined : 'remote_terminal_disabled';
+    }
+    /**
+     * Throws {@link UnreportedOutcomeError} when the outcome never reached the
+     * server, so the harness asks for the delivery again rather than ack it.
+     */
+    async handleStart(data) {
+        const request = parseStartRequest(data);
+        if (!request)
+            return false;
+        const result = await this.terminals.start(request);
+        if (!result.reported)
+            throw new UnreportedOutcomeError(request.codeThreadId);
+        return result.ok;
+    }
+    async handleInput(data, deliveryId) {
+        const request = parseInputRequest(data);
+        if (!request)
+            return false;
+        if (deliveryId && this.deliveries.has(deliveryId))
+            return this.repeat(deliveryId);
+        // Re-checked here as well as by the harness: the switch is read at the
+        // moment of typing.
+        if (!this.settings().allowRemoteTerminal)
+            throw new RefusedDeliveryError('remote_terminal_disabled');
+        // A permission menu may be up, and this reply's keys would answer it (its Enter picks the
+        // highlighted "Yes"). One the terminal owns: refused, so the server hands the reply back. One
+        // whose hook is still deciding: waited on a moment; past that, nothing is typed and it comes again.
+        const menu = await this.menuSettled(request.terminalId);
+        // Unknown application is a reportable refusal, not proof the menu is still open. The
+        // existing reason tells the server nothing was typed and the prompt MAY remain.
+        if (menu === 'open' || menu === 'unconfirmed')
+            throw new RefusedDeliveryError('prompt_open');
+        if (menu === 'deciding')
+            return this.retryLater(undefined, request.codeThreadId);
+        if (deliveryId && !this.deliveries.claim(deliveryId))
+            return this.repeat(deliveryId);
+        // Turned off while it waited behind another reply, before a key: refused, so handed back.
+        const outcome = {};
+        const typed = await this.terminals.input(request, outcome);
+        if (!typed && outcome.refused)
+            this.refuse(deliveryId, outcome.refused);
+        if (!typed && outcome.retry)
+            this.retryLater(deliveryId, request.codeThreadId);
+        return typed;
+    }
+    async handleApproval(data, deliveryId) {
+        if (!this.settings().allowRemoteTerminal)
+            throw new RefusedDeliveryError('remote_terminal_disabled');
+        const request = parseApprovalDecision(data);
+        if (!request)
+            return false;
+        // The decision is handed to the prompt's own hook, which answers exactly that prompt; no key
+        // is ever pressed. Refused once nothing waits for it: answered in the terminal, its wait ran
+        // out, or a window launched before hooks waited (whose prompts are the terminal's).
+        if (deliveryId && !this.deliveries.claim(deliveryId))
+            return this.repeat(deliveryId);
+        const outcome = hookDecides(request.terminalId, request.approvalId, this.env)
+            ? decide(request.terminalId, request.approvalId, request.decision, this.env)
+            : 'local';
+        if (outcome === 'local')
+            this.refuse(deliveryId, 'prompt_local');
+        this.log(`    ✓ code thread ${request.codeThreadId.slice(0, 12)}: ${request.decision} handed to its hook (approval ${request.approvalId.slice(0, 12)})`);
+        return true;
+    }
+    /** The terminal's menu state (`menuState`) once a hook that is still deciding has had a moment to finish. */
+    async menuSettled(terminalId) {
+        if (!isValidId(terminalId))
+            return 'clear';
+        const deadline = Date.now() + DECISION_APPLY_WAIT_MS;
+        for (;;) {
+            const state = menuState(terminalId, this.env, Date.now(), this.options.alive);
+            if (state !== 'deciding' || Date.now() >= deadline)
+                return state;
+            await (this.options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(50);
+        }
+    }
+    /**
+     * A refusal the server hands back. Nothing typed (the switch): the claim is
+     * released, so a redelivery after a lost ack is judged afresh rather than
+     * answered "done". Possibly typed (`reply_interrupted`): the claim stays, so it
+     * is never typed twice, and a redelivery is refused the same way.
+     */
+    refuse(deliveryId, reason) {
+        if (deliveryId) {
+            if (reason === 'reply_interrupted')
+                this.deliveries.refuse(deliveryId, reason);
+            else
+                this.deliveries.release(deliveryId);
+        }
+        throw new RefusedDeliveryError(reason);
+    }
+    /**
+     * A local failure before anything reached the pane: the claim is released and
+     * the harness acks 503, so the outbox sends it again and it is typed once.
+     */
+    retryLater(deliveryId, codeThreadId) {
+        if (deliveryId)
+            this.deliveries.release(deliveryId);
+        throw new Error(`code thread ${codeThreadId.slice(0, 12)}: could not reach its terminal; retrying`);
+    }
+    /**
+     * A delivery already acted on: done, unless it ended in a refusal, which is said again
+     * (`decision_unconfirmed`: a decision an older CLI pressed keys for, which may have landed).
+     */
+    repeat(deliveryId) {
+        const reason = this.deliveries.refusalFor(deliveryId);
+        if (reason === 'reply_interrupted' || reason === 'decision_unconfirmed')
+            throw new RefusedDeliveryError(reason);
+        return true;
+    }
+}