@naswerks/periscope 1.0.0

package/dist/host/host.js

@@ -0,0 +1,1294 @@
+/** How long to wait before re-offering held frames to the link. */
+const HELD_RETRY_MS = 250;
+/** How many refused undroppable frames one session may hold before the next is reported lost. */
+const HELD_FRAMES_MAX = 512;
+import { systemClock, systemTicker } from '../core/time.js';
+import { KeyedTurns } from '../core/keyed-turns.js';
+import { refusal } from '../core/refusal.js';
+import { ok, refuse } from '../core/result.js';
+import { ControllerLink } from '../control/link.js';
+import { WORKSPACE_PAGE_SIZE, hostConfigureResult, sessionListResult, workspaceListResult, transcriptFailed, transcriptListResult, transcriptTailResult, unsetHostConfiguration, workspaceReleaseBulkResult, workspaceReleaseEntryResult, workspaceReleaseResult, repositoryListResult, repositoryReadResult, stateTransitionUpdate, } from '../control/frames.js';
+import { forwardSession } from '../control/stream.js';
+import { localGate } from '../gate/local.js';
+import { recordGateOutcome } from '../gate/outcome.js';
+import { deadlineOrderRefusal, permissionHooks } from '../gate/gate.js';
+import { SessionRegistry } from '../sessions/registry.js';
+import { SessionStateMachine } from '../state/machine.js';
+import { SessionObserver } from '../state/observer.js';
+import { keyPreview, unusableKeyProblem } from '../workspace/git-worktree.js';
+import { bulkOriginFor, postBulk } from './bulk-post.js';
+import { readWhere } from './git-facts.js';
+import { normalizePath } from '../core/paths.js';
+import { mergeHooks, observationHooks } from './hooks.js';
+import { createToolServer } from './mcp-server.js';
+import { listTranscripts, tailTranscript } from './claude-transcripts.js';
+import { listRepositoryDirectory, readRepositoryFile } from './repository-read.js';
+import { nodePathResolver } from './paths.js';
+import { isBypassMode, mergeMcpServers, readSessionConfigure, readSessionRequest } from './wire-request.js';
+import { isDroppable } from '../control/frames.js';
+/**
+ * Assemble one session: machine, observer, gate and forwarding, then start it.
+ *
+ * This is the wiring every consumer needs, written down where it can be used.
+ */
+export function composeSession(options) {
+    // The one combination this function will not assemble, and this is the only place that can see
+    // it: the gate knows whether it grants and the request knows which settings tiers load, and
+    // neither knows the other. Refused before any process exists, by name, rather than resolved by a
+    // precedence that would surprise one of them.
+    //
+    // The ground for the refusal is narrow. Per the documented permission rules, deny and ask are
+    // evaluated whatever a hook returns, so a grant skips only mode, allow rules and `canUseTool`; an
+    // effective allow does not short-circuit every later permission check. The refusal stands on the
+    // narrower ground that the two mechanisms answer the same question from different places, and a
+    // session that both grants and loads operator rules has two authorities with no stated
+    // precedence. See `gate.ts` for the full order and for why the claim is documented rather than
+    // measured.
+    //
+    // And `settingSources: []` does not mean "no operator rules live". Managed policy settings and
+    // `~/.claude.json` load regardless of this field, precisely on the managed corporate laptop this
+    // package's threat model is written for. So this refusal is incomplete on its own logic: it
+    // catches the tiers named here and cannot see the two that are always on.
+    const settingSources = options.request?.settingSources ?? [];
+    // The pair is refused, except under bypassPermissions. What the grant skips is "permission
+    // mode, allow rules and canUseTool"; under bypass the mode already allows all of that, so the
+    // grant changes nothing and there is no second authority to shadow. A hook deny survives every
+    // mode, so the gate's boundary set still holds. The precedence is therefore stated by the mode
+    // itself: the operator asked for bypass, and got exactly the CLI's bypass plus this gate's
+    // refusals. Every other mode keeps the refusal below, unchanged.
+    if ((options.gate?.grantOnAllow ?? false) &&
+        settingSources.length > 0 &&
+        !isBypassMode(options.request?.permissionMode)) {
+        return refuse('permission-grant-shadows-settings', `grantOnAllow makes this gate's allow effective, and this session also loads operator settings ` +
+            `(${settingSources.join(', ')}) — two authorities over the same call with no stated ` +
+            `precedence. Per the SDK's documented evaluation order a hook allow does NOT skip deny or ` +
+            `ask rules, so those survive the grant; what it skips is permission mode, allow rules and ` +
+            `canUseTool. Load no settings, do not grant, or run bypassPermissions — where the grant ` +
+            `changes nothing because the mode already allows what it would. Note that managed policy and ` +
+            `~/.claude.json load regardless of settingSources, so an empty list is not proof that no ` +
+            `operator rule is live.`);
+    }
+    // The second combination this function will not assemble. `permissionHooks` throws when the
+    // host's own deadline does not expire before the matcher's, and that throw is right: the pair is
+    // checkable, the failure it prevents is a block nobody can explain, and an embedder calling
+    // `permissionHooks` directly should meet it loudly. But gate timings ride `session_new`, so a
+    // controller can send the pair, and a throw from here would escape the payload dispatcher's
+    // `void this.#open(…)` as an unhandled rejection, which means the controller gets no answer at
+    // all. A command that vanishes reads as a host that hung, which is precisely what refusing every
+    // unknown payload by name exists to prevent. Caught here rather than by relaxing the throw: the
+    // check keeps its teeth, and the composer keeps its contract of returning a Result for
+    // everything it declines to build.
+    const inverted = deadlineOrderRefusal(options.gate?.decisionTimeoutMs, options.gate?.matcherTimeoutSeconds);
+    if (inverted !== null)
+        return refuse('gate-deadlines-inverted', inverted);
+    const clock = options.clock ?? systemClock;
+    const ticker = options.ticker ?? systemTicker;
+    const machine = new SessionStateMachine({
+        where: options.where ?? unknownWhere(options.cwd),
+        clock,
+        ticker,
+        correlationId: options.correlationId ?? null,
+    });
+    const observer = new SessionObserver(machine);
+    // The gate records every outcome on the machine. That emission is what makes a deny, an outage and
+    // an expiry visible off-box at all, so it is unconditional and the embedder's listener is extra.
+    const gate = permissionHooks({
+        decide: options.decide,
+        // The escalation body carries the controller's handle. This function is the one place that
+        // holds both the handle and the gate, so it is where the two transports are tied together.
+        sessionKey: options.sessionKey,
+        onOutcome: (outcome) => {
+            recordGateOutcome(machine, outcome);
+            options.onOutcome?.(outcome);
+        },
+        ...(options.localGate === undefined ? {} : { localGate: options.localGate }),
+        ...(options.gate?.decisionTimeoutMs === undefined
+            ? {}
+            : { decisionTimeoutMs: options.gate.decisionTimeoutMs }),
+        ...(options.gate?.holdAfterMs === undefined ? {} : { holdAfterMs: options.gate.holdAfterMs }),
+        ...(options.gate?.matcherTimeoutSeconds === undefined
+            ? {}
+            : { matcherTimeoutSeconds: options.gate.matcherTimeoutSeconds }),
+        ...(options.gate?.grantOnAllow === undefined ? {} : { grantOnAllow: options.gate.grantOnAllow }),
+        // The `gate-cannot-grant` residual reaches the same lane every other named degrade uses, so an
+        // embedder who already subscribes to refusals learns about it without opting in to anything new.
+        ...(options.onRefusal === undefined
+            ? {}
+            : {
+                onDegrade: (degrade) => options.onRefusal?.(refusal(degrade.name, degrade.detail)),
+            }),
+    });
+    // Observation first, the gate second. The order is a convention rather than a race guard (see
+    // permissionHooks' own note), but it is the one both files state, so it is written once here.
+    const hooks = mergeHooks(observationHooks({
+        observer,
+        ...(options.onHookFailure === undefined ? {} : { onHandlerFailure: options.onHookFailure }),
+    }), gate);
+    const created = options.registry.create({ ...(options.request ?? {}), cwd: options.cwd, hooks });
+    if (!created.ok)
+        return refuse(created.refusal.reason, created.refusal.detail);
+    const session = created.value;
+    // Before the first record. See this file's header: the forwarder subscribes to the machine, so
+    // anything recorded ahead of this line is emitted to nobody.
+    const detach = forwardSession({
+        sessionKey: options.sessionKey,
+        session,
+        observer,
+        sink: options.sink,
+        ...(options.onRefusal === undefined ? {} : { onRefusal: options.onRefusal }),
+    });
+    observer.created(`a session was requested in ${options.cwd}`);
+    return ok({ sessionKey: options.sessionKey, session, machine, observer, detach });
+}
+/**
+ * The `where` for a directory nobody has read git facts for.
+ *
+ * Stated rather than left null: a transition whose `where` is absent cannot be told apart from one
+ * whose repository could not be determined, and only the second is a fact worth reporting.
+ */
+function unknownWhere(cwd) {
+    return { cwd, worktree: null, branch: null, unknownReason: 'the repository was not read for this session' };
+}
+/**
+ * A controller's per-session timings, as a partial the composer can spread.
+ *
+ * Absent keys rather than nulls: `GateTimings` reads an absent key as "use the default", and a
+ * present `undefined` would spread over a value the embedder deliberately set. The difference is
+ * invisible until an embedder configures a timeout and a controller sends `gate: {…, holdAfterMs:
+ * null}` — at which point the embedder's value either survives or silently does not.
+ *
+ * Nothing validates the pair here, deliberately. `permissionHooks` throws at construction when the
+ * host's own deadline does not expire before the matcher's, and that check must stay the only one:
+ * a second copy of the rule is a second thing to keep in step. The throw surfaces as a refused
+ * composition before any process exists, which is where a controller wants to learn it.
+ */
+function readGateTimings(gate) {
+    if (gate === null)
+        return {};
+    return {
+        ...(gate.decisionTimeoutMs === null ? {} : { decisionTimeoutMs: gate.decisionTimeoutMs }),
+        ...(gate.holdAfterMs === null ? {} : { holdAfterMs: gate.holdAfterMs }),
+        ...(gate.matcherTimeoutSeconds === null ? {} : { matcherTimeoutSeconds: gate.matcherTimeoutSeconds }),
+    };
+}
+/**
+ * How many turns may wait for one still-opening session before the rest are refused.
+ *
+ * The bound exists because the buffer is fed from the wire, not because anyone expects to reach it:
+ * a controller sends one seed per `session_new`, so the ordinary depth is 1. An unbounded per-handle
+ * buffer that a peer can grow is the shape this package refuses everywhere else, and the window it
+ * lives in is exactly as long as a workspace provider takes, which is seconds, not microseconds, and
+ * is the whole reason this queue exists.
+ */
+const MAX_HELD_TURNS = 8;
+/**
+ * A host: one outbound link, one registry, and the dispatcher between them.
+ *
+ * It interprets exactly the payload kinds its `#dispatch` switch names and refuses the rest by
+ * name: the session commands (`session_new`, `session_prompt`, `session_cancel`,
+ * `session_configure`), `bulk_request`, and the host-scoped asks (the discovery, workspace,
+ * configure and repository asks). Derive the count from the switch below; never carry it from
+ * prose. Anything else arriving inbound is
+ * either a frame this host produces (an update, a delta, a receipt) or a kind a newer controller
+ * invented, and both are reported rather than ignored; a command that vanishes reads to the
+ * controller as a host that hung.
+ */
+export class PeriscopeHost {
+    #options;
+    #link;
+    #registry;
+    /** Keyed by the controller's handle, which is the only id present when `session_new` arrives. */
+    #sessions = new Map();
+    /**
+     * Handles whose open is still in flight. `#open` awaits the workspace provider before it can
+     * populate `#sessions`, so the map alone cannot make the duplicate guard hold across that await;
+     * the reservation is taken synchronously and released in the same call, whatever the outcome.
+     */
+    #opening = new Set();
+    /**
+     * regression: an undroppable frame the link's queue refused at capacity — a turn-end transition, a
+     * result — was reported here and dropped, so the controller never learned the turn ended and the
+     * session read as still working until its next turn. The queue's refusal is backpressure; the
+     * caller has to hold the frame and offer it again. Held per session, in order; while a session holds
+     * frames its later undroppable frames queue behind them, so the controller sees the session's order.
+     */
+    #heldFrames = new Map();
+    #heldFramesTimer = null;
+    /**
+     * Turns that arrived while their session was still opening, in order.
+     *
+     * A controller sends `session_new` then `session_prompt`, and that ordering is real on the wire,
+     * but a send returning Ok means written to the socket, not accepted, because the host
+     * acknowledges no controller frame (the reason `OutboundRetention` exists). Here the open is
+     * asynchronous: it awaits the workspace provider, and a real `GitWorktreeProvider` is a
+     * `git worktree add`, which takes seconds (measured at 13 s once). A seed landing in that window
+     * would be refused `session-unknown`, and the session would then open and sit idle forever.
+     * Nothing downstream could say why: a born session with no first turn looks exactly like a slow
+     * one.
+     *
+     * With `PlainDirProvider` (a `mkdir`) the window never opens, so only the git provider, which
+     * is what a session needs in order to commit or push at all, exposes this.
+     *
+     * The invariant, and it is the whole point: a held turn is answered, never dropped. Delivered
+     * when the session opens (`#compose`), refused if the open failed (`#open`'s `finally`, which runs
+     * on every path including a throw), or withdrawn because the controller cancelled it (`#withdraw`).
+     * Three exits, all of them reported. A queue that silently discarded on any one of them would be
+     * the same defect wearing a fix's clothes.
+     *
+     * It is deliberately not consulted for a handle this host has never heard of. `session-unknown`
+     * stays the honest, immediate answer for an id that does not exist and never will; retrying that
+     * is futile and `core/refusal.ts` says so. Only a handle already reserved in `#opening` can hold.
+     */
+    #held = new Map();
+    /**
+     * Which workspace key each live-or-opening session provisioned at (protocol v5).
+     *
+     * Two consumers, and both exist because keys can alias. The release sites read it so a session
+     * provisioned at a shared key releases that key rather than its own session key; without it,
+     * `provision('shared-1')` paired with `release(sessionKey)` would leak the claim on every
+     * aliased session. And the reap's in-use guard scans its values: N sessions can share one key,
+     * each holding its own entry here, so "is this key in use" stays true until the last of them
+     * closes; a single-mapping guard would clear on the first close and let a reap delete a tree
+     * other sessions are still working in.
+     *
+     * Written synchronously before the provision await (so an opening session already guards its
+     * key); cleared in `#open`'s finally when the open produced no session, and in `#close`.
+     */
+    #workspaceKeyFor = new Map();
+    /**
+     * Every provider call rides a per-key turn. `#dispatch` never awaits a handler, and the work
+     * behind these verbs is seconds long and mutually destructive on one key: a `git worktree add`
+     * measured at 13 to 18 s, a `git worktree remove --force` the same order. The reachable
+     * interleavings: a `session_new` provisioning into a directory the reap is mid-deleting (the
+     * in-use scan happened before the multi-second await), and a reap starting inside `#close`'s
+     * window (the map entry is deleted before its release settles). One serial queue per key closes
+     * every direction at the only chokepoint all three verbs share; keys that differ never wait on
+     * each other.
+     */
+    #workspaceTurns = new KeyedTurns();
+    /**
+     * The pieces a `host_configure` may replace, held apart from the frozen options so a reconfigure
+     * swaps them in one place and every handler reads the current one. Initialised from the options.
+     */
+    #workspaces;
+    #transcriptsRoot;
+    #bulk;
+    #linkCapabilities;
+    #configuration;
+    #overriddenByEnvironment;
+    #pendingRestart;
+    constructor(options) {
+        this.#options = options;
+        this.#workspaces = options.workspaces;
+        this.#transcriptsRoot = options.transcriptsRoot;
+        this.#bulk = options.bulk;
+        this.#linkCapabilities = options.linkCapabilities ?? [];
+        this.#configuration = options.configuration ?? unsetHostConfiguration();
+        this.#overriddenByEnvironment = options.overriddenByEnvironment ?? [];
+        this.#pendingRestart = options.pendingRestart ?? [];
+        if (options.registry !== undefined && (options.baseEnv !== undefined || options.homeDir !== undefined)) {
+            // A registry carries its own environment and home; a second pair beside it would be read by
+            // nothing, and an embedder who passed both would believe the pair was in effect.
+            throw new Error('PeriscopeHostOptions: baseEnv and homeDir are ignored when a registry is supplied; pass them to the registry');
+        }
+        this.#registry =
+            options.registry ??
+                new SessionRegistry({
+                    baseEnv: options.baseEnv ?? {},
+                    homeDir: options.homeDir ?? '',
+                    ...(options.clock === undefined ? {} : { clock: options.clock }),
+                });
+        const handlers = {
+            onTransition: (transition) => this.#report({ kind: 'link', transition }),
+            onSessionFrame: (frame) => this.#dispatch(frame),
+            onGap: (sessionKey, expected, received) => this.#report({ kind: 'gap', sessionKey, expected, received }),
+            onRefusal: (refused) => this.#report({ kind: 'refusal', refusal: refused, sessionKey: null }),
+        };
+        this.#link =
+            options.link?.(handlers) ??
+                new ControllerLink({
+                    url: options.controllerUrl,
+                    hostId: options.hostId,
+                    handlers,
+                    ...(options.credential === undefined ? {} : { credential: options.credential }),
+                    ...(options.backoff === undefined ? {} : { backoff: options.backoff }),
+                    ...(options.clock === undefined ? {} : { clock: options.clock }),
+                    ...(options.ticker === undefined ? {} : { ticker: options.ticker }),
+                    ...(options.linkCapabilities === undefined ? {} : { capabilities: options.linkCapabilities }),
+                    ...(options.configuration === undefined ? {} : { configuration: options.configuration }),
+                    ...(options.pendingRestart === undefined ? {} : { pendingRestart: options.pendingRestart }),
+                    ...(options.linkTimings?.heartbeatIntervalMs === undefined
+                        ? {}
+                        : { heartbeatIntervalMs: options.linkTimings.heartbeatIntervalMs }),
+                    ...(options.linkTimings?.heartbeatTimeoutMs === undefined
+                        ? {}
+                        : { heartbeatTimeoutMs: options.linkTimings.heartbeatTimeoutMs }),
+                    ...(options.linkTimings?.connectTimeoutMs === undefined
+                        ? {}
+                        : { connectTimeoutMs: options.linkTimings.connectTimeoutMs }),
+                });
+    }
+    get link() {
+        return this.#link;
+    }
+    get registry() {
+        return this.#registry;
+    }
+    /** The composed session behind a controller handle, or a refusal naming the handle. */
+    session(sessionKey) {
+        const composed = this.#sessions.get(sessionKey);
+        if (composed === undefined) {
+            return refuse('session-unknown', `no session for controller handle ${sessionKey}`);
+        }
+        return ok(composed);
+    }
+    start() {
+        this.#link.start();
+    }
+    /** Ends every session first, then the link — so the end transitions still have somewhere to go. */
+    stop(detail = 'host shutting down') {
+        if (this.#heldFramesTimer !== null) {
+            clearTimeout(this.#heldFramesTimer);
+            this.#heldFramesTimer = null;
+        }
+        for (const composed of [...this.#sessions.values()])
+            composed.session.stop(detail);
+        this.#registry.stopAll(detail);
+        this.#link.stop(detail);
+    }
+    // -------------------------------------------------------------------------
+    #dispatch(frame) {
+        const payload = frame.payload;
+        switch (payload.kind) {
+            case 'session_new':
+                void this.#open(frame.sessionId, payload);
+                return;
+            case 'session_prompt': {
+                // A turn for a session whose open is still in flight waits for it rather than being refused.
+                // The reservation it tests is the one `#open` already takes; see `#held`.
+                if (!this.#sessions.has(frame.sessionId) && this.#opening.has(frame.sessionId)) {
+                    return this.#hold(frame.sessionId, payload.text);
+                }
+                const composed = this.session(frame.sessionId);
+                if (!composed.ok)
+                    return this.#refuse(frame.sessionId, composed.refusal);
+                return this.#prompt(frame.sessionId, composed.value, payload.text);
+            }
+            case 'session_cancel': {
+                // The same race, the other frame. A cancel arriving while the session is still opening
+                // stops the turn that is waiting, the only turn that can exist yet. It does not stop the
+                // open: `session_cancel` ends a turn, never a session, and that contract is pinned.
+                if (!this.#sessions.has(frame.sessionId) && this.#opening.has(frame.sessionId)) {
+                    return this.#withdraw(frame.sessionId);
+                }
+                const composed = this.session(frame.sessionId);
+                if (!composed.ok)
+                    return this.#refuse(frame.sessionId, composed.refusal);
+                composed.value.observer.interrupted('the controller cancelled the turn');
+                void composed.value.session.interrupt().catch((error) => {
+                    this.#refuse(frame.sessionId, refusal('session-unknown', `the interrupt failed: ${describe(error)}`));
+                });
+                return;
+            }
+            case 'session_configure': {
+                // Protocol v6: the SDK's live setters. A session still opening has no query to configure yet; the
+                // controller is told so by name rather than left to assume the change landed.
+                const composed = this.session(frame.sessionId);
+                if (!composed.ok)
+                    return this.#refuse(frame.sessionId, composed.refusal);
+                const change = readSessionConfigure(payload);
+                if (!change.ok)
+                    return this.#refuse(frame.sessionId, change.refusal);
+                void composed.value.session.configure(change.value).catch((error) => {
+                    this.#refuse(frame.sessionId, refusal('session-unknown', `the configure failed: ${describe(error)}`));
+                });
+                return;
+            }
+            case 'bulk_request':
+                void this.#deliver(frame.sessionId, payload.deliveryId, payload.what, payload.postUrl, payload.fromOffset);
+                return;
+            // The discovery requests are host-scoped, not session-scoped. The routing key on these
+            // frames is a channel the controller chose; no session needs to exist behind it, so none of
+            // the session-existence machinery above applies. The answer rides back on the same key.
+            case 'session_list':
+                return this.#answerSessionList(frame.sessionId, payload);
+            case 'transcript_list':
+                void this.#answerTranscriptList(frame.sessionId, payload);
+                return;
+            case 'transcript_tail':
+                void this.#answerTranscriptTail(frame.sessionId, payload);
+                return;
+            case 'workspace_release':
+                void this.#answerWorkspaceRelease(frame.sessionId, payload);
+                return;
+            case 'workspace_release_bulk':
+                void this.#answerWorkspaceReleaseBulk(frame.sessionId, payload);
+                return;
+            case 'host_configure':
+                return this.#answerHostConfigure(frame.sessionId, payload);
+            case 'workspace_list':
+                void this.#answerWorkspaceList(frame.sessionId, payload);
+                return;
+            case 'repository_list':
+                void this.#answerRepositoryList(frame.sessionId, payload);
+                return;
+            case 'repository_read':
+                void this.#answerRepositoryRead(frame.sessionId, payload);
+                return;
+            default:
+                // A kind this host produces, or one a newer controller invented. Named either way.
+                this.#refuse(frame.sessionId, refusal('frame-malformed', `this host takes no inbound "${payload.kind}" — it is not a command`));
+                return;
+        }
+    }
+    /**
+     * Send one turn at a live session and record that it happened.
+     *
+     * One path for both arrivals. A turn that waited and a turn that walked straight in must reach the
+     * agent identically and leave the same trace, or "it was queued" would become a second, quieter
+     * grade of delivery that nothing downstream could tell apart from the first.
+     */
+    #prompt(sessionKey, composed, text) {
+        const sent = composed.session.prompt(text);
+        if (!sent.ok)
+            return this.#refuse(sessionKey, sent.refusal);
+        composed.observer.promptSubmitted('the controller sent a turn');
+    }
+    /** Hold a turn for a session still opening, or refuse it when the bound is already reached. */
+    #hold(sessionKey, text) {
+        const waiting = this.#held.get(sessionKey) ?? [];
+        if (waiting.length >= MAX_HELD_TURNS) {
+            // Named rather than dropped, and `session-unknown` rather than a new reason: from the sender's
+            // side this handle still holds no session, and the vocabulary in `core/refusal.ts` is closed on
+            // purpose; a reason minted for one call site is one nobody else can branch on.
+            return this.#refuse(sessionKey, refusal('session-unknown', `${MAX_HELD_TURNS} turns are already waiting for ${sessionKey} to open — this one was not taken`));
+        }
+        waiting.push(text);
+        this.#held.set(sessionKey, waiting);
+        this.#report({ kind: 'prompt-held', sessionKey, held: waiting.length });
+    }
+    /** Every held turn, in arrival order, the moment the session exists. */
+    #drain(sessionKey, composed) {
+        const waiting = this.#held.get(sessionKey);
+        if (waiting === undefined)
+            return;
+        this.#held.delete(sessionKey);
+        for (const text of waiting)
+            this.#prompt(sessionKey, composed, text);
+        this.#report({ kind: 'prompt-delivered', sessionKey, delivered: waiting.length });
+    }
+    /**
+     * The controller withdrew the turns it was waiting on. The third answer, and the only one the
+     * sender asked for.
+     *
+     * It is reported rather than silent, which is what keeps it inside the invariant instead of
+     * being the exception that swallows it: a withdrawn turn and a dropped one are the same absence on
+     * the wire, and only one of them is something to investigate.
+     *
+     * The limit: no session exists yet, so there is no machine to record an `interrupted`
+     * transition on; this is reported by the host, not by the session's own state log. A cancel that
+     * lands after the open takes the ordinary path and is recorded there.
+     */
+    #withdraw(sessionKey) {
+        const waiting = this.#held.get(sessionKey) ?? [];
+        this.#held.delete(sessionKey);
+        this.#report({ kind: 'prompt-withdrawn', sessionKey, withdrawn: waiting.length });
+    }
+    /**
+     * The open ended without a session: every turn still waiting is refused, one refusal each.
+     *
+     * This is the half that keeps the queue honest. Holding a turn is a promise to answer it, and the
+     * only failure worse than refusing a turn that could have been served is accepting one and saying
+     * nothing, which is the defect this whole queue exists to end, relocated one layer in.
+     */
+    #abandon(sessionKey) {
+        const waiting = this.#held.get(sessionKey);
+        if (waiting === undefined)
+            return;
+        this.#held.delete(sessionKey);
+        for (const _text of waiting) {
+            this.#refuse(sessionKey, refusal('session-unknown', `${sessionKey} never opened, so a turn held for it cannot be delivered`));
+        }
+    }
+    async #open(sessionKey, opening) {
+        if (this.#sessions.has(sessionKey) || this.#opening.has(sessionKey)) {
+            // Two `session_new` for one handle: the second must not silently replace the first, which
+            // would leave a live agent running with nothing routed to it. The `#opening` half of the
+            // check is what makes this hold for two frames in flight: with a workspace provider
+            // configured there is an await between here and the map write, and a guard that reads only
+            // the map lets both frames through it: double spawn, one leaked agent, one handle.
+            return this.#refuse(sessionKey, refusal('session-unknown', `${sessionKey} is already a live or opening session here`));
+        }
+        this.#opening.add(sessionKey);
+        try {
+            await this.#compose(sessionKey, opening);
+        }
+        catch (error) {
+            // Every exit from an open is a wire answer. The dispatcher calls this as
+            // `void this.#open(…)`, so without this catch a throw anywhere in `#compose` would become an
+            // unhandled rejection: the controller gets nothing at all, its record of the session reads
+            // `open` forever, and on a host with no unhandledRejection handler the process could die
+            // outright. A command that vanishes reads as a host that hung, the exact failure refusing
+            // every unknown payload by name exists to prevent, arriving through the one door that was not
+            // refusing.
+            //
+            // Caught here rather than at each throw site, deliberately. Guarding a named list of throw
+            // sources leaves the next one unguarded; this arm cannot be outrun by a source nobody has
+            // written yet.
+            //
+            // The `finally` below still runs for the queue: held turns are answered by `#abandon`, so a
+            // throw during an open does not silently strand the turns waiting on it.
+            this.#refuseOpen(sessionKey, null, refusal('session-spawn-failed', `opening ${sessionKey} threw rather than returning a refusal: ${describe(error)}`));
+        }
+        finally {
+            this.#opening.delete(sessionKey);
+            // A successful open drained and cleared the queue already, so this finds nothing. Anything still
+            // here means the open did not produce a session (a refused request, a failed provision, a
+            // `giveBack`, or a throw) and each waiting turn is answered rather than forgotten. It sits in
+            // `finally` so no failure path can skip it, including one nobody has written yet.
+            this.#abandon(sessionKey);
+            // An open that produced no session holds no workspace claim, so its key entry goes too: in
+            // `finally` for the same reason as the queue, and guarded so a successful open keeps the
+            // entry the release sites and the in-use guard read for the session's whole life.
+            if (!this.#sessions.has(sessionKey))
+                this.#workspaceKeyFor.delete(sessionKey);
+        }
+    }
+    async #compose(sessionKey, opening) {
+        // Narrowed before the workspace is claimed, and the order is the point. A request this host
+        // cannot use is refused while it still owns nothing: provisioning first would take a directory,
+        // find the request unusable, and have to hand it back, a claim/release round trip on every
+        // malformed frame, in the one path a stranger can drive.
+        const requested = readSessionRequest(opening.request);
+        if (!requested.ok)
+            return this.#refuseOpen(sessionKey, null, requested.refusal);
+        const provider = this.#workspaces;
+        // Where the workspace key resolves: each `??` is a default for an absence, never an
+        // override, so a controller that names a key never has the host's configured default consulted.
+        // Validated before the workspace is claimed, same order and same reason as the request
+        // narrowing above: a key this host cannot use must refuse while it still owns nothing.
+        const askedKey = opening.workspaceKey ?? this.#options.defaultWorkspaceKey ?? null;
+        if (askedKey !== null) {
+            const source = opening.workspaceKey !== null
+                ? 'session_new.workspaceKey'
+                : "this host's configured default workspace key";
+            if (provider === undefined) {
+                // The `path-input-missing` posture's mirror image: with no provider there is nothing to
+                // provision at any key, and running in the controller's cwd instead would deliver the
+                // wrong topology silently, the exact failure an explicit key exists to end.
+                return this.#refuseOpen(sessionKey, null, refusal('workspace-provision-failed', `${source} names ${askedKey} and this host has no workspace provider — there is nothing to provision at that key, so the ask cannot be honoured`));
+            }
+            const problem = unusableKeyProblem(askedKey);
+            if (problem !== null) {
+                // An unusable key is refused by the host's own guard with the field named, never left to
+                // die inside git as an unnamed provision failure.
+                // `keyPreview`, never the raw key: an over-length key's refusal must itself stay sendable.
+                return this.#refuseOpen(sessionKey, null, refusal('workspace-provision-failed', `${source} ${keyPreview(askedKey)} ${problem}`));
+            }
+        }
+        const workspaceKey = askedKey ?? sessionKey;
+        let cwd = opening.cwd;
+        // The provider decides, except for the repository it clones from. A named cwd is advisory
+        // under a provider, with one exception: the provider's own repository root, the operator's
+        // checkout, trusted in their ~/.claude.json, where the CLI they know runs and every settings
+        // tier loads. There is no isolation to protect when the operator asks for the source itself,
+        // and no worktree could be more "the repo" than the repo. Any other named directory still gets
+        // a provisioned workspace. The workspace guard's root follows the cwd either way; the
+        // operator's checkout claims no workspace key, so the reap never touches it.
+        const operatorsCheckout = provider !== undefined &&
+            cwd !== null &&
+            provider.repositoryRoot !== undefined &&
+            normalizePath(cwd).toLowerCase() === normalizePath(provider.repositoryRoot).toLowerCase();
+        // A resume runs where its transcript lives, or not at all. The CLI keeps transcripts per cwd;
+        // a resume moved into a provisioned workspace finds nothing and becomes a fresh session that
+        // says nothing. A named cwd the provider would not honour is therefore refused by name, on the
+        // wire, instead of being quietly overruled.
+        if (provider !== undefined && !operatorsCheckout && cwd !== null && opening.request?.resume) {
+            return this.#refuseOpen(sessionKey, null, refusal('resume-cwd-not-honoured', `the resume names ${cwd}, but this host provisions workspaces and honours only its own repository root (${provider.repositoryRoot ?? 'none configured'}) — the transcript would not be found anywhere else, so the session is not started`));
+        }
+        let claimed = false;
+        if (provider !== undefined && !operatorsCheckout) {
+            // Before the await, so the reap's in-use guard already covers a session whose open is still
+            // in flight. `#open`'s finally clears it again when the open produced no session.
+            this.#workspaceKeyFor.set(sessionKey, workspaceKey);
+            // The turn, not a bare await: a provision arriving while this key's reap (or a closing
+            // session's release) is still running waits for it to settle instead of racing the removal.
+            const provisioned = await this.#workspaceTurns.run(workspaceKey, () => provider.provision(workspaceKey));
+            if (!provisioned.ok)
+                return this.#refuseOpen(sessionKey, null, provisioned.refusal);
+            cwd = provisioned.value.path;
+            claimed = true;
+        }
+        else if (cwd === null) {
+            // A null cwd is "the provider decides", and this host has no provider, so there is no
+            // decider and nowhere honest to fall back to. Not `process.cwd()`: sharing the host's own
+            // directory is the weakest isolation `bin/workspaces.ts` knows, and it is a posture an embedder
+            // chooses, never one a frame's absence smuggles in. Refused before anything is claimed, with
+            // the same name a path-taking tool uses for a pathless input.
+            return this.#refuseOpen(sessionKey, null, refusal('path-input-missing', 'session_new carries cwd: null and this host has no workspace provider — there is no decider to defer to, so the session has nowhere to run'));
+        }
+        // A workspace this host asked for and then could not use is handed back, on every failure path
+        // below. The provider's default is to leave the directory alone, so this is a release of the
+        // claim rather than a deletion, but a host that never releases makes `provision` and `release`
+        // unbalanced, and a provider counting sessions would leak one per refused start.
+        const giveBack = async (refused) => {
+            this.#refuseOpen(sessionKey, cwd, refused);
+            if (!claimed || provider === undefined)
+                return;
+            // The claim was taken at the workspace key, so it is handed back at the workspace key;
+            // releasing the session key here would release nothing the moment keys alias.
+            const released = await provider.release(workspaceKey);
+            if (!released.ok)
+                this.#refuse(sessionKey, released.refusal);
+        };
+        const tools = this.#toolServer(sessionKey);
+        if (!tools.ok)
+            return giveBack(tools.refusal);
+        // The one throw source in this function, named. `readWhere` walks up from `cwd` looking for
+        // a `.git`, so it touches the filesystem with a path the controller chose: a malformed `cwd`
+        // (an illegal segment, a path the OS refuses to stat) throws out of here rather than
+        // returning. The catch in `#open` would turn that into a refusal anyway; this exists so the
+        // refusal says where, instead of naming the whole open.
+        //
+        // Its two neighbours are not throw sources and are not guarded: `localGate({…})` builds a
+        // closure and touches nothing at construction, and `nodePathResolver` is only stored here; its
+        // one throw fires later, inside the gate's decide path, which is a different surface with a
+        // different answer.
+        let where;
+        try {
+            where = readWhere(cwd);
+        }
+        catch (error) {
+            return giveBack(refusal('session-spawn-failed', `reading git facts for ${cwd} threw, so this session has no honest 'where': ${describe(error)}`));
+        }
+        const servers = mergeMcpServers(requested.value.mcpServers, tools.value);
+        if (!servers.ok)
+            return giveBack(servers.refusal);
+        const composed = composeSession({
+            registry: this.#registry,
+            sessionKey,
+            cwd,
+            sink: this.#link,
+            decide: this.#options.decide,
+            // Jailed to its own workspace by default, and the default is the whole point: a host whose
+            // local gate is opt-in is a host most embedders run without one.
+            localGate: localGate({
+                workspaceRoot: cwd,
+                resolve: nodePathResolver,
+                protectedPaths: this.#options.protectedPaths,
+                ...(this.#options.toolFamilies === undefined ? {} : { toolFamilies: this.#options.toolFamilies }),
+            }),
+            where,
+            // The controller's own handle when it sent one, the routing key otherwise. The key stays the
+            // fallback rather than null: a transition with no correlation at all is strictly less useful
+            // than one correlated to the handle the controller is already using. The two are still
+            // different contracts (one is interpreted by construction, the other never) and nothing here
+            // derives one from the other in the direction that would matter.
+            correlationId: opening.correlationId ?? sessionKey,
+            // This host grants what its gate approves, and that is a posture rather than an inherited
+            // default. It loads no settings files, so nothing sits behind the gate that a grant could
+            // override, and without it the gate would be a veto: able to refuse a call, unable to let one
+            // through. An embedder who wants the silent-allow posture sets `grantOnAllow: false` and gets
+            // a host whose agent cannot run a tool, which is a legitimate thing to want and a surprising
+            // thing to get by accident. Recorded in SECURITY.md, not only here.
+            // Three layers, and the order is a decision. The host's posture is the floor, the embedder's
+            // configuration overrides it, and the controller's per-session timings win last, because a
+            // timing is a statement about how long that controller is willing to wait, and it is the only
+            // party that knows. `grantOnAllow` is deliberately not reachable from the wire and so cannot be
+            // overridden by the last spread; see `SessionNewGate`.
+            gate: { grantOnAllow: true, ...(this.#options.gate ?? {}), ...readGateTimings(opening.gate) },
+            request: { ...requested.value, ...(servers.value === null ? {} : { mcpServers: servers.value }) },
+            ...(this.#options.clock === undefined ? {} : { clock: this.#options.clock }),
+            ...(this.#options.ticker === undefined ? {} : { ticker: this.#options.ticker }),
+            onRefusal: (refused) => this.#refuse(sessionKey, refused),
+            onHookFailure: (failure) => this.#refuse(sessionKey, refusal('transition-cause-unnamed', `a ${failure.event} handler threw: ${describe(failure.error)}`)),
+        });
+        if (!composed.ok)
+            return giveBack(composed.refusal);
+        this.#sessions.set(sessionKey, composed.value);
+        composed.value.machine.onTransition((transition) => this.#report({ kind: 'transition', sessionKey, transition }));
+        composed.value.session.onEnd(() => this.#close(sessionKey));
+        // `onDegrade` replays what was raised before this line ran, which is what makes the
+        // create-time degrades (an untrusted workspace is reported during `create()`) reachable at
+        // all; the collision degrade arrives live later, when the agent reports an id already held.
+        composed.value.session.onDegrade((degrade) => this.#report({ kind: 'degrade', sessionKey, degrade }));
+        this.#report({ kind: 'session-opened', sessionKey, cwd });
+        // After the open is reported, so the trace reads in causal order: held, opened, delivered. The
+        // gap between the first and the last is the provisioning window, stated rather than inferred.
+        this.#drain(sessionKey, composed.value);
+    }
+    /**
+     * Everything a finished session holds, released in the order that keeps its last frames.
+     *
+     * `forgetSession` deliberately does not discard unacked frames: a session's final transitions are
+     * its most important and are exactly the ones still in flight if the link is down when it ends.
+     */
+    #close(sessionKey) {
+        const composed = this.#sessions.get(sessionKey);
+        if (composed === undefined)
+            return;
+        this.#sessions.delete(sessionKey);
+        composed.detach();
+        this.#link.forgetSession(sessionKey);
+        // Released at the key the workspace was provisioned at: for an aliased session the two
+        // differ, and releasing the session key would leak the claim. Deleted from the map first so
+        // the in-use guard stops counting this session the moment it is gone.
+        const workspaceKey = this.#workspaceKeyFor.get(sessionKey) ?? sessionKey;
+        this.#workspaceKeyFor.delete(sessionKey);
+        const provider = this.#workspaces;
+        // The release rides the key's turn: the map entry above is gone synchronously, so a reap
+        // arriving now already sees the key as free; serializing the release behind the same turn is
+        // what keeps that reap from removing the tree while this release still runs.
+        if (provider !== undefined) {
+            void this.#workspaceTurns
+                .run(workspaceKey, () => provider.release(workspaceKey))
+                .then((released) => {
+                if (!released.ok)
+                    this.#refuse(sessionKey, released.refusal);
+            }, 
+            // A provider that throws instead of returning a refusal must land in the same place: the
+            // named-refusal contract for a quiet release leak exists precisely because the failure is
+            // invisible until a disk fills, and an unhandled rejection here was the one path around it.
+            (error) => this.#refuse(sessionKey, refusal('workspace-release-failed', describe(error))));
+        }
+        this.#report({ kind: 'session-closed', sessionKey });
+    }
+    /**
+     * The in-process MCP server for a session, or null when this host offers no tools.
+     *
+     * The descriptors are the embedder's, not the controller's, and that is forced rather than
+     * chosen: no payload kind registers an in-process tool, so there is no way for a controller to
+     * declare one over the link. (A controller can name an HTTP or stdio MCP server through
+     * `session_new.request.mcpServers`; see `wire-request.ts`.)
+     */
+    #toolServer(sessionKey) {
+        const tools = this.#options.tools;
+        if (tools === undefined)
+            return ok(null);
+        const built = createToolServer({
+            ...tools,
+            // Read at call time, never captured: the agent has no id until its first turn is queued.
+            identity: () => ({ sessionId: this.#sessions.get(sessionKey)?.machine.sessionId ?? null }),
+        });
+        if (!built.ok) {
+            return refuse(built.refusal.reason, built.refusal.detail);
+        }
+        return ok({ [tools.name]: built.value });
+    }
+    /**
+     * Answer `session_list` from what this host holds: every handle it routes, plus the registry's
+     * two counts. Synchronous: no filesystem, no process, nothing to await.
+     */
+    #answerSessionList(channelKey, asked) {
+        const sessions = [...this.#sessions.entries()].map(([sessionKey, composed]) => ({
+            sessionKey,
+            sessionId: composed.session.id,
+            state: composed.session.state,
+            cwd: composed.machine.where.cwd,
+            startedAt: composed.session.facts?.startedAt ?? null,
+        }));
+        this.#send(channelKey, sessionListResult(asked.requestId, sessions, {
+            liveCount: this.#registry.liveCount,
+            provisioningCount: this.#registry.provisioningCount,
+        }));
+    }
+    /**
+     * Answer `transcript_list` from the discovery door, one page per request.
+     *
+     * Every exit sends a wire answer. A missing root, a failed walk and a thrown error all become a
+     * `transcript_failed` naming the reason; an answer that dies inside the host would read to the
+     * asker as a host that hung, which is the exact failure the closed dispatch set exists to end.
+     * (`#send` reports a send the link refused locally; the attempt is what every exit guarantees.)
+     */
+    async #answerTranscriptList(channelKey, asked) {
+        const root = this.#transcriptsRoot;
+        if (root === undefined) {
+            return this.#failDiscovery(channelKey, asked.requestId, refusal('path-input-missing', 'this host has no transcripts root configured — the discovery door cannot look'));
+        }
+        try {
+            const page = await listTranscripts(root, { fromIndex: asked.fromIndex });
+            this.#send(channelKey, transcriptListResult(asked.requestId, page.entries, {
+                totalCount: page.totalCount,
+                ...(page.nextIndex === null ? {} : { nextIndex: page.nextIndex }),
+            }));
+        }
+        catch (error) {
+            this.#failDiscovery(channelKey, asked.requestId, refusal('transcript-read-failed', describe(error)));
+        }
+    }
+    /** Answer `transcript_tail`. Same exit discipline as the listing: every path answers. */
+    async #answerTranscriptTail(channelKey, asked) {
+        const root = this.#transcriptsRoot;
+        if (root === undefined) {
+            return this.#failDiscovery(channelKey, asked.requestId, refusal('path-input-missing', 'this host has no transcripts root configured — the discovery door cannot look'));
+        }
+        try {
+            const answer = await tailTranscript(root, asked.projectSlug, asked.sessionId, {
+                fromOffset: asked.fromOffset,
+                needle: asked.needle,
+            });
+            if (!answer.ok)
+                return this.#failDiscovery(channelKey, asked.requestId, answer.refusal);
+            this.#send(channelKey, transcriptTailResult(asked.requestId, {
+                found: answer.value.found,
+                absent: answer.value.absent,
+                newOffset: answer.value.newOffset,
+                ...(answer.value.sizeBytes === null ? {} : { sizeBytes: answer.value.sizeBytes }),
+                ...(answer.value.mtimeMs === null ? {} : { mtimeMs: answer.value.mtimeMs }),
+            }));
+        }
+        catch (error) {
+            this.#failDiscovery(channelKey, asked.requestId, refusal('transcript-read-failed', describe(error)));
+        }
+    }
+    /**
+     * Answer `repository_list`: one directory of the repository this host provisions from,
+     * names only, jailed to the repository root by `listRepositoryDirectory`. Every exit is the one
+     * result kind; a host with no repository root has nothing to read under and says so by name.
+     */
+    async #answerRepositoryList(channelKey, asked) {
+        const refused = (why) => this.#refuseRepository(channelKey, repositoryListResult(asked.requestId, [], false, wireRefusalOf(why)), why);
+        const root = this.#workspaces?.repositoryRoot;
+        if (root === undefined)
+            return refused(noRepositoryRoot());
+        try {
+            const listed = await listRepositoryDirectory(root, asked.path, undefined, this.#options.protectedPaths);
+            if (!listed.ok)
+                return refused(listed.refusal);
+            this.#send(channelKey, repositoryListResult(asked.requestId, listed.value.entries, listed.value.truncated));
+        }
+        catch (error) {
+            refused(refusal('repository-read-failed', describe(error)));
+        }
+    }
+    /** Answer `repository_read`: the head of one text file under the repository root. */
+    async #answerRepositoryRead(channelKey, asked) {
+        const nothing = { text: null, sizeBytes: 0, truncated: false };
+        const refused = (why) => this.#refuseRepository(channelKey, repositoryReadResult(asked.requestId, nothing, wireRefusalOf(why)), why);
+        const root = this.#workspaces?.repositoryRoot;
+        if (root === undefined)
+            return refused(noRepositoryRoot());
+        try {
+            const read = await readRepositoryFile(root, asked.path, asked.maxBytes, this.#options.protectedPaths);
+            if (!read.ok)
+                return refused(read.refusal);
+            this.#send(channelKey, repositoryReadResult(asked.requestId, read.value));
+        }
+        catch (error) {
+            refused(refusal('repository-read-failed', describe(error)));
+        }
+    }
+    /** A refused repository ask goes on the wire as its result kind, and is reported locally too. */
+    #refuseRepository(channelKey, answer, why) {
+        this.#send(channelKey, answer);
+        this.#refuse(channelKey, why);
+    }
+    /** A discovery request that could not be answered says so on the wire; the `#failDelivery` twin. */
+    #failDiscovery(channelKey, requestId, refused) {
+        this.#send(channelKey, transcriptFailed(requestId, { reason: refused.reason, detail: refused.detail }));
+        this.#refuse(channelKey, refused);
+    }
+    /**
+     * Answer `workspace_release` (protocol v5): remove a workspace's directory, on demand, by name.
+     *
+     * Every exit is the one result kind: `refusal: null` is the released answer, a named refusal
+     * is every other, so "every exit sends a wire answer" is a property of the shape here rather than
+     * a discipline across two builders. The answer is one small frame, nowhere near the frame cap,
+     * unconditionally, since the key screen is length-bounded and the detail echoes `keyPreview`,
+     * never the raw key.
+     *
+     * The in-use guard is many-to-one, because keys alias: N sessions can share one workspace key,
+     * each with its own entry in `#workspaceKeyFor`, so the guard scans values and holds until the
+     * last session on the key is gone. A guard that cleared on the first close would delete a tree
+     * the other sessions are still working in, the exact conditions the shared-worktree topology
+     * exists to create. Opening sessions count too: their entry is written before the provision
+     * await.
+     *
+     * `ReleaseOptions.remove` stays default-false everywhere else. This is the one production path
+     * that passes it, and it passes it because a caller asked; a session ending still leaves its
+     * directory for whoever wants to look at it.
+     */
+    async #answerWorkspaceRelease(channelKey, asked) {
+        const outcome = await this.#releaseOne(asked, false);
+        this.#send(channelKey, workspaceReleaseResult(asked.requestId, outcome.result));
+        if (outcome.refused !== null)
+            this.#refuse(channelKey, outcome.refused);
+    }
+    /**
+     * Every entry is judged and released on its own — different keys interleave, the same key
+     * serialises under its turn — and a refusal on one never aborts the rest. Duplicates are judged
+     * on the name as asked: the second entry naming a key or a path already in this ask does nothing
+     * and says so.
+     */
+    async #answerWorkspaceReleaseBulk(channelKey, asked) {
+        const named = new Set();
+        const outcomes = await Promise.all(asked.releases.map((entry) => {
+            const name = entry.workspaceKey ?? entry.path;
+            const duplicate = name !== null && named.has(name);
+            if (name !== null)
+                named.add(name);
+            return this.#releaseOne(entry, duplicate);
+        }));
+        this.#send(channelKey, workspaceReleaseBulkResult(asked.requestId, outcomes.map((outcome) => outcome.result)));
+        for (const outcome of outcomes) {
+            if (outcome.refused !== null)
+                this.#refuse(channelKey, outcome.refused);
+        }
+    }
+    /**
+     * One release: resolve the address to a key, screen it, then under the key's turn run the in-use
+     * guard and the provider's release with the ask's flags. Every exit is a result; `refused` is the
+     * same refusal for the log.
+     */
+    async #releaseOne(ask, duplicate) {
+        const provider = this.#workspaces;
+        const refused = (reason, detail, partial = {}) => {
+            const problem = refusal(reason, detail);
+            return {
+                result: workspaceReleaseEntryResult({
+                    ...partial,
+                    refusal: { reason: problem.reason, detail: problem.detail },
+                }),
+                refused: problem,
+            };
+        };
+        if (provider === undefined) {
+            return refused('workspace-release-failed', 'this host has no workspace provider — there is no workspace to release');
+        }
+        if (ask.workspaceKey !== null && ask.path !== null) {
+            return refused('workspace-release-failed', 'workspace_release names both a workspaceKey and a path — name exactly one');
+        }
+        let workspaceKey;
+        if (ask.path !== null) {
+            if (provider.keyForPath === undefined) {
+                return refused('workspace-release-failed', "this host's workspace provider cannot address a worktree by path — name its workspaceKey", { path: ask.path });
+            }
+            const resolved = provider.keyForPath(ask.path);
+            if (resolved === null) {
+                return refused('workspace-release-failed', `workspace_release.path ${keyPreview(ask.path)} is not a directory directly under this host's workspace root`, { path: ask.path });
+            }
+            workspaceKey = resolved;
+        }
+        else if (ask.workspaceKey !== null) {
+            workspaceKey = ask.workspaceKey;
+        }
+        else {
+            return refused('workspace-release-failed', 'workspace_release names neither a workspaceKey nor a path — name exactly one');
+        }
+        const address = { workspaceKey, path: ask.path };
+        const problem = unusableKeyProblem(workspaceKey);
+        if (problem !== null) {
+            return refused('workspace-release-failed', `workspace_release.workspaceKey ${keyPreview(workspaceKey)} ${problem}`, address);
+        }
+        if (duplicate) {
+            return refused('workspace-release-failed', `workspace ${workspaceKey} is named twice in one ask — this entry does nothing`, address);
+        }
+        // The scan and the removal ride one turn. The in-use guard is check-then-act across a
+        // multi-second `git worktree remove`; scanned outside the turn, a `session_new` on this key
+        // could pass its own guard mid-removal and provision into a dying directory while this answer
+        // reads released. Inside the turn the scan runs after any queued provision or close-release
+        // settles, so it reads the map the other verbs have finished writing.
+        return this.#workspaceTurns.run(workspaceKey, async () => {
+            const inUse = [...this.#workspaceKeyFor.values()].includes(workspaceKey);
+            if (inUse) {
+                return refused('workspace-release-failed', `workspace ${workspaceKey} still backs a live or opening session on this host — close every session on it before asking for its removal`, address);
+            }
+            try {
+                const released = await provider.release(workspaceKey, {
+                    remove: true,
+                    deleteBranch: ask.deleteBranch,
+                    force: ask.force,
+                });
+                if (!released.ok)
+                    return refused(released.refusal.reason, released.refusal.detail, address);
+                const receipt = released.value;
+                // A provider that answers no receipt vouches for nothing beyond "released or absent".
+                if (receipt === undefined)
+                    return { result: workspaceReleaseEntryResult(address), refused: null };
+                const partial = {
+                    workspaceKey,
+                    path: receipt.path,
+                    directoryRemoved: receipt.directoryRemoved,
+                    branchDeleted: receipt.branchDeleted,
+                };
+                if (receipt.refusal !== null)
+                    return refused(receipt.refusal.reason, receipt.refusal.detail, partial);
+                return { result: workspaceReleaseEntryResult(partial), refused: null };
+            }
+            catch (error) {
+                // A provider that throws instead of refusing lands in the same named place, the contract
+                // the ordinary release path already holds.
+                return refused('workspace-release-failed', describe(error), address);
+            }
+        });
+    }
+    /**
+     * List the worktrees under the workspace root, read from disk now. Paged like the transcript
+     * listing; every exit is one `workspace_list_result`, refusal or page, so a host that cannot look
+     * says so by name rather than going quiet.
+     */
+    async #answerWorkspaceList(channelKey, asked) {
+        const answer = (page, refused) => {
+            this.#send(channelKey, workspaceListResult(asked.requestId, page.entries, page, refused === undefined ? undefined : { reason: refused.reason, detail: refused.detail }));
+            if (refused !== undefined)
+                this.#refuse(channelKey, refused);
+        };
+        const empty = { entries: [], totalCount: 0, defaultBranch: null };
+        const provider = this.#workspaces;
+        if (provider === undefined) {
+            return answer(empty, refusal('workspace-list-failed', 'this host has no workspace provider — there is nothing to list'));
+        }
+        if (provider.inventory === undefined) {
+            return answer(empty, refusal('workspace-list-failed', "this host's workspace provider keeps no inventory"));
+        }
+        let inventory;
+        try {
+            inventory = await provider.inventory();
+        }
+        catch (error) {
+            return answer(empty, refusal('workspace-list-failed', describe(error)));
+        }
+        if (!inventory.ok)
+            return answer(empty, inventory.refusal);
+        const all = inventory.value.entries;
+        const from = Math.max(0, asked.fromIndex);
+        const end = Math.min(all.length, from + WORKSPACE_PAGE_SIZE);
+        return answer({
+            entries: all.slice(from, end),
+            totalCount: all.length,
+            ...(end < all.length ? { nextIndex: end } : {}),
+            defaultBranch: inventory.value.defaultBranch,
+        });
+    }
+    /**
+     * Apply a configuration change. Every exit is one `host_configure_result` carrying the
+     * effective configuration, so a controller always learns what this host runs with, refused or
+     * not. The seam validates and writes; this method only decides whether the host is busy and swaps
+     * the rebuilt pieces in, then tells the link what its next hello declares.
+     */
+    #answerHostConfigure(channelKey, asked) {
+        const answer = (refused) => {
+            this.#send(channelKey, hostConfigureResult(asked.requestId, this.#configuration, this.#overriddenByEnvironment, refused === undefined ? undefined : { reason: refused.reason, detail: refused.detail }, this.#pendingRestart));
+            if (refused !== undefined)
+                this.#refuse(channelKey, refused);
+        };
+        const reconfigure = this.#options.reconfigure;
+        if (reconfigure === undefined) {
+            return answer(refusal('config-write-failed', 'this host was composed without a configuration seam, so nothing can be written'));
+        }
+        // Busy means a workspace is claimed or being claimed: a session releases through the provider
+        // that provisioned it, so the roots cannot move under one. The seam refuses only when the ask
+        // actually changes a root; a scheme or transcripts-root change applies live regardless.
+        const hostBusy = this.#sessions.size > 0 || this.#opening.size > 0;
+        let outcome;
+        try {
+            outcome = reconfigure(asked.entries, hostBusy);
+        }
+        catch (error) {
+            return answer(refusal('config-write-failed', describe(error)));
+        }
+        if (!outcome.ok)
+            return answer(outcome.refusal);
+        const rebuilt = outcome.value;
+        this.#workspaces = rebuilt.workspaces;
+        this.#transcriptsRoot = rebuilt.transcriptsRoot;
+        this.#bulk = rebuilt.bulk;
+        this.#linkCapabilities = rebuilt.linkCapabilities;
+        this.#configuration = rebuilt.configuration;
+        this.#overriddenByEnvironment = rebuilt.overriddenByEnvironment;
+        // The control-plane addresses are never applied to the live link: the host keeps dialling what it
+        // dialled, names the keys as pending, and the next start reads the file.
+        this.#pendingRestart = rebuilt.pendingRestart;
+        this.#link.announce?.(this.#linkCapabilities, this.#configuration, this.#pendingRestart);
+        return answer();
+    }
+    async #deliver(sessionKey, deliveryId, what, postUrl, fromOffset) {
+        const resolve = this.#bulk;
+        if (resolve === undefined) {
+            return this.#failDelivery(sessionKey, deliveryId, refusal('bulk-target-invalid', 'this host resolves no bulk content — nothing can be delivered'));
+        }
+        const filePath = resolve(what, sessionKey);
+        if (!filePath.ok)
+            return this.#failDelivery(sessionKey, deliveryId, filePath.refusal);
+        // The one origin this host will POST to, derived from the link it already dials. Resolved per
+        // delivery rather than cached so a reconfigured controller URL cannot leave a stale trusted
+        // origin behind it.
+        const allowedOrigin = bulkOriginFor(this.#options.controllerUrl);
+        if (!allowedOrigin.ok)
+            return this.#failDelivery(sessionKey, deliveryId, allowedOrigin.refusal);
+        // The same credential the link and the decision POST present, resolved per delivery. A
+        // credential that refuses posts headerless rather than not at all: this lane is a read-back the
+        // controller itself asked for, and the receiver's refusal comes back loud on the wire as
+        // `bulk-delivery-failed` naming the status, which beats a silent no-request.
+        let headers;
+        const credential = this.#options.credential;
+        if (credential !== undefined) {
+            const authorized = await credential.authorize();
+            if (authorized.ok)
+                headers = { [authorized.value.header]: authorized.value.value };
+        }
+        let receipt;
+        try {
+            receipt = await postBulk({
+                deliveryId,
+                postUrl,
+                allowedOrigin: allowedOrigin.value,
+                filePath: filePath.value,
+                fromOffset,
+                ...(headers === undefined ? {} : { headers }),
+            });
+        }
+        catch (error) {
+            receipt = refuse('bulk-delivery-failed', describe(error));
+        }
+        if (!receipt.ok)
+            return this.#failDelivery(sessionKey, deliveryId, receipt.refusal);
+        this.#send(sessionKey, {
+            kind: 'bulk_delivered',
+            deliveryId,
+            byteCount: receipt.value.byteCount,
+            // The stat pair rides the receipt so a transcript puller can detect a rewrite. See
+            // `BulkDelivered` in frames.ts.
+            sizeBytes: receipt.value.sizeBytes,
+            mtimeMs: receipt.value.mtimeMs,
+        });
+    }
+    /** A delivery that did not happen says so on the wire; it is a receipt, not a silence. */
+    #failDelivery(sessionKey, deliveryId, refused) {
+        this.#send(sessionKey, {
+            kind: 'bulk_failed',
+            deliveryId,
+            refusal: { reason: refused.reason, detail: refused.detail },
+        });
+        this.#refuse(sessionKey, refused);
+    }
+    /**
+     * Send one payload. A refusal other than queue overflow is reported locally, since there is no
+     * wire to tell; an overflow refusal of an undroppable frame holds the frame for a retry instead.
+     */
+    #send(sessionKey, payload) {
+        const pending = this.#heldFrames.get(sessionKey);
+        if (pending !== undefined && pending.length > 0) {
+            if (isDroppable(payload.kind)) {
+                this.#refuse(sessionKey, refusal('queue-dropped-droppable', `frames are held for this session; discarded an incoming ${payload.kind}`));
+                return;
+            }
+            this.#holdFrame(sessionKey, payload);
+            return;
+        }
+        const sent = this.#link.send(sessionKey, payload);
+        if (sent.ok)
+            return;
+        if (sent.refusal.reason === 'queue-overflow-undroppable' && !isDroppable(payload.kind)) {
+            this.#holdFrame(sessionKey, payload);
+            return;
+        }
+        this.#refuse(sessionKey, sent.refusal);
+    }
+    #holdFrame(sessionKey, payload) {
+        const pending = this.#heldFrames.get(sessionKey) ?? [];
+        if (pending.length >= HELD_FRAMES_MAX) {
+            this.#refuse(sessionKey, refusal('queue-overflow-undroppable', `${HELD_FRAMES_MAX} frames are already held for this session; ${payload.kind} could not be held`));
+            return;
+        }
+        pending.push(payload);
+        this.#heldFrames.set(sessionKey, pending);
+        this.#scheduleHeldFrames();
+    }
+    #scheduleHeldFrames() {
+        if (this.#heldFramesTimer !== null)
+            return;
+        // Ref'd on purpose: a held turn-end is work this process has promised to deliver.
+        this.#heldFramesTimer = setTimeout(() => {
+            this.#heldFramesTimer = null;
+            this.#retryHeldFrames();
+        }, HELD_RETRY_MS);
+    }
+    #retryHeldFrames() {
+        let remaining = false;
+        for (const [sessionKey, pending] of this.#heldFrames) {
+            while (pending.length > 0) {
+                const head = pending[0];
+                if (head === undefined)
+                    break;
+                const sent = this.#link.send(sessionKey, head);
+                if (sent.ok) {
+                    pending.shift();
+                    continue;
+                }
+                if (sent.refusal.reason !== 'queue-overflow-undroppable') {
+                    this.#refuse(sessionKey, sent.refusal);
+                    pending.shift();
+                    continue;
+                }
+                break;
+            }
+            if (pending.length === 0)
+                this.#heldFrames.delete(sessionKey);
+            else
+                remaining = true;
+        }
+        if (remaining)
+            this.#scheduleHeldFrames();
+    }
+    #refuse(sessionKey, refused) {
+        this.#report({ kind: 'refusal', refusal: refused, sessionKey });
+    }
+    /**
+     * A refused open goes on the wire. Reported locally only, the controller would keep a session
+     * record nobody could talk to and the operator would watch a session that "did nothing" while
+     * the refusal sat in this host's log. The session never had a machine, so this is the one
+     * transition composed by hand: spawning to ended, cause `refusal` with the reason as its event
+     * and the whole detail; the controller stores it, ends its record, and can show why. Local
+     * report first, then the wire.
+     */
+    #refuseOpen(sessionKey, cwd, refused) {
+        this.#refuse(sessionKey, refused);
+        let where;
+        try {
+            where =
+                cwd === null
+                    ? { cwd: '', worktree: null, branch: null, unknownReason: 'the session never had a workspace' }
+                    : readWhere(cwd);
+        }
+        catch {
+            where = { cwd: cwd ?? '', worktree: null, branch: null, unknownReason: 'git facts could not be read' };
+        }
+        const transition = {
+            sessionId: null,
+            // The controller's own handle is the only correlation this session ever had.
+            correlationId: sessionKey,
+            seq: 1,
+            at: new Date(this.#options.clock?.() ?? Date.now()).toISOString(),
+            from: 'spawning',
+            to: 'ended',
+            activity: null,
+            entryId: null,
+            cause: { kind: 'refusal', event: refused.reason, detail: refused.detail },
+            where,
+        };
+        const sent = this.#link.send(sessionKey, stateTransitionUpdate(transition));
+        if (!sent.ok)
+            this.#report({ kind: 'refusal', refusal: sent.refusal, sessionKey });
+    }
+    #report(event) {
+        try {
+            this.#options.report?.(event);
+        }
+        catch {
+            // The reporter is the failure channel; reporting a reporter would recurse.
+        }
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The repository asks on a host composed without a repository root: nothing to read under. */
+function noRepositoryRoot() {
+    return refusal('repository-path-escape', 'this host has no repository root configured, so there is nothing to read under');
+}
+/** A local refusal as the wire carries it. */
+function wireRefusalOf(why) {
+    return { reason: why.reason, detail: why.detail };
+}
+//# sourceMappingURL=host.js.map