@xenosystem/agent-interface-host 0.1.3

package/dist/index.js

@@ -0,0 +1,3242 @@
+import { AgentHostProtocolError, XENO_AGENT_HOST_MIN_PROTOCOL_VERSION, XENO_AGENT_HOST_PROTOCOL_VERSION, isAgentHostClientIdentity, isAgentProviderListResult, defaultRunIdOf, isAgentRuntimeEventEnvelope, } from '@xenosystem/agent-interface-contract';
+/**
+ * Bounds on the instruction queue. Unbounded queues are how a stuck loop turns
+ * into unbounded memory; the coordination spec applies the same discipline to
+ * inter-run messages.
+ */
+/** A refusal is cheap to produce and a host can live for days. */
+const MAX_FLEET_COLLISIONS = 500;
+const MAX_QUEUED_INSTRUCTIONS = 50;
+const MAX_QUEUED_INSTRUCTION_LENGTH = 20_000;
+import { cloneProvider, isDevelopmentProviderReady, missingDevelopmentCapabilities, resolveAgentRuntimeSelection, renderWorkspaceKnowledge, selectAvailableProviders, withHostBackedCapabilities, planFanOut, routeByCapability, } from '@xenosystem/agent-interface-core';
+import { InMemoryInterruptedTurnStore, } from './turns/interruptedTurns.js';
+import { evaluateTurnAdmission, resolveTurnAdmissionPolicy, } from './turns/turnAdmission.js';
+import { boundSubagentWorkspace } from './subagents/subagentWorkspaceAuthority.js';
+import { summariseSubagentRun } from './subagents/subagentRunPort.js';
+import { describeClaimScope } from './coordination/claims.js';
+import { CoordinationService } from './coordination/CoordinationService.js';
+import { renderInbox } from './coordination/renderInbox.js';
+import { coordinationRuntimeEventDraft } from './coordination/runtimeEvents.js';
+import { RunObservationService } from './observation/RunObservationService.js';
+import { RunIsolationService } from './isolation/RunIsolationService.js';
+import { IntakeService } from './intake/IntakeService.js';
+import { WorkspaceKnowledgeService } from './knowledge/WorkspaceKnowledgeService.js';
+import { AgentSessionService } from './session/AgentSessionService.js';
+import { createBufferedSessionPty } from './session/bufferedSessionPty.js';
+import { renderSupportFor } from './session/renderSupport.js';
+import { createRuntimeEventSessionChannel } from './session/runtimeEventChannel.js';
+import { answerChooseDirectoryRequest } from './agent/chooseDirectoryBridge.js';
+import { answerWorkspacePlacementRequest } from './agent/workspacePlacementBridge.js';
+/**
+ * How long the host waits for an adapter to notice an abort before it stops counting the turn.
+ *
+ * 🔴 This exists because the host used to wait FOREVER. `activeTurns` is cleared in the
+ * `.finally()` of the adapter's execute promise, so an adapter that ignores `signal` — or simply
+ * hangs — kept its entry indefinitely. Measured 2026-08-17: `turn.cancel` returned
+ * `success: true` while the turn stayed active and stayed counted, and with turn admission in
+ * place the slot never came back. Sixteen such turns wedge a default host, recoverable only by
+ * restarting it.
+ *
+ * Generous, because a slow-but-honest adapter finishing its cleanup is the common case and
+ * abandoning it early would be worse than waiting. Bounded, because "wait for cooperation that
+ * may never come" is not a policy.
+ */
+export const DEFAULT_TURN_ABANDON_GRACE_MS = 5_000;
+export class AgentHostCoordinator {
+    options;
+    listeners = new Set();
+    providers = new Map();
+    providerCatalogLoader;
+    runtimeEvents = new Map();
+    runtimeEventRepository;
+    stateRepository;
+    workspaceService;
+    interactionService;
+    permissionPolicyService;
+    interruptedTurnStore;
+    sdkControlService;
+    engineeringControlService;
+    coordinationService;
+    /**
+     * Run id -> the conversation that run belongs to.
+     *
+     * Gate 8 needs coordination on the RUN TIMELINE, and a timeline entry is
+     * addressed by conversation and request. Only the host knows that mapping;
+     * the coordination service deals in run ids alone, which is what keeps it
+     * testable without a store.
+     */
+    runContexts = new Map();
+    coordinationEventSequence = 0;
+    /** Collisions seen since this host started — see the sink above for why this
+     *  is the only place they exist. */
+    fleetCollisions = [];
+    runObservationService;
+    runIsolationService;
+    runObservationBinder;
+    sessionService;
+    intakeService;
+    knowledgeService;
+    acpApprovalService;
+    /**
+     * Subagent runs — ADE §5.2. A PORT spanning `SubagentRunService` (create/list) and
+     * `SubagentScheduler` (cancel), because cancelling a launched run must reach the adapter.
+     */
+    subagentRuns;
+    resolveRunId;
+    connectedClients = new Map();
+    /** What each connected client declared it can do, keyed the same way. */
+    clientCapabilities = new Map();
+    turnExecutionAdapters = new Map();
+    turnAdmissionPolicy;
+    turnAbandonGraceMs;
+    /**
+     * Timers owned by a live turn: its deadline, and any abandonment grace already started.
+     * Cleared when the turn settles, so a completed turn cannot be abandoned retroactively.
+     */
+    turnTimers = new Map();
+    activeTurns = new Map();
+    commandResults = new Map();
+    /**
+     * Instructions stacked while a turn is running, per conversation.
+     *
+     * Held by the HOST, not by an adapter: that is what makes queueing work at
+     * every structure tier (ADE spec §2.9), including a third-party agent running
+     * its own TUI where there is no protocol to hand a steer to.
+     *
+     * The host does NOT auto-start the queued turn. It holds the instruction and
+     * signals when the active turn ends; the client starts the next turn, because
+     * the client is where the user's permission context lives. Auto-drain would
+     * convert a queue into unattended execution, which is a different decision.
+     */
+    queuedInstructions = new Map();
+    queuedInstructionSequence = 0;
+    sequence = 0;
+    catalogRevision = 0;
+    providerCatalogFingerprint = '';
+    providerCatalogRefresh = null;
+    constructor(options) {
+        const { providers, providerCatalogLoader, runtimeEvents, runtimeEventRepository, stateRepository, workspaceService, interactionService, permissionPolicyService, interruptedTurnStore, turnAdmissionPolicy, turnAbandonGraceMs, sdkControlService, engineeringControlService, turnExecutionAdapters, coordinationService, runObservationService, runIsolationService, runObservationBinder, sessionService, intakeService, knowledgeService, acpApprovalService, subagentRuns, resolveRunId, ...hostOptions } = options;
+        if (runtimeEventRepository && runtimeEvents && runtimeEvents.length > 0) {
+            throw new Error('Seeded runtimeEvents cannot be combined with a durable runtimeEventRepository.');
+        }
+        this.options = { ...hostOptions };
+        this.runtimeEventRepository = runtimeEventRepository;
+        this.providerCatalogLoader = providerCatalogLoader;
+        this.stateRepository = stateRepository;
+        this.workspaceService = workspaceService;
+        this.interactionService = interactionService;
+        this.permissionPolicyService = permissionPolicyService;
+        this.interruptedTurnStore = interruptedTurnStore || new InMemoryInterruptedTurnStore();
+        this.turnAdmissionPolicy = turnAdmissionPolicy ?? resolveTurnAdmissionPolicy();
+        this.turnAbandonGraceMs = turnAbandonGraceMs ?? DEFAULT_TURN_ABANDON_GRACE_MS;
+        this.sdkControlService = sdkControlService;
+        this.engineeringControlService = engineeringControlService;
+        this.coordinationService = coordinationService;
+        // A turn's run identity, if the request carries one. `subagentRunId` first:
+        // a subagent IS a distinct run with its own claims, so folding it into its
+        // parent conversation would let two runs share one lock holder.
+        // 🔴 `defaultRunIdOf`, not a hand-written `??` — a session filters runtime
+        // EVENTS by the same rule, and the two must not drift. See its doc.
+        this.resolveRunId = resolveRunId ?? ((request) => defaultRunIdOf(request));
+        this.workspaceService?.setEventSink((type, payload) => this.publish(type, payload));
+        // Coordination reaches surfaces through the event feed and nothing else.
+        // Published as `redactionState: 'safe'` like every host event — which holds
+        // because a coordination event carries ids, scopes and outcomes, never
+        // message TEXT. That is a property of the CoordinationEvent union, so it is
+        // asserted in a test rather than trusted to stay true.
+        this.coordinationService?.setEventSink((event) => {
+            // 🔴 Recorded HERE, not projected from the runtime-event cache.
+            //
+            // The first version of `fleet.view` projected collisions from
+            // `this.runtimeEvents`, which looked right and was empty in the app:
+            // `publishPersistedRuntimeEvent` publishes a persisted event to
+            // subscribers and does NOT add it to that map, so with a repository
+            // configured — which is every real composition — coordination events
+            // never reached it. The view would have reported "no collisions" forever.
+            //
+            // The claim registry keeps no record of a refusal (it refuses and moves
+            // on), so this sink is the only place a collision exists at all. Bounded,
+            // because a long-lived host must not accumulate one entry per refusal
+            // without limit.
+            if (event.type === 'coordination.claim.refused') {
+                this.fleetCollisions.push({
+                    // `describeClaimScope`, because a scope is a structured value and the fleet view
+                    // reports the unit of work a person recognises — a path as itself, a branch permit
+                    // as `branch:<name>` so the two axes stay distinguishable in one timeline.
+                    scope: describeClaimScope(event.scope),
+                    wantedByRunId: event.runId,
+                    heldByRunId: event.heldByRunId,
+                    at: new Date().toISOString(),
+                });
+                if (this.fleetCollisions.length > MAX_FLEET_COLLISIONS)
+                    this.fleetCollisions.shift();
+            }
+            this.publish('coordination.event', event);
+        });
+        // The OTHER half of gate 8: the durable record, which carries the message
+        // text the live feed deliberately does not.
+        this.coordinationService?.setTimelineSink((event, text) => {
+            void this.recordCoordinationEvent(event, text);
+        });
+        this.runObservationService = runObservationService;
+        // Always present, never optional. A host that could not answer "is this
+        // contained?" would leave the surface guessing, and the honest answer with
+        // no source is `none` rather than silence.
+        this.runIsolationService = runIsolationService ?? new RunIsolationService();
+        this.runObservationBinder = runObservationBinder;
+        // Counts and completeness only — see the contract's `run.observation`.
+        this.runObservationService?.setEventSink((summary) => this.publish('run.observation', summary));
+        this.sessionService = sessionService;
+        this.intakeService = intakeService;
+        this.knowledgeService = knowledgeService;
+        // Session lifecycle on the feed: ids, modes and viewer counts — never PTY
+        // BYTES. Terminal output reaches a surface by attaching to the session,
+        // which is a subscription per viewer, not a broadcast to every client.
+        this.sessionService?.setEventSink((event) => this.publish('session.event', event));
+        this.acpApprovalService = acpApprovalService;
+        this.subagentRuns = subagentRuns;
+        for (const provider of providers ?? []) {
+            this.setProvider(provider, false);
+        }
+        this.providerCatalogFingerprint = fingerprintProviders([...this.providers.values()]);
+        for (const event of runtimeEvents ?? []) {
+            this.appendRuntimeEvent(event, false);
+        }
+        for (const adapter of turnExecutionAdapters ?? []) {
+            this.registerTurnExecutionAdapter(adapter);
+        }
+    }
+    /**
+     * The mounted coordination service, or `undefined` when the host has none.
+     *
+     * Deliberately NOT reachable through `request()`. A run coordinates with
+     * another run; a client surface watches. Exposing send/claim as host methods
+     * would let whatever is holding a transport act *as* a run, which is exactly
+     * the boundary coordination spec §4 draws — and `AgentHostTransport` is a
+     * protected cross-repo interface whose consumers (Hub, Shell) would all need
+     * coordinating for a capability neither of them is asking for.
+     */
+    get coordination() {
+        return this.coordinationService;
+    }
+    /**
+     * Puts what the workspace knows into the turn — ADE §5.8's gate.
+     *
+     * 🔴 **In the coordinator, before the adapter is invoked, so it cannot be
+     * per-provider.** The gate is that a fact learned by one provider reaches a
+     * later run on a DIFFERENT one; injecting inside an adapter would make that a
+     * property each lane had to remember, and the lane that forgot would fail
+     * silently — the prompt would simply be missing knowledge, which looks exactly
+     * like an agent that never learned anything.
+     *
+     * 🔴 **Prepended to `systemPrompt`, never replacing it.** Standing context
+     * about the codebase is what a system prompt is for, and every lane already
+     * carries one — so this reaches all of them without touching three adapters.
+     * A caller's own system prompt is preserved below it.
+     *
+     * A failure here does NOT fail the turn. Knowledge is an enrichment; the run
+     * is the user's actual work, and a broken store must not be able to stop it.
+     * The turn simply proceeds without the block, which is the same behaviour as a
+     * workspace that has learned nothing yet.
+     */
+    async injectWorkspaceKnowledge(request) {
+        const service = this.knowledgeService;
+        if (!service || !request.workspaceId)
+            return;
+        try {
+            const selection = await service.context(request.workspaceId);
+            const block = renderWorkspaceKnowledge(selection);
+            // An empty block is not injected at all — not as an empty string, not as a
+            // stray blank line. Prompt space spent saying nothing is prompt space
+            // taken from something.
+            if (!block)
+                return;
+            const heading = 'What this workspace knows:';
+            request.systemPrompt = request.systemPrompt
+                ? `${heading}\n${block}\n\n${request.systemPrompt}`
+                : `${heading}\n${block}`;
+        }
+        catch {
+            // Deliberately silent to the TURN. The knowledge service reports its own
+            // problems through `knowledge.context`, which a surface can show.
+        }
+    }
+    /** Workspace knowledge — ADE §5.8. Thin: the rules live in `core`. */
+    async listKnowledge(input) {
+        const service = this.knowledgeService;
+        if (!service) {
+            return {
+                available: false,
+                entries: [],
+                durable: false,
+                reason: 'This host is not keeping workspace knowledge.',
+            };
+        }
+        return {
+            available: true,
+            entries: (await service.list(input.workspaceId)).map(summariseKnowledge),
+            durable: service.durable,
+        };
+    }
+    async recordKnowledge(input) {
+        const service = this.knowledgeService;
+        if (!service)
+            return { ok: false, reason: 'This host is not keeping workspace knowledge.' };
+        const subject = String(input.subject ?? '').trim();
+        const fact = String(input.fact ?? '').trim();
+        if (!subject || !fact) {
+            // Refused rather than stored empty: a blank fact occupies prompt budget
+            // and tells an agent nothing.
+            return { ok: false, reason: 'A fact needs both a subject and a statement.' };
+        }
+        const entry = await service.record({
+            workspaceId: input.workspaceId,
+            subject,
+            fact,
+            ...(input.pinned ? { pinned: true } : {}),
+            runId: input.runId,
+            ...(input.providerId ? { providerId: input.providerId } : {}),
+        });
+        return { ok: true, entry: summariseKnowledge(entry) };
+    }
+    async forgetKnowledge(input) {
+        const service = this.knowledgeService;
+        if (!service)
+            return { ok: false, reason: 'This host is not keeping workspace knowledge.' };
+        const forgotten = await service.forget(input.workspaceId, input.entryId);
+        return forgotten ? { ok: true } : { ok: false, reason: 'No such knowledge entry.' };
+    }
+    async knowledgeContext(input) {
+        const service = this.knowledgeService;
+        if (!service) {
+            return {
+                available: false,
+                text: '',
+                entries: [],
+                omitted: [],
+                // NOT complete. Nothing was read, and a caller treating this as a
+                // complete empty context would inject nothing and believe it had
+                // everything.
+                complete: false,
+                reason: 'This host is not keeping workspace knowledge.',
+            };
+        }
+        const selection = await service.context(input.workspaceId, input.maxChars === undefined ? {} : { maxChars: input.maxChars });
+        return {
+            available: true,
+            text: renderWorkspaceKnowledge(selection),
+            entries: selection.entries.map(summariseKnowledge),
+            omitted: selection.omitted,
+            complete: selection.complete,
+        };
+    }
+    /** Intake — ADE §5.1. Thin: every rule lives in `core/intakeClaim`. */
+    listIntakeSources() {
+        const service = this.intakeService;
+        if (!service) {
+            return { available: false, sources: [], reason: 'This host has no intake sources configured.' };
+        }
+        return {
+            available: true,
+            sources: service.sources().map((source) => ({
+                sourceId: source.sourceId,
+                label: source.label,
+                healthy: source.healthy,
+                ...(source.problem ? { problem: source.problem } : {}),
+            })),
+        };
+    }
+    async listIntakeItems(input) {
+        const service = this.intakeService;
+        if (!service) {
+            return {
+                available: false,
+                items: [],
+                // NOT `complete: true`. Nothing was read, so nothing is known — and an
+                // unreadable inbox reporting completeness reads as "no work".
+                complete: false,
+                failedSources: [],
+                reason: 'This host has no intake sources configured.',
+            };
+        }
+        const inbox = await service.inbox(input.sourceId ? { sourceId: input.sourceId } : {});
+        return {
+            available: true,
+            items: inbox.items.map((item) => ({
+                id: item.id,
+                sourceId: item.source.sourceId,
+                externalId: item.source.externalId,
+                title: item.title,
+                ...(item.detail === undefined ? {} : { detail: item.detail }),
+                ...(item.createdAt === undefined ? {} : { createdAt: item.createdAt }),
+                ...(item.url === undefined ? {} : { url: item.url }),
+                claimState: item.claim.state,
+                ...(item.claim.state === 'unclaimed' ? {} : { claimedBy: item.claim.byClientId }),
+                ...(item.claim.state === 'dispatched' ? { runId: item.claim.runId } : {}),
+            })),
+            complete: inbox.complete,
+            failedSources: inbox.failedSources,
+        };
+    }
+    claimIntakeItem(input) {
+        const service = this.intakeService;
+        if (!service)
+            return { ok: false, reason: 'This host has no intake sources configured.' };
+        const result = service.claim(input.itemId, input.clientId);
+        return intakeClaimResponse(result, service.claimState(input.itemId).state);
+    }
+    releaseIntakeItem(input) {
+        const service = this.intakeService;
+        if (!service)
+            return { ok: false, reason: 'This host has no intake sources configured.' };
+        const released = service.release(input.itemId, input.clientId);
+        if (released)
+            return { ok: true, claimState: 'unclaimed' };
+        // Named rather than a bare false: "you do not hold this" and "nobody does"
+        // call for different next moves.
+        const state = service.claimState(input.itemId);
+        return {
+            ok: false,
+            claimState: state.state,
+            ...(state.state === 'unclaimed'
+                ? { reason: 'Nobody holds this item.' }
+                : { heldBy: state.byClientId, reason: `${state.byClientId} holds this item.` }),
+        };
+    }
+    dispatchIntakeItem(input) {
+        const service = this.intakeService;
+        if (!service)
+            return { ok: false, reason: 'This host has no intake sources configured.' };
+        const result = service.dispatch(input.itemId, input.clientId, input.runId);
+        return intakeClaimResponse(result, service.claimState(input.itemId).state);
+    }
+    /**
+     * Sessions over the protocol — ADE §5.5, build-order step 4.
+     *
+     * The substrate has had attach, takeover and input routing all along; none of
+     * it was reachable from a surface, which is the same "built, tested,
+     * unreachable" shape this repo has shipped repeatedly. These methods are thin
+     * on purpose: every rule worth trusting lives in `AgentSessionService` and
+     * `writeLease`, where it is tested without a host.
+     */
+    listSessions(input) {
+        const service = this.sessionService;
+        if (!service) {
+            // Distinct from "no sessions". A surface that cannot tell them apart
+            // waits for sessions that can never appear.
+            return { available: false, sessions: [], reason: 'This host has no session substrate mounted.' };
+        }
+        const sessions = service.sessions()
+            .filter((session) => !input.runId || session.runId === input.runId)
+            .map((session) => summariseSession(session));
+        return { available: true, sessions };
+    }
+    attachSession(input) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        /**
+         * 🔴 The `onData` sink is deliberately EMPTY.
+         *
+         * Attaching registers a viewer and makes the session's viewer count true;
+         * it does not stream bytes to this caller, because the host protocol is
+         * request/response and its event feed is a broadcast that must never carry
+         * PTY output. Output is read with `session.snapshot`.
+         *
+         * The retention buffer is subscribed at OPEN, not here, so a viewer that
+         * attaches late still sees what happened while nobody was watching.
+         */
+        const ok = service.attach(input.sessionId, input.viewerId, () => { });
+        if (!ok) {
+            return {
+                ok: false,
+                reason: service.session(input.sessionId)
+                    ? 'That viewer is already attached to this session.'
+                    : 'No such session.',
+            };
+        }
+        const session = service.session(input.sessionId);
+        return { ok: true, ...(session ? { session: summariseSession(session) } : {}) };
+    }
+    detachSession(input) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        const ok = service.detach(input.sessionId, input.viewerId);
+        // A session outlives its viewers — detaching is not closing.
+        if (!ok)
+            return { ok: false, reason: 'That viewer is not attached to this session.' };
+        const session = service.session(input.sessionId);
+        return { ok: true, ...(session ? { session: summariseSession(session) } : {}) };
+    }
+    snapshotSession(input) {
+        const service = this.sessionService;
+        const snapshot = service?.snapshot(input.sessionId);
+        if (!snapshot) {
+            return {
+                available: false,
+                output: '',
+                // NOT `truncated: false`. Nothing was read, so nothing is known about
+                // whether output was dropped, and a false here would be a claim.
+                truncated: false,
+                reason: service ? 'No such session.' : 'This host has no session substrate mounted.',
+            };
+        }
+        return { available: true, output: snapshot.output, truncated: snapshot.truncated };
+    }
+    /**
+     * Hands a run what its peers said — ADE §5.2b's `message` primitive.
+     *
+     * 🔴 Nothing called `deliverTo`. Messages were sent, journalled, reported
+     * `delivered` to the sender — and sat in the bus forever, because the only
+     * thing that empties an inbox had no caller anywhere in the repo. The
+     * primitive was half a pipe: every agent could send and no agent could
+     * receive, while the sender was told it had been delivered.
+     *
+     * At TURN START and in the coordinator, for the same reason §5.8's knowledge
+     * injection is: a push that each lane had to remember would fail silently in
+     * the lane that forgot, and a prompt merely missing its messages looks exactly
+     * like a run nobody wrote to.
+     *
+     * Prepended to `systemPrompt` alongside knowledge rather than appended to the
+     * user's prompt — what a peer said is standing context for this turn, not
+     * something the user typed, and putting it in their words would misattribute
+     * it.
+     *
+     * ⚠️ Draining also sets the run's CAUSE, which is what makes gate 8
+     * attribution and §8 loop detection work at all: a message this run sends
+     * while handling another inherits the chain. Both were inert for the same
+     * reason.
+     */
+    deliverCoordinationMessages(request) {
+        const service = this.coordinationService;
+        const runId = this.resolveRunId(request);
+        if (!service || !runId)
+            return;
+        try {
+            const block = renderInbox(service.deliverTo(runId));
+            // An empty inbox injects NOTHING — not a heading, not a blank line. Prompt
+            // space spent saying "no messages" is prompt space taken from something.
+            if (!block)
+                return;
+            const heading = 'Messages from other runs in this fleet:';
+            request.systemPrompt = request.systemPrompt
+                ? `${heading}\n${block}\n\n${request.systemPrompt}`
+                : `${heading}\n${block}`;
+        }
+        catch {
+            // A failure here does NOT fail the turn, matching the knowledge
+            // injection: the run is the user's actual work. But note the asymmetry —
+            // a dropped message is a LOSS, not a missing enrichment, and the drain
+            // already published `coordination.message.delivered` to the timeline, so
+            // a reader can still see what arrived.
+        }
+    }
+    /**
+     * A run's activity changed — §7's run state and last decision.
+     *
+     * 🔴 `awaiting-approval` had no producer at all, and the gap is not
+     * cosmetic: a peer deciding whether to wait for a run or take the work itself
+     * needs "blocked on a human" to look different from "busy". A run reported
+     * `running` while it sits on a permission prompt is the one case where
+     * waiting is guaranteed to be wrong.
+     *
+     * Public because the signal originates in a turn adapter, which the
+     * composition builds BEFORE this host exists — the same ordering
+     * `setEventSink` already solves for coordination events.
+     */
+    reportRunActivity(signal) {
+        this.registerCoordinationRun(signal.runId, signal.state, signal.lastDecision);
+    }
+    /**
+     * Puts a run on the coordination roster — ADE §5.2b.
+     *
+     * 🔴 Nothing called `registerRun`. The primitives were reachable from both
+     * lanes and INERT: `peers()` returns an empty list for a caller it has never
+     * heard of, so every agent asking who else was working got the same answer as
+     * an agent genuinely alone. The build was complete and the feature did
+     * nothing — the shape this repo keeps finding one level further in.
+     *
+     * An UPSERT, called at both ends of a turn, because a run spans many turns and
+     * its state changes: `running` while a turn is in flight, `idle` between them.
+     * A run is never removed here; `endRun` belongs to whoever created the run,
+     * and claims have lease expiry as the backstop for a host that never got the
+     * news.
+     *
+     * ⚠️ `complete: false`, always, and honestly. This host observes FILES — the
+     * process sensor lives behind `xeno-use` and only the file-change port is
+     * consumed here — so `commandsRun` is empty because commands are UNOBSERVED,
+     * not because none ran. A peer must be able to tell those apart.
+     */
+    registerCoordinationRun(runId, state, lastDecision) {
+        const service = this.coordinationService;
+        // \u{1F534} Read from `runContexts`, not from a request handed in. A state change
+        // arrives mid-turn from the permission bridge, which has no turn request —
+        // and a version of this that needed one could only ever be called at the
+        // two moments a turn begins and ends, which is exactly the granularity that
+        // made `awaiting-approval` unreachable.
+        const context = this.runContexts.get(runId);
+        if (!service || !context)
+            return;
+        // Live, from tier-1 observation, rather than a list this method maintains:
+        // a second copy would disagree with the diff a reviewer is looking at.
+        const observed = this.runObservationService?.snapshot(runId);
+        // Carried forward when this update does not bring a new one: `undefined`
+        // means "no change", and overwriting a real decision with it would erase
+        // §7's fourth field every time the run merely went idle.
+        const previous = service.runSummary(runId, runId);
+        const decision = lastDecision ?? previous?.lastDecision;
+        service.registerRun({
+            runId,
+            // §3: human-readable, defaulting from the workspace. The run id is the
+            // honest fallback — it is at least the thing a peer would address.
+            name: context.workspaceId || runId,
+            state,
+            // '' when the request names no workspace, which `canSee` treats as
+            // matching NOTHING rather than matching every other unnamed run.
+            workspace: context.workspaceId ?? '',
+            filesTouched: (observed?.changes ?? []).map((change) => change.path),
+            commandsRun: [],
+            complete: false,
+            ...(decision === undefined ? {} : { lastDecision: decision }),
+            // §6: the input to `deriveInboundPolicy`.
+            //
+            // Per-TURN, and that is correct rather than incidental: `upsertRun`
+            // REPLACES the record, and `runContexts` is rewritten at each turn start,
+            // so a turn that declares no capabilities leaves the posture unknown again
+            // instead of inheriting the last turn's. A posture is "what this run is
+            // executing with *now*" — carrying a stale one forward would judge a
+            // message against authority the run no longer has.
+            //
+            // Spread-omitted rather than set to `undefined` because the field is
+            // declared optional under `exactOptionalPropertyTypes`.
+            ...(context.posture === undefined ? {} : { posture: context.posture }),
+        });
+    }
+    /**
+     * Gives a run a session — ADE §2.8, and the step §9 has been stuck on.
+     *
+     * Opened at TURN START rather than on demand, because a session is where a
+     * person looks to see what the agent is doing, and one that only exists after
+     * someone asks for it is not there during the minute they most want it.
+     *
+     * 🔴 Every ingredient is derived, none is asserted:
+     *
+     * - the render support comes from the ADAPTERS (`renderSupportFor`), so a
+     *   provider nothing can execute is refused by name instead of opening a
+     *   session that would render nothing;
+     * - the protocol channel is the run's OWN runtime-event stream, already
+     *   redacted and already durable, so the terminal is a rendering of the run
+     *   rather than a second opinion about it;
+     * - the PTY has no process behind it, because in `acp` there is nothing to
+     *   attach to — and `createBufferedSessionPty` throws rather than silently
+     *   swallowing a write, so a broken mode rule surfaces instead of losing
+     *   what someone typed.
+     *
+     * Failures are contained for the same reason the observation binder's are: a
+     * turn is the user's actual work, and a session is an observability surface
+     * over it. A run without a session is honest — `session.list` simply will not
+     * show it — whereas a turn that failed to start because a terminal could not
+     * be opened would be absurd.
+     *
+     * ⚠️ One session per RUN, not per turn. A second turn on the same run finds
+     * the session already open and leaves it alone; re-opening would discard the
+     * output a viewer is reading mid-conversation.
+     */
+    openSessionForRun(runId, provider) {
+        const service = this.sessionService;
+        // No "already open?" check: `open` REFUSES `session_exists`, and a second
+        // statement of that rule here would be free to drift from it. Removing this
+        // guard changed no test, which is how it was found.
+        if (!service)
+            return;
+        try {
+            const support = renderSupportFor(provider, { adapters: [...this.turnExecutionAdapters.values()] });
+            const protocol = createRuntimeEventSessionChannel({
+                runId,
+                subscribe: (listener) => this.subscribe((event) => {
+                    if (event.type !== 'runtime.event.appended')
+                        return;
+                    const payload = event.payload;
+                    if (isAgentRuntimeEventEnvelope(payload?.event))
+                        listener(payload.event);
+                }),
+            });
+            const opened = service.open({
+                sessionId: runId,
+                runId,
+                support,
+                pty: createBufferedSessionPty(),
+                protocol,
+            });
+            // A refusal is the substrate doing its job — an unexecutable provider has
+            // nothing to render. Close the channel we built for it rather than leaving
+            // a subscription attached to a session that never existed.
+            if (!opened.ok)
+                protocol.close();
+        }
+        catch {
+            // Contained: see above. The run proceeds without a session.
+        }
+    }
+    async routeSessionInput(input) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        // \u{1F534} DERIVED here, never accepted from the caller. Both facts are the
+        // host's: it holds the active turns, and it knows whether the run's adapter
+        // can steer — it already refuses `steer_unsupported` on that same basis.
+        const runId = service.session(input.sessionId)?.runId;
+        const active = runId ? this.activeTurnForRun(runId) : undefined;
+        const result = service.routeInput(input.sessionId, input.viewerId, input.data, {
+            turnInFlight: active !== undefined,
+            acceptsMidTurnSteering: active?.adapter.steer !== undefined,
+        });
+        if (!result.ok) {
+            // Who holds it, by name. "Someone else is typing" leaves the reader with
+            // no next action; naming the surface tells them whom to ask.
+            return result.code === 'lease_held'
+                ? {
+                    ok: false,
+                    code: 'lease_held',
+                    reason: `${result.holder} has taken over this session.`,
+                }
+                : { ok: false, code: 'no_such_session', reason: 'No such session.' };
+        }
+        const owed = await this.deliverOwedSessionInput(input.sessionId, input.command, input.data, result.delivery);
+        return {
+            ok: true,
+            disposition: result.routing.disposition,
+            delivered: owed.delivered,
+            sink: result.delivery.sink,
+            ...(owed.queued === undefined ? {} : { queued: owed.queued }),
+            ...(owed.reason === undefined ? {} : { reason: owed.reason }),
+        };
+    }
+    /**
+     * The turn a run is executing right now, if any.
+     *
+     * §2.8's routing needs two facts — is a turn in flight, and can this agent
+     * take a correction mid-turn — and both live here. `activeTurns` is keyed by
+     * conversation and request, so finding a RUN's turn means asking
+     * `resolveRunId` about each one, the same derivation everything else uses.
+     */
+    activeTurnForRun(runId) {
+        for (const active of this.activeTurns.values()) {
+            if (this.resolveRunId(active.request) === runId)
+                return active;
+        }
+        return undefined;
+    }
+    /**
+     * Delivers what the substrate could not, through the ONE path that can.
+     *
+     * §2.8 promises typing never falls into a void, and `AgentSessionService`
+     * keeps its half by refusing to write into a PTY with no process behind it. It
+     * deliberately stops there: an `acp` steer travels `turn.steer`, where
+     * acknowledgement, idempotency and the named refusal already live, and a
+     * second delivery path from inside the substrate would be the unacknowledged
+     * one §5.5 measured to be wrong.
+     *
+     * So the host — which owns execution — closes the loop here, for BOTH input
+     * doors. Splitting it would leave the promise held at one entrance again.
+     *
+     * A failure is REPORTED, never swallowed: `turn_not_active` in particular is
+     * an ordinary outcome (someone typed between turns) and its message already
+     * tells the reader to queue instead. Reporting `delivered: true` there would
+     * be the precise lie this whole chain exists to prevent.
+     */
+    async deliverOwedSessionInput(sessionId, command, data, delivery) {
+        if (delivery.delivered || delivery.sink === 'pty')
+            return { delivered: delivery.delivered };
+        const runId = this.sessionService?.session(sessionId)?.runId;
+        const context = runId ? this.runContexts.get(runId) : undefined;
+        if (!context) {
+            return {
+                delivered: false,
+                reason: delivery.sink === 'turn.queue'
+                    ? 'That session has no run to queue against. Start a turn so the instruction has somewhere to go.'
+                    : 'That session has no run to steer. Start a turn so the instruction has somewhere to go.',
+            };
+        }
+        /**
+         * 🔴 The `turn.queue` sink, SERVICED.
+         *
+         * `routeHumanInput` returns `disposition: 'queue'` when a turn is in flight
+         * and the agent does not take mid-turn steering, and its own reason string
+         * promises the input is "delivered as the next turn". Nothing kept that
+         * promise: this method returned early for every sink but `turn.steer`, so
+         * the keystrokes were dropped — the void `AgentSessionInputResult` says
+         * deliberately does not exist ("there is deliberately no `drop`: typing
+         * never falls into a void").
+         *
+         * It also left the host's whole turn queue with no writer, which is why
+         * `turn.queue` / `.list` / `.drop` were built, tested and reachable by
+         * nothing.
+         *
+         * `delivered` stays FALSE on purpose: the agent has not seen this. Queued
+         * is not delivered, and the id is what says the queue took it.
+         */
+        if (delivery.sink === 'turn.queue') {
+            const queued = this.queueTurnInstruction({
+                command,
+                conversationId: context.conversationId,
+                instruction: data,
+            });
+            if (!queued.success)
+                return { delivered: false, reason: queued.safeError };
+            const entry = queued.queue[queued.queue.length - 1];
+            return {
+                delivered: false,
+                // The conversation rides along because that is what `turn.queue.drop`
+                // is keyed by, and the session only knows its run. Without it the id is
+                // evidence a surface can render and not act on.
+                ...(entry
+                    ? { queued: { instructionId: entry.id, conversationId: context.conversationId } }
+                    : {}),
+            };
+        }
+        const steer = await this.steerTurn({
+            command,
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            instruction: data,
+        });
+        return steer.success ? { delivered: true } : { delivered: false, reason: steer.safeError };
+    }
+    async takeOverSession(input) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        if (!service.session(input.sessionId))
+            return { ok: false, reason: 'No such session.' };
+        const outcome = service.takeOver(input.sessionId, input.viewerId, input.data);
+        if (!outcome) {
+            /**
+             * 🔴 The session EXISTS — checked immediately above — so `undefined` here
+             * means REFUSED, not missing.
+             *
+             * `takeOver` returns `undefined` for both, which is fine inside the
+             * substrate (the caller there has the session in hand) and is exactly the
+             * conflation a protocol surface must not pass on: "no such session" sends
+             * someone to re-open a terminal, while "someone else is typing" tells them
+             * to go talk to a colleague. The pre-check is what keeps them apart.
+             */
+            const current = service.session(input.sessionId)?.lease;
+            const holder = current && current.holder.kind === 'human' ? current.holder.viewerId : null;
+            return {
+                ok: false,
+                ...(current ? { lease: summariseLease(current) } : {}),
+                reason: holder
+                    ? `Another person is typing in this session (${holder}).`
+                    : 'The write lease could not be taken.',
+            };
+        }
+        const owed = await this.deliverOwedSessionInput(input.sessionId, input.command, input.data, outcome.delivery);
+        return {
+            ok: true,
+            lease: summariseLease(outcome.lease),
+            delivered: owed.delivered,
+            sink: outcome.delivery.sink,
+            ...(owed.reason === undefined ? {} : { reason: owed.reason }),
+        };
+    }
+    releaseSession(input) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        const ok = service.releaseTakeOver(input.sessionId, input.viewerId);
+        if (!ok)
+            return { ok: false, reason: 'That viewer does not hold the write lease.' };
+        const session = service.session(input.sessionId);
+        return { ok: true, ...(session ? { session: summariseSession(session) } : {}) };
+    }
+    /**
+     * Every run this host knows about — ADE §9 step 6.
+     *
+     * Composed from three subsystems rather than a fourth record, because a
+     * separate fleet ledger would be a second copy of facts that already exist and
+     * would disagree with them the first time one was updated and the other was
+     * not.
+     *
+     * 🔴 The completeness flags are the load-bearing part. A fleet view showing
+     * three collisions when five happened, or four changed files when a drain was
+     * dropped, is worse than no fleet view: it is the shape a person uses to
+     * decide the work is safe to land.
+     */
+    /**
+     * Plans a fan-out WITHOUT starting anything — ADE §5.2's scheduler.
+     *
+     * Deliberately separate from dispatch. A plan is the reviewable artifact: it
+     * shows which agent gets which task, which tasks nothing can run and why, and
+     * how the load actually spread — all before a single agent touches a
+     * repository. Fusing plan and execute would remove the only moment at which
+     * any of that can be checked.
+     */
+    planFleetFanOut(input) {
+        const plan = planFanOut([...this.providers.values()], (input.tasks ?? []).map((task) => ({
+            taskId: task.taskId,
+            ...(task.requiredCapabilities === undefined
+                ? {}
+                : { requiredCapabilities: task.requiredCapabilities }),
+        })));
+        return {
+            assignments: plan.assignments.map((assignment) => ({
+                taskId: assignment.taskId,
+                providerId: assignment.providerId,
+                degraded: [...assignment.degraded],
+            })),
+            refusals: plan.refusals.map((refusal) => ({ ...refusal })),
+            loadByProvider: { ...plan.loadByProvider },
+        };
+    }
+    /**
+     * Which agents could run a task requiring these capabilities — ADE §5.2.
+     *
+     * A pure QUERY over the live provider catalog: it starts nothing, so a
+     * surface or a scheduler can ask before committing to anything.
+     *
+     * 🔴 The refusal REASON is the deliverable, not the boolean. §5.2's gate is
+     * that a task requiring an undeclared capability is "refused with a named
+     * reason" — so this reports which capability nobody declares, and
+     * distinguishes that from every capable agent merely being down. Those two
+     * send a user to completely different places.
+     *
+     * The matching rules live in `routeByCapability` (provider-neutral, in
+     * `core`) rather than here: this method's job is to supply the catalog and
+     * shape the answer for the wire.
+     */
+    routeByCapabilities(input) {
+        const decision = routeByCapability([...this.providers.values()], input.requiredCapabilities ?? []);
+        if (decision.routable) {
+            return {
+                routable: true,
+                candidates: decision.matches.map((match) => ({
+                    providerId: match.providerId,
+                    degraded: [...match.degraded],
+                })),
+                rejected: decision.rejected.map((entry) => ({
+                    providerId: entry.providerId,
+                    ...(entry.capability === undefined ? {} : { capability: entry.capability }),
+                    reason: entry.reason,
+                })),
+            };
+        }
+        return {
+            routable: false,
+            candidates: [],
+            rejected: decision.rejected.map((entry) => ({
+                providerId: entry.providerId,
+                ...(entry.capability === undefined ? {} : { capability: entry.capability }),
+                reason: entry.reason,
+            })),
+            reason: decision.reason,
+        };
+    }
+    readFleetView(input) {
+        const problems = [];
+        // 🔴 Claims come from the SERVICE and collisions from the timeline, and the
+        // split is not an inconsistency — the two answer different questions.
+        //
+        // A claim is current state: the registry knows what is held right now,
+        // including leases that have since expired and runs that never started a
+        // turn. Projecting claims from events instead would MISS a run that claimed
+        // a path without a conversation — which is exactly the run worth seeing,
+        // because it has locked something and is about to collide with someone.
+        //
+        // A collision is history: the registry refuses the second claimant and keeps
+        // no record of the refusal, so the timeline is the only place it survives.
+        // `fleetProjection` retains them deliberately — "nobody collided" and "a
+        // collision happened and was handled" are different histories.
+        const liveClaims = this.coordinationService?.claims() ?? [];
+        const heldScopes = new Set(liveClaims.map((claim) => describeClaimScope(claim.scope)));
+        // 🔴 The collision record is NEVER complete today, and this says so.
+        //
+        // The first version of this line read `this.runtimeEventRepository ===
+        // undefined`, which was exactly backwards: with no repository the host
+        // records no coordination timeline at all, so collisions are always empty —
+        // and it reported that as COMPLETE. An empty list plus a complete flag is
+        // read as "nobody collided", which is the false-clean failure this whole
+        // family of flags exists to prevent. Found by running the test, not by
+        // reading the code.
+        //
+        // With a repository it is still partial: the collisions are projected from
+        // an in-memory cache of what this host has seen since it started, not from
+        // the durable timeline. Both cases are false; they differ in WHY, and the
+        // reason is what a reader can act on.
+        const coordinationComplete = false;
+        problems.push('Collisions cover what this host has seen since it started; earlier ones are not held anywhere.');
+        const claimsByRun = new Map();
+        for (const claim of liveClaims) {
+            claimsByRun.set(claim.runId, [...(claimsByRun.get(claim.runId) ?? []), describeClaimScope(claim.scope)]);
+        }
+        // §5.1 provenance, read per RUN. Absent when the host has no intake mounted
+        // OR when this run was not dispatched from an item — both mean "no intake
+        // origin to show", and neither is a claim that one is unknown.
+        const intakeOriginFor = (runId) => this.intakeService?.originFor(runId);
+        const overlaps = this.runObservationService?.landingOverlaps(input.claimedPathsByRun ?? {});
+        const contestedByRun = new Map();
+        for (const overlap of overlaps?.overlaps ?? []) {
+            for (const runId of overlap.runIds) {
+                contestedByRun.set(runId, [...(contestedByRun.get(runId) ?? []), overlap.path]);
+            }
+        }
+        // Every run anything knows about, not just the observed ones: a run with a
+        // claim and no observation is exactly the run a person needs to see.
+        const runIds = new Set([
+            ...this.runContexts.keys(),
+            ...claimsByRun.keys(),
+            ...this.fleetCollisions.flatMap((collision) => [collision.wantedByRunId, collision.heldByRunId]),
+            ...(this.runObservationService?.observedRuns() ?? []),
+        ]);
+        // One lookup built once: `runSummary(runId, runId)` is how a run reads its
+        // OWN record, which is the only view guaranteed visible regardless of
+        // workspace.
+        const service = this.coordinationService;
+        const rosterState = service
+            ? (runId) => service.runSummary(runId, runId)?.state
+            : undefined;
+        const workingRuns = new Set();
+        for (const active of this.activeTurns.values()) {
+            const runId = this.resolveRunId(active.request);
+            if (runId)
+                workingRuns.add(runId);
+        }
+        /**
+         * 🔴 Starts FALSE when nothing is observing.
+         *
+         * It used to start `true` unconditionally and only go false when a snapshot
+         * existed and reported a hole — so a host with no observation substrate,
+         * where `snapshot` is always undefined, announced that every diff was the
+         * whole story. Exactly the shape already fixed once in
+         * `coordinationComplete`, which is why the fix is the same: say why.
+         */
+        let observationComplete = this.runObservationService !== undefined;
+        if (!observationComplete) {
+            problems.push('No run observation is configured, so no run\'s changes are known.');
+        }
+        const runs = [...runIds].sort().map((runId) => {
+            const context = this.runContexts.get(runId);
+            const snapshot = this.runObservationService?.snapshot(runId);
+            const pinnedInboundPolicy = service?.inboundPolicyFor(runId).explicit;
+            const isolation = this.runIsolationService.report(runId);
+            // A run nobody observed is not a complete picture either. Absent and
+            // incomplete are different facts about the RUN — see `diffComplete` —
+            // but for the FLEET both mean the same thing: this view cannot be read as
+            // the whole story.
+            if (!snapshot && this.runObservationService) {
+                observationComplete = false;
+                problems.push(`${runId}: not observed, so its changes are unknown.`);
+            }
+            if (snapshot && !snapshot.complete) {
+                observationComplete = false;
+                for (const problem of snapshot.problems)
+                    problems.push(`${runId}: ${problem}`);
+            }
+            return {
+                runId,
+                ...(context?.conversationId ? { conversationId: context.conversationId } : {}),
+                ...(context?.workspaceId ? { workspaceId: context.workspaceId } : {}),
+                ...(context?.agentId ? { agentId: context.agentId } : {}),
+                working: workingRuns.has(runId),
+                claims: (claimsByRun.get(runId) ?? []).sort(),
+                ...(snapshot
+                    ? {
+                        changes: countChangeKinds(snapshot.changes),
+                        // Present ONLY when observed. Absent and `false` are different
+                        // facts: "nobody watched" versus "watched, with a hole".
+                        diffComplete: snapshot.complete,
+                    }
+                    : {}),
+                ...(intakeOriginFor(runId) ? { intakeItemId: intakeOriginFor(runId) } : {}),
+                contestedPaths: (contestedByRun.get(runId) ?? []).sort(),
+                // From the ROSTER, the same state a peer sees. Absent without a
+                // coordination service: no roster means no answer, and `false` would
+                // assert the run is not waiting.
+                ...(rosterState
+                    ? { awaitingApproval: rosterState(runId) === 'awaiting-approval' }
+                    : {}),
+                // §6 `hold`, as a COUNT. Absent without a coordination service for the
+                // same reason as the line above: no roster, no answer.
+                ...(service ? { heldMessages: service.heldFor(runId).length } : {}),
+                // §6's EXPLICIT override only — absent when the derivation decides.
+                //
+                // Deliberately not the effective policy: §6 derives comparatively, so
+                // "what happens to a message" depends on who sends it and has no single
+                // value to show on a row. Reporting one would invent an answer for a
+                // question the row cannot ask. What a human needs here is whether THEY
+                // pinned something, because that is the only part they can undo.
+                // Read ONCE into a local: two calls cannot be narrowed by the compiler,
+                // and a value read twice is a value that can disagree with itself.
+                ...(pinnedInboundPolicy === undefined ? {} : { inboundPolicy: pinnedInboundPolicy }),
+                // 🔴 ALWAYS present, unlike every other optional field on this row.
+                // §5.3 requires the user to always know whether the thing running is
+                // contained, and "always" is the word that forbids omitting it when the
+                // answer is unflattering. `none` IS the answer today.
+                isolation: isolation.isolation,
+                ...(isolation.mechanism === undefined ? {} : { isolationMechanism: isolation.mechanism }),
+                ...(isolation.reason === undefined ? {} : { isolationReason: isolation.reason }),
+            };
+        });
+        return {
+            runs,
+            collisions: this.fleetCollisions.map((collision) => ({
+                ...collision,
+                // Recomputed against the CURRENT claim map rather than stored: a
+                // collision whose holder has since released is history, not something a
+                // person still has to act on, and only the live registry knows which.
+                stillHeld: heldScopes.has(collision.scope),
+            })),
+            coordinationComplete,
+            observationComplete,
+            problems,
+        };
+    }
+    /**
+     * A run's observed diff, for review.
+     *
+     * 🔴 Unavailable is reported as `available: false` with a reason, never as an
+     * empty change list. They are different facts — "this run changed nothing" and
+     * "nobody was watching" — and a surface that cannot tell them apart will show
+     * a clean review for an unobserved run.
+     */
+    /**
+     * What a run is not being told yet — coordination §6 `hold`.
+     *
+     * 🔴 `available: false` when this host has no coordination service, so a
+     * surface can tell "this host does not coordinate" from "nothing is
+     * held". Reporting an empty list for both would make an unmounted service
+     * look like a quiet one.
+     */
+    listHeldMessages(input) {
+        const service = this.coordinationService;
+        if (!service) {
+            return {
+                available: false,
+                runId: input.runId,
+                held: [],
+                reason: 'This host is not coordinating runs.',
+            };
+        }
+        return {
+            available: true,
+            runId: input.runId,
+            held: service.heldFor(input.runId).map((message) => ({
+                id: message.id,
+                fromRunId: message.fromRunId,
+                text: message.text,
+                sentAt: message.sentAt,
+            })),
+        };
+    }
+    /** A human approves one held message. §6's approval step, made reachable. */
+    releaseHeldMessage(input) {
+        const service = this.coordinationService;
+        if (!service) {
+            return {
+                status: 'expired',
+                messageId: input.messageId,
+                reason: 'This host is not coordinating runs.',
+            };
+        }
+        const outcome = service.releaseHeld(input.runId, input.messageId);
+        return {
+            status: outcome.status,
+            messageId: outcome.messageId,
+            ...('reason' in outcome && outcome.reason ? { reason: outcome.reason } : {}),
+        };
+    }
+    /**
+     * A human pins or releases a run's inbound policy — §6's override, made
+     * reachable.
+     *
+     * 🔴 Deliberately a HOST method and not a lane call. `CoordinationLanePort`
+     * exposes exactly four calls and this is not one of them, because an agent
+     * that could set its receiver's policy could accept its own messages past the
+     * rule that a message never moves trust upward.
+     */
+    setCoordinationInboundPolicy(input) {
+        const service = this.coordinationService;
+        if (!service) {
+            return { ok: false, reason: 'This host is not coordinating runs.' };
+        }
+        if (input.policy === null)
+            service.clearInboundPolicy(input.runId);
+        else
+            service.setInboundPolicy(input.runId, input.policy);
+        // Read back rather than echo the request: the surface must render what the
+        // host now holds, and a result that restated the input would look identical
+        // whether or not the write landed.
+        const { explicit } = service.inboundPolicyFor(input.runId);
+        return { ok: true, ...(explicit === undefined ? {} : { explicit }) };
+    }
+    async readRunObservation(input) {
+        const unavailable = (reason) => ({
+            available: false,
+            runId: input.runId,
+            changes: [],
+            // `complete: false` on the unavailable path, deliberately. An unobserved
+            // run's diff is not complete; it does not exist. Reporting `true` here
+            // would let a landing gate that only reads completeness clear it.
+            complete: false,
+            droppedEvents: 0,
+            problems: [],
+            reason,
+        });
+        const service = this.runObservationService;
+        if (!service)
+            return unavailable('This host is not observing runs.');
+        const snapshot = input.poll === true
+            ? await service.poll(input.runId)
+            : service.snapshot(input.runId);
+        if (!snapshot)
+            return unavailable('This run is not being observed.');
+        return {
+            available: true,
+            runId: snapshot.runId,
+            changes: snapshot.changes.map((change) => ({ path: change.path, kind: change.kind })),
+            complete: snapshot.complete,
+            droppedEvents: snapshot.droppedEvents,
+            problems: snapshot.problems,
+        };
+    }
+    /**
+     * Content for one changed path — §2.9 hunk-level review.
+     *
+     * The service refuses a path the run did not change, so this cannot be used to
+     * browse the sandbox: that is a different capability with a different consent
+     * story, and a review pane is not a licence to read arbitrary files.
+     */
+    async readRunObservationChange(input) {
+        const service = this.runObservationService;
+        const content = service ? await service.readChange(input.runId, input.path) : undefined;
+        if (!content) {
+            return {
+                available: false,
+                path: input.path,
+                binary: false,
+                truncated: false,
+                refusal: service
+                    ? 'This run has no observed change at that path, or no content reader is configured.'
+                    : 'This host is not observing runs.',
+            };
+        }
+        return {
+            available: true,
+            path: content.path,
+            ...(content.before === undefined ? {} : { before: content.before }),
+            ...(content.after === undefined ? {} : { after: content.after }),
+            binary: content.binary,
+            truncated: content.truncated,
+            ...(content.refusal === undefined ? {} : { refusal: content.refusal }),
+        };
+    }
+    /** Where the observed runs collide — §5.7, while both are still alive. */
+    readRunObservationOverlaps(input) {
+        const service = this.runObservationService;
+        if (!service) {
+            return {
+                available: false,
+                overlaps: [],
+                incompleteRuns: [],
+                // Not complete: nothing was measured. An `available: false` result that
+                // claimed completeness would read as "checked, nothing found".
+                complete: false,
+                reason: 'This host is not observing runs, so overlaps cannot be detected.',
+            };
+        }
+        /**
+         * The host tells the service which runs it knows about; the service owns the
+         * rule that an unobserved one makes the report incomplete.
+         *
+         * 🔴 That rule used to live HERE, and the shipping landing gate bypassed
+         * it by calling `landingOverlaps` directly. A check that only one caller
+         * performs is a check the other caller does not have.
+         */
+        const report = service.landingOverlaps(input.claimedPathsByRun ?? {}, [
+            ...this.runContexts.keys(),
+            ...(this.coordinationService?.claims() ?? []).map((claim) => claim.runId),
+        ]);
+        return {
+            available: true,
+            overlaps: report.overlaps.map((overlap) => ({
+                path: overlap.path,
+                runIds: overlap.runIds,
+                kind: overlap.kind,
+                ...(overlap.unclaimed === undefined ? {} : { unclaimed: overlap.unclaimed }),
+            })),
+            incompleteRuns: report.incompleteRuns,
+            complete: report.complete,
+        };
+    }
+    /**
+     * How many turns are executing right now.
+     *
+     * Exposed so a composition can answer "would quitting destroy work?" — which
+     * it cannot ask any other way, and which is the difference between an app that
+     * closes cleanly and one that silently ends a run the user is waiting on.
+     *
+     * A COUNT, not the turns themselves: a caller deciding whether to quit has no
+     * business with the requests, and handing them out would make an internal map
+     * part of the surface.
+     */
+    get activeTurnCount() {
+        return this.activeTurns.size;
+    }
+    /**
+     * The mounted run-observation service, or `undefined` when unmounted.
+     *
+     * The full change set is pulled through here rather than pushed on the feed:
+     * a diff is large and mostly unchanged between polls, while the notification
+     * that it moved is small. Same reason it is not on `AgentHostTransport` —
+     * that is a protected cross-repo interface (root ABSOLUTE RULE §4).
+     */
+    get runObservation() {
+        return this.runObservationService;
+    }
+    /**
+     * The mounted session substrate, or `undefined` when unmounted.
+     *
+     * Reached by composition, not through `request()`: attaching to a session
+     * means subscribing to a byte stream, which is not a request/response shape —
+     * and `AgentHostTransport` is protected (root ABSOLUTE RULE §4).
+     */
+    get sessions() {
+        return this.sessionService;
+    }
+    async request(method, input) {
+        if (method === 'host.handshake') {
+            return this.handshake(input);
+        }
+        if (method === 'providers.list') {
+            await this.refreshProviderCatalog();
+            return this.listProviders(input);
+        }
+        if (method === 'providers.refresh') {
+            await this.refreshProviderCatalog();
+            return this.listProviders(input);
+        }
+        if (method === 'runtime.events.list') {
+            return await this.listRuntimeEvents(input);
+        }
+        if (method === 'state.workspaces.load') {
+            return await this.requireStateRepository().loadWorkspaces();
+        }
+        if (method === 'state.workspaces.save') {
+            return await this.requireStateRepository().saveWorkspaces(input);
+        }
+        if (method === 'state.conversations.load') {
+            return await this.requireStateRepository().loadConversations();
+        }
+        if (method === 'state.conversations.save') {
+            return await this.requireStateRepository().saveConversation(input);
+        }
+        if (method === 'state.conversations.delete') {
+            return await this.requireStateRepository().deleteConversation(input);
+        }
+        if (method === 'workspace.access.grant') {
+            return await this.requireWorkspaceService().grantDirectory(input);
+        }
+        if (method === 'coordination.held.list') {
+            return this.listHeldMessages(input);
+        }
+        if (method === 'coordination.held.release') {
+            return this.releaseHeldMessage(input);
+        }
+        if (method === 'coordination.policy.set') {
+            return this.setCoordinationInboundPolicy(input);
+        }
+        if (method === 'workspace.application.grant') {
+            // Deliberately NOT behind `assertWorkspaceClient`, matching
+            // `workspace.access.grant` beside it: granting is how a client comes to
+            // have access at all, so requiring existing access to ask for it would
+            // make the first grant impossible.
+            return await this.requireWorkspaceService().grantApplication(input);
+        }
+        if (method === 'workspace.directory.list') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().listDirectory(input);
+        }
+        if (method === 'workspace.file.read') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().readFile(input);
+        }
+        if (method === 'workspace.file.write') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().writeFile(input);
+        }
+        if (method === 'workspace.command.run') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().runCommand(input);
+        }
+        if (method === 'workspace.terminal.start') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().startTerminal(input);
+        }
+        if (method === 'workspace.terminal.stop') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().stopTerminal(input);
+        }
+        if (method === 'workspace.pty.start') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().startPty(input);
+        }
+        if (method === 'workspace.pty.snapshot') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().snapshotPty(input);
+        }
+        if (method === 'workspace.pty.input') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().inputPty(input);
+        }
+        if (method === 'workspace.pty.resize') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().resizePty(input);
+        }
+        if (method === 'workspace.pty.clear') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().clearPty(input);
+        }
+        if (method === 'workspace.pty.stop') {
+            this.assertWorkspaceClient(input);
+            return await this.requireWorkspaceService().stopPty(input);
+        }
+        if (method === 'turn.start') {
+            return await this.startTurn(input);
+        }
+        if (method === 'acp.provider.approve') {
+            return await this.approveAcpProvider(input);
+        }
+        if (method === 'turn.resume') {
+            return await this.resumeTurn(input);
+        }
+        if (method === 'turn.cancel') {
+            return await this.cancelTurn(input);
+        }
+        if (method === 'turn.steer') {
+            return await this.steerTurn(input);
+        }
+        if (method === 'turn.queue') {
+            return this.queueTurnInstruction(input);
+        }
+        if (method === 'turn.queue.list') {
+            return this.listQueuedInstructions(input);
+        }
+        if (method === 'run.observation.snapshot') {
+            return await this.readRunObservation(input);
+        }
+        if (method === 'run.observation.change') {
+            return await this.readRunObservationChange(input);
+        }
+        if (method === 'run.observation.overlaps') {
+            return this.readRunObservationOverlaps(input);
+        }
+        if (method === 'subagent.run.create') {
+            return this.createSubagentRun(input);
+        }
+        if (method === 'subagent.run.list') {
+            return this.listSubagentRuns(input);
+        }
+        if (method === 'subagent.run.cancel') {
+            return this.cancelSubagentRun(input);
+        }
+        if (method === 'fleet.view') {
+            return this.readFleetView(input);
+        }
+        if (method === 'fleet.route') {
+            return this.routeByCapabilities(input);
+        }
+        if (method === 'fleet.plan') {
+            return this.planFleetFanOut(input);
+        }
+        if (method === 'session.list') {
+            return this.listSessions(input);
+        }
+        if (method === 'session.attach') {
+            return this.attachSession(input);
+        }
+        if (method === 'session.detach') {
+            return this.detachSession(input);
+        }
+        if (method === 'session.snapshot') {
+            return this.snapshotSession(input);
+        }
+        if (method === 'session.input') {
+            return await this.routeSessionInput(input);
+        }
+        if (method === 'session.takeover') {
+            return await this.takeOverSession(input);
+        }
+        if (method === 'session.release') {
+            return this.releaseSession(input);
+        }
+        if (method === 'intake.sources.list') {
+            return this.listIntakeSources();
+        }
+        if (method === 'intake.items.list') {
+            return await this.listIntakeItems(input);
+        }
+        if (method === 'intake.item.claim') {
+            return this.claimIntakeItem(input);
+        }
+        if (method === 'intake.item.release') {
+            return this.releaseIntakeItem(input);
+        }
+        if (method === 'intake.item.dispatch') {
+            return this.dispatchIntakeItem(input);
+        }
+        if (method === 'knowledge.list') {
+            return await this.listKnowledge(input);
+        }
+        if (method === 'knowledge.record') {
+            return await this.recordKnowledge(input);
+        }
+        if (method === 'knowledge.forget') {
+            return await this.forgetKnowledge(input);
+        }
+        if (method === 'knowledge.context') {
+            return await this.knowledgeContext(input);
+        }
+        if (method === 'turn.queue.drop') {
+            return this.dropQueuedInstruction(input);
+        }
+        if (method === 'elicitation.choose-directory.answer') {
+            return answerChooseDirectoryRequest(input);
+        }
+        if (method === 'elicitation.workspace-placement.answer') {
+            return answerWorkspacePlacementRequest(input);
+        }
+        if (method === 'elicitation.permission.answer') {
+            return await this.requireInteractionService().answerPermission(input);
+        }
+        if (method === 'permissions.rules.list') {
+            return await this.requirePermissionPolicyService().listRules();
+        }
+        if (method === 'permissions.rules.revoke') {
+            return await this.requirePermissionPolicyService().revokeRule(input);
+        }
+        if (method === 'elicitation.ask-user.answer') {
+            return await this.requireInteractionService().answerAskUser(input);
+        }
+        if (method === 'sdk.sessions.list') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().listSessions(input);
+        }
+        if (method === 'sdk.sessions.show') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().showSession(input);
+        }
+        if (method === 'sdk.sessions.attach') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().attachSession(input);
+        }
+        if (method === 'sdk.sessions.detach') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().detachSession(input);
+        }
+        if (method === 'sdk.sessions.delete') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().deleteSession(input);
+        }
+        if (method === 'sdk.sessions.clean') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().cleanSessions(input);
+        }
+        if (method === 'sdk.checkpoints.list') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().listCheckpoints(input);
+        }
+        if (method === 'sdk.checkpoints.restore') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().restoreCheckpoint(input);
+        }
+        if (method === 'sdk.checkpoints.delete') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().deleteCheckpoint(input);
+        }
+        if (method === 'sdk.tasks.output') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().readTaskOutput(input);
+        }
+        if (method === 'sdk.tasks.stop') {
+            this.assertSdkControlClient(input);
+            return await this.requireSdkControlService().stopTask(input);
+        }
+        if (String(method).startsWith('engineering.')) {
+            this.assertEngineeringControlClient(input);
+            const engineeringMethod = method;
+            return await this.requireEngineeringControlService().request(engineeringMethod, input);
+        }
+        throw new AgentHostProtocolError('invalid_response', `Unsupported XENO Agent host method: ${String(method)}`);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Forget a client whose connection is gone.
+     *
+     * 🔴 Before this there was no `connectedClients.delete` anywhere except a wholesale clear, so
+     * the set only ever grew within a session. That is invisible until something asks a question of
+     * it — and `canPresentElicitations` is exactly such a question, asked immediately before the
+     * host puts a prompt to a person and waits with no timeout.
+     */
+    releaseClient(instanceId) {
+        this.connectedClients.delete(instanceId);
+        this.clientCapabilities.delete(instanceId);
+    }
+    /**
+     * Is there a connected client that can put a question to a person and answer it?
+     *
+     * ⚠️ Subscribers are NOT the signal, and that is the trap this method exists to avoid: the RPC
+     * server subscribes exactly ONE listener and fans out to whatever sockets it has, so a listener
+     * count of 1 is equally consistent with ten attached clients and none. Only a completed
+     * handshake says someone is there, and only a declared capability says they can answer.
+     */
+    hasElicitationCapableClient() {
+        for (const [instanceId, capabilities] of this.clientCapabilities) {
+            if (!this.connectedClients.has(instanceId))
+                continue;
+            if (capabilities.canPresentElicitations === true)
+                return true;
+        }
+        return false;
+    }
+    registerProvider(provider) {
+        this.setProvider(provider, true);
+        this.providerCatalogFingerprint = fingerprintProviders([...this.providers.values()]);
+    }
+    registerTurnExecutionAdapter(adapter) {
+        if (!adapter.id.trim())
+            throw new Error('Turn execution adapter id must not be empty.');
+        if (this.turnExecutionAdapters.has(adapter.id)) {
+            throw new Error(`Turn execution adapter ${adapter.id} is already registered.`);
+        }
+        this.turnExecutionAdapters.set(adapter.id, adapter);
+    }
+    async close() {
+        for (const active of this.activeTurns.values()) {
+            active.controller.abort('The XENO Agent host is shutting down.');
+        }
+        this.activeTurns.clear();
+        await Promise.all([...this.turnExecutionAdapters.values()].map(async (adapter) => {
+            await adapter.close?.();
+        }));
+        await this.sdkControlService?.close?.();
+        await this.engineeringControlService?.close?.();
+        await this.workspaceService?.close?.();
+        await this.stateRepository?.close?.();
+        // Before the listeners go: each session's protocol channel is subscribed to
+        // this host's event feed, and closing the session is what releases it.
+        for (const session of this.sessionService?.sessions() ?? []) {
+            this.sessionService?.close(session.sessionId);
+        }
+        this.connectedClients.clear();
+        // Cleared together, always: a capability outliving its client would answer "yes, someone can
+        // be asked" on behalf of a connection that no longer exists.
+        this.clientCapabilities.clear();
+        this.listeners.clear();
+    }
+    removeProvider(providerId) {
+        const removed = this.providers.delete(providerId);
+        if (removed) {
+            this.catalogRevision += 1;
+            this.providerCatalogFingerprint = fingerprintProviders([...this.providers.values()]);
+            this.publishCatalogChange();
+        }
+        return removed;
+    }
+    async recordRuntimeEvent(event) {
+        assertRuntimeEventForHost(event);
+        if (this.runtimeEventRepository) {
+            const result = await this.runtimeEventRepository.append(structuredClone(event));
+            if (result.inserted) {
+                this.publish('runtime.event.appended', {
+                    requestId: result.event.requestId,
+                    event: structuredClone(result.event),
+                });
+            }
+            return result.inserted;
+        }
+        return this.appendRuntimeEvent(event, true);
+    }
+    publishPersistedRuntimeEvent(event) {
+        assertRuntimeEventForHost(event);
+        this.publish('runtime.event.appended', {
+            requestId: event.requestId,
+            event: structuredClone(event),
+        });
+    }
+    createElicitationSurfaceMessenger() {
+        return {
+            send: (channel, payload) => {
+                if (channel === 'agent:choose-directory-request') {
+                    this.publish('elicitation.choose-directory.requested', structuredClone(payload));
+                    return;
+                }
+                if (channel === 'agent:workspace-placement-request') {
+                    this.publish('elicitation.workspace-placement.requested', structuredClone(payload));
+                    return;
+                }
+                if (channel === 'agent:permission-request') {
+                    this.publish('elicitation.permission.requested', structuredClone(payload));
+                    return;
+                }
+                if (channel === 'agent:ask-user-request') {
+                    this.publish('elicitation.ask-user.requested', structuredClone(payload));
+                    return;
+                }
+                if (channel === 'agent:task-event') {
+                    this.publish('task.changed', structuredClone(payload));
+                    return;
+                }
+                throw new AgentHostProtocolError('invalid_response', `Unsupported Agent elicitation channel: ${channel}`);
+            },
+        };
+    }
+    /**
+     * Enqueue a subagent run — ADE §5.2, the join between `fleet.plan` and `SubagentScheduler`.
+     *
+     * ⚠️ Reached through a PORT spanning two objects on purpose. `createRun`/`listRuns` live on
+     * `SubagentRunService` and `cancelRun` on `SubagentScheduler` — and cancel must go through the
+     * SCHEDULER, because cancelling a run whose adapter has already launched it has to tell the
+     * adapter. Handing the host either object alone would push that distinction onto every caller.
+     *
+     * 🔴 Refuses with a NAMED reason when no scheduler is mounted, rather than pretending. A host
+     * with no scheduler is a normal composition (the standalone app had none until this landed),
+     * and a create that silently succeeded against nothing would queue work no one will ever run.
+     */
+    createSubagentRun(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return { success: false, safeError: 'The requesting surface must complete the host handshake first.' };
+        }
+        const commandKey = this.commandKey('subagent.run.create', input.command);
+        const fingerprint = commandFingerprint(input);
+        const prior = this.commandResults.get(commandKey);
+        if (prior) {
+            // 🔴 The reason this verb takes a command envelope at all: a client that retries an enqueue
+            // it is unsure about must NOT get a second child doing identical work.
+            if (prior.method !== 'subagent.run.create' || prior.fingerprint !== fingerprint) {
+                return { success: false, safeError: 'This idempotency key was already used for a different command.' };
+            }
+            return structuredClone(prior.result);
+        }
+        if (!this.subagentRuns) {
+            // Deliberately NOT remembered: a refusal caused by this host's shape must not freeze into
+            // the command ledger, or mounting a scheduler later would replay the refusal forever.
+            return { success: false, safeError: 'This Agent host has no subagent scheduler mounted.' };
+        }
+        /**
+         * 🔴 A CHILD MAY NOT OUTRANK ITS PARENT. The requested workspace is bounded by the workspace
+         * of the turn that spawned this run, and a request that cannot be bounded is REFUSED rather
+         * than quietly narrowed — a caller told it got a workspace it did not get would debug the
+         * wrong thing.
+         *
+         * ⚠️ Refusals here are NOT remembered in the command ledger, for the same reason as the
+         * missing-scheduler refusal above: the parent turn may simply not have started yet, and
+         * freezing that answer would replay it forever against a retry that would now succeed.
+         */
+        const bound = boundSubagentWorkspace({
+            ...(input.workspace === undefined ? {} : { requested: input.workspace }),
+            ...(this.parentTurnWorkspace(input) === undefined
+                ? {}
+                : { parent: this.parentTurnWorkspace(input) }),
+        });
+        if (!bound.granted)
+            return { success: false, safeError: bound.safeError };
+        const created = this.subagentRuns.createRun({
+            ...(bound.workspace === undefined ? {} : { workspace: bound.workspace }),
+            parentConversationId: input.parentConversationId,
+            ...(input.parentRequestId === undefined ? {} : { parentRequestId: input.parentRequestId }),
+            parentAgentId: input.parentAgentId,
+            childConversationId: input.childConversationId,
+            childAgentId: input.childAgentId,
+            workspaceId: input.workspaceId,
+            teamId: input.teamId,
+            objective: input.objective,
+            ...(input.role === undefined ? {} : { role: input.role }),
+            ...(input.requiredCapabilities === undefined
+                ? {}
+                : { requiredCapabilities: [...input.requiredCapabilities] }),
+        });
+        const result = created.success && created.run
+            ? { success: true, run: summariseSubagentRun(created.run) }
+            : { success: false, safeError: created.error ?? 'The subagent run could not be created.' };
+        this.commandResults.set(commandKey, {
+            method: 'subagent.run.create',
+            fingerprint,
+            result: structuredClone(result),
+        });
+        return result;
+    }
+    /**
+     * What the turn that spawned this run is allowed to reach.
+     *
+     * Resolved from `runContexts`, which the host populates at `turn.start` and keeps for the life
+     * of the run. Absent means the host genuinely does not know — a run created outside a turn, or
+     * by a surface that declared no workspace — and `boundSubagentWorkspace` treats that as
+     * authorising nothing rather than as permission.
+     */
+    parentTurnWorkspace(input) {
+        for (const context of this.runContexts.values()) {
+            if (context.conversationId !== input.parentConversationId)
+                continue;
+            if (input.parentRequestId !== undefined && context.requestId !== input.parentRequestId)
+                continue;
+            if (context.workspace)
+                return context.workspace;
+        }
+        return undefined;
+    }
+    listSubagentRuns(input) {
+        if (!this.subagentRuns) {
+            return { success: false, runs: [], safeError: 'This Agent host has no subagent scheduler mounted.' };
+        }
+        const listed = this.subagentRuns.listRuns({
+            ...(input.parentConversationId === undefined ? {} : { parentConversationId: input.parentConversationId }),
+            ...(input.childAgentId === undefined ? {} : { childAgentId: input.childAgentId }),
+            ...(input.workspaceId === undefined ? {} : { workspaceId: input.workspaceId }),
+            ...(input.teamId === undefined ? {} : { teamId: input.teamId }),
+            ...(input.status === undefined ? {} : { status: input.status }),
+            ...(input.activeOnly === undefined ? {} : { activeOnly: input.activeOnly }),
+        });
+        return listed.success
+            ? { success: true, runs: listed.runs.map(summariseSubagentRun) }
+            : { success: false, runs: [], safeError: listed.error ?? 'Subagent runs could not be listed.' };
+    }
+    cancelSubagentRun(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return { success: false, safeError: 'The requesting surface must complete the host handshake first.' };
+        }
+        if (!this.subagentRuns) {
+            return { success: false, safeError: 'This Agent host has no subagent scheduler mounted.' };
+        }
+        const cancelled = this.subagentRuns.cancelRun({
+            id: input.runId,
+            ...(input.reason === undefined ? {} : { reason: input.reason }),
+        });
+        return cancelled.success && cancelled.run
+            ? { success: true, run: summariseSubagentRun(cancelled.run) }
+            : { success: false, safeError: cancelled.error ?? 'The subagent run could not be cancelled.' };
+    }
+    /** Remember a timer owned by this turn, so settling can cancel it. */
+    trackTurnTimer(activeKey, timer) {
+        const timers = this.turnTimers.get(activeKey);
+        if (timers)
+            timers.push(timer);
+        else
+            this.turnTimers.set(activeKey, [timer]);
+    }
+    /**
+     * Drop every timer for a turn. Called when it settles, so a turn that finished normally can
+     * never be abandoned afterwards by a timer that was already in flight.
+     */
+    clearTurnTimers(activeKey) {
+        for (const timer of this.turnTimers.get(activeKey) ?? [])
+            clearTimeout(timer);
+        this.turnTimers.delete(activeKey);
+    }
+    /**
+     * Abort a turn, then STOP COUNTING IT if the adapter does not settle in time.
+     *
+     * 🔴 The honesty this preserves is the whole point. The host cannot make a third-party adapter
+     * stop — it can only ask, and then decide what to believe. Waiting forever means one
+     * uncooperative adapter permanently consumes an admission slot; pretending the abort worked
+     * means reporting a success we do not have, which this repo's own rules forbid. So the host
+     * abandons ITS OWN record and says so: `turn.execution.abandoned` states that the host gave up
+     * tracking, NOT that the work stopped.
+     */
+    abortAndAbandon(activeKey, reason) {
+        const active = this.activeTurns.get(activeKey);
+        if (!active)
+            return;
+        const { controller, request, adapter } = active;
+        controller.abort(reason);
+        const timer = setTimeout(() => {
+            const stillActive = this.activeTurns.get(activeKey);
+            // Only abandon the turn we aborted: a newer turn may legitimately hold this key.
+            if (!stillActive || stillActive.controller !== controller)
+                return;
+            this.activeTurns.delete(activeKey);
+            this.clearTurnTimers(activeKey);
+            this.publish('turn.execution.abandoned', {
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                adapterId: adapter.id,
+                graceMs: this.turnAbandonGraceMs,
+                safeError: 'The runtime adapter did not stop within the grace period. The XENO Agent host has '
+                    + 'stopped tracking this turn and released its capacity. The adapter may still be '
+                    + 'running.',
+            });
+        }, this.turnAbandonGraceMs);
+        timer.unref?.();
+        this.trackTurnTimer(activeKey, timer);
+    }
+    async startTurn(input) {
+        const invalidReason = validateTurnStartRequest(input);
+        if (invalidReason) {
+            return turnStartFailure('invalid_request', invalidReason, input);
+        }
+        if (!this.isConnectedClient(input.command.client)) {
+            return turnStartFailure('client_not_connected', 'The requesting surface must complete the host handshake before starting a turn.', input);
+        }
+        const commandKey = this.commandKey('turn.start', input.command);
+        const fingerprint = commandFingerprint(input);
+        const prior = this.commandResults.get(commandKey);
+        if (prior) {
+            if (prior.method !== 'turn.start' || prior.fingerprint !== fingerprint) {
+                return turnStartFailure('idempotency_conflict', 'This idempotency key was already used for a different command.', input);
+            }
+            const result = prior.result;
+            return result.success
+                ? structuredClone({ ...result, status: 'replayed' })
+                : structuredClone(result);
+        }
+        const provider = this.providers.get(input.selection.providerId);
+        if (!provider) {
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('provider_not_found', 'The selected runtime provider is no longer in the catalog.', input));
+        }
+        if (provider.catalogRevision !== input.selection.catalogRevision) {
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('catalog_revision_mismatch', 'The provider catalog changed. Refresh the model selection before starting this turn.', input));
+        }
+        const resolved = resolveAgentRuntimeSelection([provider], {
+            providerId: input.selection.providerId,
+            ...(input.selection.modelId ? { modelId: input.selection.modelId } : {}),
+            ...(input.selection.reasoningOptionId ? { reasoningOptionId: input.selection.reasoningOptionId } : {}),
+        });
+        if (!resolved.ok) {
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure(resolved.code, resolved.safeReason, input));
+        }
+        if (input.mode === 'development' && !isDevelopmentProviderReady(provider)) {
+            const missing = missingDevelopmentCapabilities(provider);
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('development_capability_missing', `The selected provider cannot run an engineering turn because it lacks: ${missing.join(', ')}.`, input));
+        }
+        if (input.execution?.toolExecution === 'disabled') {
+            // 🔴 The declaration is what makes the request honest, so it is checked BEFORE the turn is
+            // accepted rather than discovered at execution time. A lane that cannot hold an agent to a
+            // tool-free turn must not be handed one: the request and the audit record would both read as
+            // though the restriction had been honoured.
+            //
+            // ⚠️ `available` only. For most capabilities `degraded` means "works, with caveats"; a tool
+            // policy that works with caveats is not a tool policy, and there is no partial credit for
+            // mostly not executing tools.
+            const declared = provider.capabilities?.['turn.tools-disabled'];
+            if (declared?.status !== 'available') {
+                return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('development_capability_missing', declared?.reason
+                    ?? 'The selected provider cannot guarantee a turn that executes no tools.', input));
+            }
+        }
+        const adapter = [...this.turnExecutionAdapters.values()].find((candidate) => {
+            try {
+                return candidate.supports(provider);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!adapter) {
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('adapter_unavailable', 'No runnable host adapter is registered for the selected provider.', input));
+        }
+        const activeKey = turnKey(input.conversationId, input.requestId);
+        if (this.activeTurns.has(activeKey)) {
+            return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('request_already_active', 'A turn with this conversation and request ID is already active.', input));
+        }
+        // 🔴 ADMISSION — and deliberately the LAST gate.
+        //
+        // Everything above is a PERMANENT property of the request: malformed, unknown provider,
+        // stale catalog, no adapter, already active. Those must be reported regardless of load,
+        // because the caller has to change something. Capacity is TRANSIENT, so it is checked only
+        // once the request is known to be otherwise runnable — telling someone they are over the
+        // limit when their provider does not exist sends them to fix the wrong thing.
+        //
+        // Placed before `structuredClone` because nothing below is free of side effects: run
+        // contexts, observation binding, sessions and the coordination roster all begin there.
+        //
+        // It READS `activeTurns` rather than keeping its own count. That map's cleanup runs in a
+        // `finally` and is guarded against evicting a newer turn, so deriving the decision from it
+        // makes a leaked slot unrepresentable — there is no second ledger to drift out of sync.
+        const admission = evaluateTurnAdmission({
+            surface: input.command.client.surface,
+            providerId: input.selection.providerId,
+            active: [...this.activeTurns.values()].map((turn) => ({
+                surface: turn.request.command.client.surface,
+                providerId: turn.request.selection.providerId,
+            })),
+            policy: this.turnAdmissionPolicy,
+        });
+        if (!admission.admitted) {
+            // 🔴 NOT remembered, and that is the whole difference between this refusal and the ones
+            // above it. `rememberTurnStartFailure` freezes a result into the command ledger so a
+            // retried command replays it — correct for a PERMANENT fault, and wrong here. Capacity is
+            // transient: caching it would mean a surface that waits and retries the same command gets
+            // a stale "at capacity" forever, with no way back except inventing a new command id.
+            //
+            // Idempotency exists to stop duplicate EXECUTION. This refusal executed nothing, so there
+            // is nothing to deduplicate — re-evaluating on retry is the correct behaviour.
+            return turnStartFailure('concurrency_limit_reached', admission.safeError, input);
+        }
+        const request = structuredClone(input);
+        // Recorded BEFORE execution, so a coordination event arriving in the first
+        // moments of a turn still finds its conversation.
+        const contextRunId = this.resolveRunId(request);
+        if (contextRunId) {
+            this.runContexts.set(contextRunId, {
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                ...(request.workspaceId === undefined ? {} : { workspaceId: request.workspaceId }),
+                ...(request.agentId === undefined ? {} : { agentId: request.agentId }),
+                // §6's derivation input. Captured from the turn that is starting,
+                // because "the capabilities this run is executing with" is a property of
+                // the turn — and omitted entirely when the request declares none, so an
+                // undeclared posture stays UNKNOWN rather than becoming an empty set
+                // that would read as "maximally constrained".
+                ...(request.execution?.capabilities === undefined
+                    ? {}
+                    : { posture: request.execution.capabilities }),
+                // The bound for any subagent this turn spawns. Captured from the turn that is starting
+                // for the same reason as `posture`: it is a property of the turn, and a child created
+                // later must be measured against what its parent was actually granted — not against
+                // whatever the child asks for.
+                ...(request.workspace === undefined ? {} : { workspace: structuredClone(request.workspace) }),
+            });
+            // Fire and forget, and guarded: attaching a sandbox is slow and the turn
+            // is the user's actual work. A binder that throws must not be able to fail
+            // a turn — the run simply goes unobserved, which every consumer of the
+            // observation service already reports honestly.
+            try {
+                this.runObservationBinder?.begin({
+                    runId: contextRunId,
+                    conversationId: request.conversationId,
+                    ...(request.workspace?.primaryDirectory === undefined
+                        ? {}
+                        : { primaryDirectory: request.workspace.primaryDirectory }),
+                    ...(request.workspaceId === undefined ? {} : { workspaceId: request.workspaceId }),
+                    ...(request.agentId === undefined ? {} : { agentId: request.agentId }),
+                });
+            }
+            catch {
+                // Nothing to report to the caller: observation is not part of this
+                // command's contract, and the binder owns its own problem reporting.
+            }
+            this.openSessionForRun(contextRunId, provider);
+            this.registerCoordinationRun(contextRunId, 'running');
+        }
+        const controller = new AbortController();
+        this.activeTurns.set(activeKey, { adapter, controller, request });
+        // 🔴 The host ENFORCES the deadline it already validates. `timeoutMs` was checked on the way
+        // in (1..3_600_000) and forwarded to the adapter, but nothing here ever acted on it: the
+        // controller was aborted only for shutdown or an explicit cancel. A turn whose adapter
+        // ignores the timeout ran forever — and, since admission counts `activeTurns`, held its
+        // capacity forever with it. Client sets the deadline, the AUTHORITY enforces it.
+        if (request.timeoutMs !== undefined) {
+            const deadline = setTimeout(() => {
+                this.abortAndAbandon(activeKey, `Turn exceeded its ${request.timeoutMs}ms deadline.`);
+            }, request.timeoutMs);
+            deadline.unref?.();
+            this.trackTurnTimer(activeKey, deadline);
+        }
+        // Written BEFORE execution begins: a record created afterwards would miss
+        // exactly the turns that die early, which are the ones worth reporting.
+        this.interruptedTurnStore.record({
+            conversationId: request.conversationId,
+            requestId: request.requestId,
+            adapterId: adapter.id,
+            startedAt: Date.now(),
+            request,
+        });
+        const accepted = {
+            success: true,
+            status: 'accepted',
+            conversationId: input.conversationId,
+            requestId: input.requestId,
+            adapterId: adapter.id,
+            selection: { ...resolved.selection },
+        };
+        this.commandResults.set(commandKey, {
+            method: 'turn.start',
+            fingerprint,
+            result: structuredClone(accepted),
+        });
+        void Promise.resolve()
+            .then(() => this.recordContextCompaction(request, provider, resolved.selection))
+            // §5.8's gate lives here. Everything else in that pillar — the store, the
+            // selection, the cross-provider guarantee — is inert until a fact actually
+            // reaches a prompt.
+            .then(() => this.injectWorkspaceKnowledge(request))
+            // §5.2b's `message` primitive is a PUSH, and this is the push. Without
+            // it a run could send and no run could ever receive.
+            .then(() => this.deliverCoordinationMessages(request))
+            .then(() => adapter.execute(request, provider, resolved.selection, {
+            signal: controller.signal,
+            publishPersistedRuntimeEvent: (event) => this.publishPersistedRuntimeEvent(event),
+        }))
+            .then(() => {
+            // The turn ended WELL. Published here rather than inferred by each surface from
+            // provider-specific runtime event strings — see the note on the event type itself.
+            //
+            // 🔴 Guarded by controller identity, because "the adapter's promise resolved" and "this
+            // turn is still the host's turn" are different facts. An abandoned turn has already been
+            // declared over and its capacity handed to someone else; if its adapter finally returns
+            // afterwards, reporting completion would give a turn TWO terminal events and contradict
+            // what the host already told every surface. Late is not the same as successful.
+            if (this.activeTurns.get(activeKey)?.controller !== controller)
+                return;
+            this.publish('turn.execution.completed', {
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                adapterId: adapter.id,
+            });
+        })
+            .catch(() => {
+            // Same guard, same reason: an abandoned turn whose adapter later rejects must not add a
+            // second terminal event either.
+            if (this.activeTurns.get(activeKey)?.controller !== controller)
+                return;
+            this.publish('turn.execution.failed', {
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                adapterId: adapter.id,
+                safeError: 'The selected runtime adapter failed to execute the turn.',
+            });
+        })
+            .finally(() => {
+            const active = this.activeTurns.get(activeKey);
+            if (active?.controller === controller)
+                this.activeTurns.delete(activeKey);
+            // Before anything else: a turn that settled must not be abandoned afterwards by a timer
+            // that was already in flight.
+            this.clearTurnTimers(activeKey);
+            // Reaching here at all means the turn ended — well or badly. Either way
+            // it was not interrupted by process death, which is the only thing this
+            // record exists to describe.
+            this.interruptedTurnStore.clear(request.conversationId, request.requestId);
+            // Gate 8: a delivered message is the receiving run's cause "until its
+            // turn ends", so this is where that ends. In `finally`, because a turn
+            // that FAILED still ended — leaving the cause set would attribute the
+            // run's next, unrelated work to a message it already finished acting on.
+            //
+            // `endTurn`, never `endRun`: see `resolveRunId`. Releasing claims here
+            // would drop a live run's locks every time a turn completed.
+            const runId = this.resolveRunId(request);
+            if (runId) {
+                this.coordinationService?.endTurn(runId);
+                // \u{1F534} `idle`, not gone. A run outlives its turns — the same reason
+                // `endTurn` is called here and `endRun` is not — and a peer that
+                // vanished between turns would be unaddressable exactly when someone
+                // wanted to hand it work.
+                this.registerCoordinationRun(runId, 'idle');
+            }
+        });
+        return structuredClone(accepted);
+    }
+    async recordContextCompaction(request, provider, selection) {
+        const compaction = request.contextCompaction;
+        if (!compaction || compaction.compactedMessageCount < 1)
+            return;
+        const draft = {
+            conversationId: request.conversationId,
+            requestId: request.requestId,
+            ...(request.workspaceId ? { workspaceId: request.workspaceId } : {}),
+            ...(request.teamId ? { teamId: request.teamId } : {}),
+            ...(request.agentId ? { agentId: request.agentId } : {}),
+            ...(request.subagentRunId ? { subagentRunId: request.subagentRunId } : {}),
+            providerKind: provider.kind,
+            providerId: provider.id,
+            source: 'agent-host',
+            schemaVersion: '1',
+            redactionState: 'safe',
+            event: {
+                id: `context-compacted-${request.requestId}-${safeEventIdSegment(compaction.contextDigest)}`,
+                type: 'context.compacted',
+                timestamp: new Date().toISOString(),
+                strategyVersion: compaction.strategyVersion,
+                rawMessageCount: compaction.rawMessageCount,
+                sentMessageCount: compaction.sentMessageCount,
+                compactedMessageCount: compaction.compactedMessageCount,
+                estimatedRawTokens: compaction.estimatedRawTokens,
+                estimatedSentTokens: compaction.estimatedSentTokens,
+                retainedAnchorCount: compaction.retainedAnchorCount,
+                retainedArtifactCount: compaction.retainedArtifactCount,
+                retainedGrantedDirectoryCount: compaction.retainedGrantedDirectoryCount,
+                contextDigest: compaction.contextDigest,
+                selection: {
+                    providerId: selection.providerId,
+                    catalogRevision: selection.catalogRevision,
+                    ...(selection.modelId ? { modelId: selection.modelId } : {}),
+                    ...(selection.reasoningOptionId ? { reasoningOptionId: selection.reasoningOptionId } : {}),
+                    ...(selection.runtimeModelId ? { runtimeModelId: selection.runtimeModelId } : {}),
+                },
+            },
+        };
+        if (this.runtimeEventRepository) {
+            const result = await this.runtimeEventRepository.appendGenerated(draft);
+            if (result.inserted) {
+                this.publish('runtime.event.appended', {
+                    requestId: result.event.requestId,
+                    event: structuredClone(result.event),
+                });
+            }
+            return;
+        }
+        const sequence = [...this.runtimeEvents.values()]
+            .filter((event) => event.conversationId === request.conversationId)
+            .reduce((maximum, event) => Math.max(maximum, event.sequence), 0) + 1;
+        this.appendRuntimeEvent({
+            id: draft.event.id,
+            type: draft.event.type,
+            timestamp: draft.event.timestamp,
+            sequence,
+            conversationId: draft.conversationId,
+            requestId: draft.requestId,
+            ...(draft.workspaceId ? { workspaceId: draft.workspaceId } : {}),
+            ...(draft.teamId ? { teamId: draft.teamId } : {}),
+            ...(draft.agentId ? { agentId: draft.agentId } : {}),
+            ...(draft.parentRunId ? { parentRunId: draft.parentRunId } : {}),
+            ...(draft.subagentRunId ? { subagentRunId: draft.subagentRunId } : {}),
+            ...(draft.providerKind ? { providerKind: draft.providerKind } : {}),
+            ...(draft.providerId ? { providerId: draft.providerId } : {}),
+            source: draft.source || 'agent-host',
+            schemaVersion: draft.schemaVersion || '1',
+            redactionState: draft.redactionState || 'safe',
+            event: structuredClone(draft.event),
+        }, true);
+    }
+    async cancelTurn(input) {
+        const invalidReason = validateTurnCancelRequest(input);
+        if (invalidReason) {
+            return turnCancelFailure('invalid_request', invalidReason, input);
+        }
+        if (!this.isConnectedClient(input.command.client)) {
+            return turnCancelFailure('client_not_connected', 'The requesting surface must complete the host handshake before cancelling a turn.', input);
+        }
+        const commandKey = this.commandKey('turn.cancel', input.command);
+        const fingerprint = commandFingerprint(input);
+        const prior = this.commandResults.get(commandKey);
+        if (prior) {
+            if (prior.method !== 'turn.cancel' || prior.fingerprint !== fingerprint) {
+                return turnCancelFailure('idempotency_conflict', 'This idempotency key was already used for a different command.', input);
+            }
+            const result = prior.result;
+            return result.success
+                ? structuredClone({ ...result, status: 'replayed' })
+                : structuredClone(result);
+        }
+        const active = this.activeTurns.get(turnKey(input.conversationId, input.requestId));
+        if (!active) {
+            const failure = turnCancelFailure('turn_not_active', 'The requested turn is not active on this host.', input);
+            this.commandResults.set(commandKey, { method: 'turn.cancel', fingerprint, result: structuredClone(failure) });
+            return failure;
+        }
+        // Abort, then stop counting it if the adapter does not comply. `turn.cancel` used to return
+        // success while the turn stayed active and stayed counted against admission — reporting a
+        // success the host did not have.
+        this.abortAndAbandon(turnKey(input.conversationId, input.requestId), input.reason || 'Turn cancelled by the user.');
+        if (active.adapter.cancel) {
+            try {
+                await active.adapter.cancel(structuredClone(input));
+            }
+            catch {
+                // The shared abort signal is authoritative; provider-specific cancellation is best-effort.
+            }
+        }
+        const result = {
+            success: true,
+            status: 'cancel_requested',
+            conversationId: input.conversationId,
+            requestId: input.requestId,
+        };
+        this.commandResults.set(commandKey, { method: 'turn.cancel', fingerprint, result: structuredClone(result) });
+        return result;
+    }
+    async steerTurn(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return {
+                success: false,
+                code: 'client_not_connected',
+                safeError: 'The requesting surface must complete the host handshake before steering a turn.',
+                conversationId: input.conversationId,
+                requestId: input.requestId,
+            };
+        }
+        const instruction = typeof input.instruction === 'string' ? input.instruction.trim() : '';
+        if (!input.conversationId || !input.requestId || !instruction) {
+            return {
+                success: false,
+                code: 'invalid_request',
+                safeError: 'Steering requires a conversation id, a request id and non-empty text.',
+                conversationId: input.conversationId,
+                requestId: input.requestId,
+            };
+        }
+        const commandKey = this.commandKey('turn.steer', input.command);
+        const fingerprint = commandFingerprint(input);
+        const prior = this.commandResults.get(commandKey);
+        if (prior) {
+            if (prior.method !== 'turn.steer' || prior.fingerprint !== fingerprint) {
+                return {
+                    success: false,
+                    code: 'idempotency_conflict',
+                    safeError: 'This idempotency key was already used for a different command.',
+                    conversationId: input.conversationId,
+                    requestId: input.requestId,
+                };
+            }
+            const result = prior.result;
+            return result.success
+                ? structuredClone({ ...result, status: 'replayed' })
+                : structuredClone(result);
+        }
+        const active = this.activeTurns.get(turnKey(input.conversationId, input.requestId));
+        if (!active) {
+            // Not an error the user should be punished for: the turn most likely just
+            // ended. `turn.queue` is the right destination, and the message says so.
+            const failure = {
+                success: false,
+                code: 'turn_not_active',
+                safeError: 'That turn is no longer running. Queue the instruction instead so it is delivered to the next turn.',
+                conversationId: input.conversationId,
+                requestId: input.requestId,
+            };
+            this.commandResults.set(commandKey, { method: 'turn.steer', fingerprint, result: structuredClone(failure) });
+            return failure;
+        }
+        if (!active.adapter.steer) {
+            /**
+             * 🔴 THE REMEDY IS DERIVED, NOT NAMED BY HAND.
+             *
+             * This used to read "… or run the agent over ACP where steering is acknowledged", and it was
+             * returned FOR AN ACP LANE — measured against a real host on 2026-08-18. The ACP adapter
+             * implements no `steer`; the SDK-native one does. So the advice named the single lane that
+             * cannot do it, to someone already on it.
+             *
+             * An error that misdirects is worse than a generic one: it spends the reader's time proving
+             * the system wrong before they can start. Same shape as a package name retyped into a path —
+             * a fact that already exists in the code, restated by hand, then drifting.
+             */
+            const steerable = [...this.turnExecutionAdapters.values()]
+                .filter((adapter) => typeof adapter.steer === 'function')
+                .map((adapter) => adapter.id);
+            const failure = {
+                success: false,
+                code: 'steer_unsupported',
+                safeError: steerable.length > 0
+                    ? `The '${active.adapter.id}' lane cannot accept a correction mid-turn. Queue the `
+                        + `instruction so it reaches the next turn, or run this agent on a lane that can: `
+                        + `${steerable.join(', ')}.`
+                    : `The '${active.adapter.id}' lane cannot accept a correction mid-turn, and no lane on `
+                        + 'this host can. Queue the instruction so it reaches the next turn.',
+                conversationId: input.conversationId,
+                requestId: input.requestId,
+            };
+            this.commandResults.set(commandKey, { method: 'turn.steer', fingerprint, result: structuredClone(failure) });
+            return failure;
+        }
+        try {
+            await active.adapter.steer({ ...structuredClone(input), instruction });
+        }
+        catch (error) {
+            // A failed steer is reported, never swallowed: the user must not believe
+            // they corrected an agent that never heard them.
+            const failure = {
+                success: false,
+                code: 'steer_unsupported',
+                safeError: error instanceof Error && error.message
+                    ? `The provider rejected the correction: ${error.message.slice(0, 300)}`
+                    : 'The provider rejected the correction.',
+                conversationId: input.conversationId,
+                requestId: input.requestId,
+            };
+            this.commandResults.set(commandKey, { method: 'turn.steer', fingerprint, result: structuredClone(failure) });
+            return failure;
+        }
+        const result = {
+            success: true,
+            status: 'delivered',
+            acknowledged: true,
+            deliveredVia: 'adapter',
+            conversationId: input.conversationId,
+            requestId: input.requestId,
+        };
+        this.commandResults.set(commandKey, { method: 'turn.steer', fingerprint, result: structuredClone(result) });
+        return result;
+    }
+    /** True while any turn is running for this conversation. */
+    hasActiveTurn(conversationId) {
+        for (const active of this.activeTurns.values()) {
+            if (active.request.conversationId === conversationId)
+                return true;
+        }
+        return false;
+    }
+    queueSnapshot(conversationId) {
+        return structuredClone(this.queuedInstructions.get(conversationId) || []);
+    }
+    queueTurnInstruction(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return {
+                success: false,
+                code: 'client_not_connected',
+                safeError: 'The requesting surface must complete the host handshake before queueing an instruction.',
+                conversationId: input.conversationId,
+            };
+        }
+        const instruction = typeof input.instruction === 'string' ? input.instruction.trim() : '';
+        if (!input.conversationId || !instruction) {
+            return {
+                success: false,
+                code: 'invalid_request',
+                safeError: 'A queued instruction requires a conversation id and non-empty text.',
+                conversationId: input.conversationId,
+            };
+        }
+        const commandKey = this.commandKey('turn.queue', input.command);
+        const fingerprint = commandFingerprint(input);
+        const prior = this.commandResults.get(commandKey);
+        if (prior) {
+            if (prior.method !== 'turn.queue' || prior.fingerprint !== fingerprint) {
+                return {
+                    success: false,
+                    code: 'idempotency_conflict',
+                    safeError: 'This idempotency key was already used for a different command.',
+                    conversationId: input.conversationId,
+                };
+            }
+            const result = prior.result;
+            return result.success
+                ? structuredClone({ ...result, status: 'replayed' })
+                : structuredClone(result);
+        }
+        const existing = input.replace ? [] : (this.queuedInstructions.get(input.conversationId) || []);
+        if (existing.length >= MAX_QUEUED_INSTRUCTIONS) {
+            const failure = {
+                success: false,
+                code: 'queue_full',
+                safeError: `At most ${MAX_QUEUED_INSTRUCTIONS} instructions may be queued for one conversation.`,
+                conversationId: input.conversationId,
+            };
+            this.commandResults.set(commandKey, { method: 'turn.queue', fingerprint, result: structuredClone(failure) });
+            return failure;
+        }
+        this.queuedInstructionSequence += 1;
+        const queued = {
+            id: `queued-${this.queuedInstructionSequence}`,
+            instruction: instruction.slice(0, MAX_QUEUED_INSTRUCTION_LENGTH),
+            queuedAt: new Date().toISOString(),
+            queuedByInstanceId: input.command.client.instanceId,
+        };
+        this.queuedInstructions.set(input.conversationId, [...existing, queued]);
+        const result = {
+            success: true,
+            status: 'queued',
+            conversationId: input.conversationId,
+            queue: this.queueSnapshot(input.conversationId),
+        };
+        this.commandResults.set(commandKey, { method: 'turn.queue', fingerprint, result: structuredClone(result) });
+        return result;
+    }
+    listQueuedInstructions(input) {
+        return {
+            conversationId: input.conversationId,
+            queue: this.queueSnapshot(input.conversationId),
+            turnActive: this.hasActiveTurn(input.conversationId),
+        };
+    }
+    dropQueuedInstruction(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return {
+                success: false,
+                code: 'client_not_connected',
+                safeError: 'The requesting surface must complete the host handshake before changing the queue.',
+                conversationId: input.conversationId,
+            };
+        }
+        if (!input.conversationId) {
+            return {
+                success: false,
+                code: 'invalid_request',
+                safeError: 'A conversation id is required.',
+            };
+        }
+        const existing = this.queuedInstructions.get(input.conversationId) || [];
+        if (input.instructionId === undefined) {
+            this.queuedInstructions.delete(input.conversationId);
+            return { success: true, conversationId: input.conversationId, queue: [] };
+        }
+        if (!existing.some((entry) => entry.id === input.instructionId)) {
+            return {
+                success: false,
+                code: 'not_found',
+                safeError: 'No queued instruction with that id exists for this conversation.',
+                conversationId: input.conversationId,
+            };
+        }
+        this.queuedInstructions.set(input.conversationId, existing.filter((entry) => entry.id !== input.instructionId));
+        return {
+            success: true,
+            conversationId: input.conversationId,
+            queue: this.queueSnapshot(input.conversationId),
+        };
+    }
+    rememberTurnStartFailure(commandKey, fingerprint, result) {
+        this.commandResults.set(commandKey, { method: 'turn.start', fingerprint, result: structuredClone(result) });
+        return result;
+    }
+    commandKey(method, command) {
+        return `${command.client.instanceId}:${method}:${command.idempotencyKey}`;
+    }
+    isConnectedClient(identity) {
+        const connected = this.connectedClients.get(identity.instanceId);
+        return !!connected
+            && connected.clientId === identity.clientId
+            && connected.clientVersion === identity.clientVersion
+            && connected.surface === identity.surface;
+    }
+    handshake(input) {
+        if (!isAgentHostClientIdentity(input.identity)) {
+            throw new AgentHostProtocolError('invalid_handshake', 'Agent host client identity is invalid.');
+        }
+        if (!isProtocolRange(input.supportedProtocol)) {
+            throw new AgentHostProtocolError('invalid_handshake', 'Agent host client protocol range is invalid.');
+        }
+        const hostRange = {
+            min: XENO_AGENT_HOST_MIN_PROTOCOL_VERSION,
+            max: XENO_AGENT_HOST_PROTOCOL_VERSION,
+        };
+        if (!rangesOverlap(hostRange, input.supportedProtocol)) {
+            throw new AgentHostProtocolError('protocol_mismatch', `Client protocol ${input.supportedProtocol.min}-${input.supportedProtocol.max} is incompatible with host ${hostRange.min}-${hostRange.max}.`);
+        }
+        this.connectedClients.set(input.identity.instanceId, { ...input.identity });
+        // Recorded per connection, and re-recorded on every handshake so a reconnecting client
+        // cannot inherit what a previous connection with the same instance id claimed.
+        this.clientCapabilities.set(input.identity.instanceId, {
+            canPresentElicitations: input.capabilities?.canPresentElicitations === true,
+        });
+        return {
+            protocol: {
+                current: XENO_AGENT_HOST_PROTOCOL_VERSION,
+                supported: hostRange,
+            },
+            host: {
+                instanceId: this.options.hostInstanceId,
+                version: this.options.hostVersion,
+                authority: 'primary',
+                processBoundary: this.options.processBoundary,
+            },
+            storage: {
+                owner: 'xeno-agent-host',
+                schemaVersion: this.options.storageSchemaVersion,
+                eventSchemaVersion: this.options.eventSchemaVersion,
+            },
+            surface: { ...input.identity },
+        };
+    }
+    listProviders(input) {
+        return {
+            revision: String(this.catalogRevision),
+            providers: selectAvailableProviders([...this.providers.values()], input.includeUnavailable === true),
+        };
+    }
+    async refreshProviderCatalog() {
+        if (!this.providerCatalogLoader)
+            return false;
+        if (this.providerCatalogRefresh)
+            return this.providerCatalogRefresh;
+        this.providerCatalogRefresh = (async () => {
+            const providers = await this.providerCatalogLoader();
+            if (!isAgentProviderListResult({ revision: 'candidate', providers })) {
+                throw new AgentHostProtocolError('invalid_response', 'Provider catalog source returned an invalid descriptor.');
+            }
+            const providerIds = new Set();
+            for (const provider of providers) {
+                if (providerIds.has(provider.id)) {
+                    throw new AgentHostProtocolError('invalid_response', `Provider catalog source returned duplicate id: ${provider.id}`);
+                }
+                providerIds.add(provider.id);
+            }
+            const nextFingerprint = fingerprintProviders(providers);
+            if (nextFingerprint === this.providerCatalogFingerprint)
+                return false;
+            this.providers.clear();
+            for (const provider of providers)
+                this.providers.set(provider.id, cloneProvider(provider));
+            this.providerCatalogFingerprint = nextFingerprint;
+            this.catalogRevision += 1;
+            this.publishCatalogChange();
+            return true;
+        })().finally(() => {
+            this.providerCatalogRefresh = null;
+        });
+        return this.providerCatalogRefresh;
+    }
+    async listRuntimeEvents(input) {
+        if (!input.conversationId.trim()) {
+            throw new AgentHostProtocolError('invalid_response', 'conversationId is required to list runtime events.');
+        }
+        if (this.runtimeEventRepository) {
+            return this.runtimeEventRepository.list(structuredClone(input));
+        }
+        const limit = normalizeEventLimit(input.limit);
+        const events = [...this.runtimeEvents.values()]
+            .filter((event) => event.conversationId === input.conversationId)
+            .filter((event) => !input.requestId || event.requestId === input.requestId)
+            .filter((event) => !input.subagentRunId || event.subagentRunId === input.subagentRunId)
+            .filter((event) => !input.type || event.type === input.type)
+            .filter((event) => input.afterSequence === undefined || event.sequence > input.afterSequence)
+            .sort((left, right) => left.sequence - right.sequence || left.id.localeCompare(right.id))
+            .slice(0, limit)
+            .map((event) => structuredClone(event));
+        return {
+            events,
+            nextSequence: events.length > 0 ? events[events.length - 1]?.sequence ?? null : null,
+        };
+    }
+    requireStateRepository() {
+        if (!this.stateRepository) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned Agent state persistence is unavailable.');
+        }
+        return this.stateRepository;
+    }
+    requireWorkspaceService() {
+        if (!this.workspaceService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned workspace services are unavailable.');
+        }
+        return this.workspaceService;
+    }
+    requireInteractionService() {
+        if (!this.interactionService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned Agent interaction services are unavailable.');
+        }
+        return this.interactionService;
+    }
+    /**
+     * Re-issues a turn that process death interrupted (§5.5).
+     *
+     * ⚠️ It RESTARTS rather than resumes, and says so in the result. A turn killed
+     * with the process left no continuation point inside the agent — only the
+     * request that produced it. Work already done is done again, and side effects
+     * already performed have already happened. Where the request carries a
+     * provider continuation the session is picked up, which narrows the gap
+     * without closing it.
+     *
+     * Everything after the lookup goes through `startTurn`, deliberately: a
+     * second execution path would be free to drift from the first on provider
+     * validation, catalog revision, adapter selection and idempotency — and the
+     * one that runs rarely is the one that would rot.
+     */
+    /**
+     * Approve or revoke an ACP provider's binary.
+     *
+     * Fails CLOSED and by name in every branch. The shipping app previously
+     * rendered an enabled Approve button whose bridge answered "not available on
+     * this host yet" — a message that was true of the bridge and false of the
+     * host, which implements this. `unavailable` here means the host genuinely
+     * has no approval service mounted, and says so.
+     */
+    async approveAcpProvider(input) {
+        const agentId = typeof input?.agentId === 'string' ? input.agentId.trim() : '';
+        if (!input?.client || !this.isConnectedClient(input.client)) {
+            return {
+                success: false,
+                status: 'failed',
+                agentId,
+                safeError: 'Complete the host handshake before approving a provider.',
+            };
+        }
+        if (!agentId) {
+            return {
+                success: false,
+                status: 'failed',
+                agentId,
+                safeError: 'Provider approval needs the id of a configured ACP agent.',
+            };
+        }
+        if (input.action !== 'approve' && input.action !== 'revoke') {
+            // Not defaulted to `approve`: guessing an unrecognised action would be
+            // guessing at a trust decision.
+            return {
+                success: false,
+                status: 'failed',
+                agentId,
+                safeError: 'Provider approval action must be approve or revoke.',
+            };
+        }
+        if (!this.acpApprovalService) {
+            return {
+                success: false,
+                status: 'unavailable',
+                agentId,
+                safeError: 'This host has no ACP approval service mounted.',
+            };
+        }
+        try {
+            return await this.acpApprovalService.approveProvider({
+                agentId,
+                ...(typeof input.providerId === 'string' && input.providerId
+                    ? { providerId: input.providerId }
+                    : {}),
+                action: input.action,
+            });
+        }
+        catch {
+            // The underlying service spawns a CLI. A thrown error carries a command
+            // line and environment; neither belongs on a surface.
+            return {
+                success: false,
+                status: 'failed',
+                agentId,
+                safeError: 'The provider approval command failed to run.',
+            };
+        }
+    }
+    async resumeTurn(input) {
+        if (!input?.command?.client || !this.isConnectedClient(input.command.client)) {
+            return {
+                success: false,
+                code: 'client_not_connected',
+                safeError: 'Complete the host handshake before resuming a turn.',
+            };
+        }
+        const conversationId = typeof input?.conversationId === 'string' ? input.conversationId.trim() : '';
+        const requestId = typeof input?.requestId === 'string' ? input.requestId.trim() : '';
+        if (!conversationId || !requestId) {
+            return {
+                success: false,
+                code: 'invalid_request',
+                safeError: 'A turn resume needs both a conversation id and a request id.',
+            };
+        }
+        if (this.activeTurns.has(turnKey(conversationId, requestId))) {
+            // Restarting a live turn would run it twice against the same workspace.
+            return {
+                success: false,
+                code: 'turn_already_active',
+                safeError: 'That turn is already running.',
+                conversationId,
+                requestId,
+            };
+        }
+        const record = this.interruptedTurnStore.list()
+            .find((entry) => entry.conversationId === conversationId && entry.requestId === requestId);
+        if (!record) {
+            // Absence is reported by name rather than as a generic failure: "this turn
+            // was never interrupted" and "resuming it failed" are different answers.
+            return {
+                success: false,
+                code: 'not_interrupted',
+                safeError: 'No interrupted turn is recorded for that request.',
+                conversationId,
+                requestId,
+            };
+        }
+        const started = await this.startTurn(record.request);
+        if (!started.success) {
+            return {
+                success: false,
+                code: 'resume_failed',
+                safeError: started.safeError,
+                conversationId,
+                requestId,
+            };
+        }
+        return {
+            success: true,
+            status: 'restarted',
+            conversationId,
+            requestId,
+            adapterId: started.adapterId,
+        };
+    }
+    /**
+     * Reports turns that were running when the previous process ended (§5.5).
+     *
+     * Called by the composition after construction. Each surviving record is
+     * journalled as a durable `turn.interrupted` runtime event, so the surface
+     * shows "this turn was interrupted" instead of a turn that simply stops
+     * mid-sentence and never says why. An absence indistinguishable from an
+     * outcome is the failure this whole mechanism exists to remove.
+     *
+     * Records are NOT cleared: `turn.resume` needs them. They clear when the turn
+     * reaches a terminal state, which a resumed turn eventually does.
+     */
+    async reportInterruptedTurns() {
+        const records = this.interruptedTurnStore.list();
+        if (records.length === 0 || !this.runtimeEventRepository)
+            return 0;
+        let reported = 0;
+        for (const entry of records) {
+            try {
+                const committed = await this.runtimeEventRepository.appendGenerated({
+                    conversationId: entry.conversationId,
+                    requestId: entry.requestId,
+                    source: 'host',
+                    event: {
+                        id: `${entry.requestId}:turn-interrupted`,
+                        type: 'turn.interrupted',
+                        timestamp: new Date().toISOString(),
+                        status: 'interrupted',
+                        adapterId: entry.adapterId,
+                        startedAt: entry.startedAt,
+                        resumable: true,
+                    },
+                });
+                this.publishPersistedRuntimeEvent(committed.event);
+                reported += 1;
+            }
+            catch {
+                // One unreportable turn must not hide the rest.
+            }
+        }
+        return reported;
+    }
+    requirePermissionPolicyService() {
+        if (!this.permissionPolicyService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned permission policy is unavailable.');
+        }
+        return this.permissionPolicyService;
+    }
+    requireSdkControlService() {
+        if (!this.sdkControlService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned SDK session controls are unavailable.');
+        }
+        return this.sdkControlService;
+    }
+    requireEngineeringControlService() {
+        if (!this.engineeringControlService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned engineering workbench controls are unavailable.');
+        }
+        return this.engineeringControlService;
+    }
+    assertWorkspaceClient(input) {
+        if (!isRecord(input) || !isAgentHostClientIdentity(input.client) || !this.isConnectedClient(input.client)) {
+            throw new AgentHostProtocolError('invalid_response', 'The requesting surface must complete the host handshake before using workspace services.');
+        }
+    }
+    assertSdkControlClient(input) {
+        if (!isRecord(input) || !isAgentHostClientIdentity(input.client) || !this.isConnectedClient(input.client)) {
+            throw new AgentHostProtocolError('invalid_response', 'The requesting surface must complete the host handshake before using SDK session controls.');
+        }
+    }
+    assertEngineeringControlClient(input) {
+        if (!isRecord(input) || !isAgentHostClientIdentity(input.client) || !this.isConnectedClient(input.client)) {
+            throw new AgentHostProtocolError('invalid_response', 'The requesting surface must complete the host handshake before using engineering workbench controls.');
+        }
+    }
+    setProvider(provider, publish) {
+        if (!provider.id.trim())
+            throw new Error('Provider id must not be empty.');
+        /**
+         * 🔴 A provider cannot advertise a capability the HOST does not have.
+         *
+         * Coordination is a property of this host — whether a service is mounted —
+         * and no adapter can make it true by declaring it. Registration is the right
+         * place because it is the only point every provider passes through,
+         * including ones a composition adds later.
+         */
+        const stored = cloneProvider(provider);
+        stored.capabilities = withHostBackedCapabilities(stored.capabilities, {
+            coordination: this.coordinationService !== undefined,
+        });
+        this.providers.set(provider.id, stored);
+        this.catalogRevision += 1;
+        if (publish)
+            this.publishCatalogChange();
+    }
+    publishCatalogChange() {
+        this.publish('provider.catalog.changed', {
+            revision: String(this.catalogRevision),
+            providerIds: [...this.providers.keys()].sort(),
+        });
+    }
+    appendRuntimeEvent(event, publish) {
+        assertRuntimeEventForHost(event);
+        if (this.runtimeEvents.has(event.id))
+            return false;
+        const copy = structuredClone(event);
+        this.runtimeEvents.set(copy.id, copy);
+        if (publish)
+            this.publish('runtime.event.appended', { requestId: copy.requestId, event: copy });
+        return true;
+    }
+    /**
+     * Writes one coordination event to the run timeline.
+     *
+     * Silent when the run has no known conversation — a coordination event
+     * addressed to a run this host never started a turn for has no timeline to
+     * join, and inventing a conversation id would put the entry somewhere a
+     * reviewer would never look. It stays on the live feed either way.
+     */
+    async recordCoordinationEvent(event, text) {
+        if (!this.runtimeEventRepository)
+            return;
+        const runId = coordinationSubjectRun(event);
+        const context = this.runContexts.get(runId);
+        if (!context)
+            return;
+        this.coordinationEventSequence += 1;
+        const draft = coordinationRuntimeEventDraft(event, context, {
+            id: `${this.options.hostInstanceId}:coordination:${this.coordinationEventSequence}`,
+            timestamp: new Date().toISOString(),
+            ...(text === undefined ? {} : { text }),
+        });
+        try {
+            const { inserted, event: envelope } = await this.runtimeEventRepository.appendGenerated(draft);
+            if (inserted)
+                this.publishPersistedRuntimeEvent(envelope);
+        }
+        catch {
+            // A timeline write must not take the coordination call down with it: the
+            // message was already sent and the claim already taken, so throwing here
+            // would report a failure for work that succeeded.
+        }
+    }
+    publish(type, payload) {
+        this.sequence += 1;
+        const event = {
+            id: `${this.options.hostInstanceId}:${this.sequence}`,
+            sequence: this.sequence,
+            timestamp: Date.now(),
+            type,
+            source: 'host',
+            schemaVersion: 1,
+            redactionState: 'safe',
+            payload,
+        };
+        for (const listener of [...this.listeners])
+            listener(event);
+    }
+}
+function fingerprintProviders(providers) {
+    return JSON.stringify(providers
+        .map((provider) => cloneProvider(provider))
+        .sort((left, right) => left.id.localeCompare(right.id)));
+}
+function assertRuntimeEventForHost(value) {
+    if (!isAgentRuntimeEventEnvelope(value)) {
+        throw new AgentHostProtocolError('invalid_response', 'Runtime event does not satisfy the host contract.');
+    }
+    if (value.redactionState === 'unsafe') {
+        throw new AgentHostProtocolError('invalid_response', 'Unsafe runtime events cannot enter host history.');
+    }
+}
+function rangesOverlap(left, right) {
+    return left.min <= right.max && right.min <= left.max;
+}
+function isProtocolRange(value) {
+    return Number.isInteger(value.min) && Number.isInteger(value.max) && value.min > 0 && value.max >= value.min;
+}
+function normalizeEventLimit(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.min(5_000, Math.max(1, Math.floor(value)))
+        : 500;
+}
+function validateTurnStartRequest(value) {
+    if (!isRecord(value))
+        return 'Turn start input must be an object.';
+    const commandError = validateHostCommand(value.command);
+    if (commandError)
+        return commandError;
+    if (!isNonEmptyString(value.conversationId))
+        return 'conversationId is required.';
+    if (!isNonEmptyString(value.requestId))
+        return 'requestId is required.';
+    if (value.mode !== 'development' && value.mode !== 'chat')
+        return 'mode must be development or chat.';
+    if (!isRecord(value.selection))
+        return 'selection is required.';
+    if (!isNonEmptyString(value.selection.providerId))
+        return 'selection.providerId is required.';
+    if (!isNonEmptyString(value.selection.catalogRevision))
+        return 'selection.catalogRevision is required.';
+    if (!isNonEmptyString(value.prompt))
+        return 'prompt is required.';
+    if (value.history !== undefined) {
+        if (!Array.isArray(value.history))
+            return 'history must be an array.';
+        for (const message of value.history) {
+            if (!isRecord(message)
+                || (message.role !== 'user' && message.role !== 'assistant')
+                || typeof message.content !== 'string') {
+                return 'history contains an invalid message.';
+            }
+        }
+    }
+    if (value.workspace !== undefined) {
+        if (!isRecord(value.workspace))
+            return 'workspace must be an object.';
+        if (value.workspace.primaryDirectory !== undefined && !isNonEmptyString(value.workspace.primaryDirectory)) {
+            return 'workspace.primaryDirectory must be a non-empty path.';
+        }
+        if (value.workspace.additionalDirectories !== undefined
+            && (!Array.isArray(value.workspace.additionalDirectories)
+                || value.workspace.additionalDirectories.some((entry) => !isNonEmptyString(entry)))) {
+            return 'workspace.additionalDirectories must contain non-empty paths.';
+        }
+        if (value.workspace.filesystem !== undefined
+            && value.workspace.filesystem !== 'read-only'
+            && value.workspace.filesystem !== 'workspace-write') {
+            return 'workspace.filesystem is invalid.';
+        }
+    }
+    if (value.execution !== undefined) {
+        if (!isRecord(value.execution))
+            return 'execution must be an object.';
+        if (value.execution.maxIterations !== undefined
+            && (typeof value.execution.maxIterations !== 'number'
+                || !Number.isInteger(value.execution.maxIterations)
+                || value.execution.maxIterations < 1
+                || value.execution.maxIterations > 100)) {
+            return 'execution.maxIterations must be an integer between 1 and 100.';
+        }
+        if (value.execution.enableThinking !== undefined
+            && typeof value.execution.enableThinking !== 'boolean') {
+            return 'execution.enableThinking must be a boolean.';
+        }
+        if (value.execution.capabilities !== undefined) {
+            if (!isRecord(value.execution.capabilities)
+                || Object.values(value.execution.capabilities).some((entry) => typeof entry !== 'boolean')) {
+                return 'execution.capabilities must contain only boolean values.';
+            }
+        }
+        if (value.execution.approvalRules !== undefined
+            && (!Array.isArray(value.execution.approvalRules)
+                || value.execution.approvalRules.some((entry) => !isRecord(entry)))) {
+            return 'execution.approvalRules must contain objects.';
+        }
+    }
+    if (value.contextCompaction !== undefined) {
+        if (!isRecord(value.contextCompaction))
+            return 'contextCompaction must be an object.';
+        const integerFields = [
+            'strategyVersion',
+            'rawMessageCount',
+            'sentMessageCount',
+            'compactedMessageCount',
+            'estimatedRawTokens',
+            'estimatedSentTokens',
+            'retainedAnchorCount',
+            'retainedArtifactCount',
+            'retainedGrantedDirectoryCount',
+        ];
+        for (const field of integerFields) {
+            const fieldValue = value.contextCompaction[field];
+            if (typeof fieldValue !== 'number'
+                || !Number.isSafeInteger(fieldValue)
+                || fieldValue < (field === 'strategyVersion' ? 1 : 0)) {
+                return `contextCompaction.${field} must be a non-negative safe integer.`;
+            }
+        }
+        if (!isNonEmptyString(value.contextCompaction.contextDigest)
+            || value.contextCompaction.contextDigest.length > 160
+            || !/^[a-z0-9]+:[a-f0-9]+$/i.test(value.contextCompaction.contextDigest)) {
+            return 'contextCompaction.contextDigest is invalid.';
+        }
+        const rawMessageCount = Number(value.contextCompaction.rawMessageCount);
+        const sentMessageCount = Number(value.contextCompaction.sentMessageCount);
+        const compactedMessageCount = Number(value.contextCompaction.compactedMessageCount);
+        if (sentMessageCount > rawMessageCount
+            || compactedMessageCount !== rawMessageCount - sentMessageCount) {
+            return 'contextCompaction message counts are inconsistent.';
+        }
+    }
+    if (value.timeoutMs !== undefined
+        && (typeof value.timeoutMs !== 'number'
+            || !Number.isFinite(value.timeoutMs)
+            || value.timeoutMs < 1
+            || value.timeoutMs > 3_600_000)) {
+        return 'timeoutMs must be between 1 and 3600000.';
+    }
+    return null;
+}
+function validateTurnCancelRequest(value) {
+    if (!isRecord(value))
+        return 'Turn cancel input must be an object.';
+    const commandError = validateHostCommand(value.command);
+    if (commandError)
+        return commandError;
+    if (!isNonEmptyString(value.conversationId))
+        return 'conversationId is required.';
+    if (!isNonEmptyString(value.requestId))
+        return 'requestId is required.';
+    if (value.reason !== undefined && typeof value.reason !== 'string')
+        return 'reason must be a string.';
+    return null;
+}
+function validateHostCommand(value) {
+    if (!isRecord(value))
+        return 'command context is required.';
+    if (value.schemaVersion !== 1)
+        return 'command.schemaVersion must be 1.';
+    if (!isNonEmptyString(value.commandId))
+        return 'command.commandId is required.';
+    if (!isNonEmptyString(value.idempotencyKey))
+        return 'command.idempotencyKey is required.';
+    if (!isAgentHostClientIdentity(value.client))
+        return 'command.client is invalid.';
+    return null;
+}
+function commandFingerprint(
+// Every command that carries an idempotency key, not just turn commands: the fingerprint is
+// what distinguishes "the same request retried" from "a different request reusing a key".
+input) {
+    const command = {
+        ...input.command,
+        commandId: '',
+    };
+    return JSON.stringify({ ...input, command });
+}
+function turnKey(conversationId, requestId) {
+    return `${conversationId}:${requestId}`;
+}
+function safeEventIdSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 120);
+}
+function turnStartFailure(code, safeError, input) {
+    const record = isRecord(input) ? input : {};
+    return {
+        success: false,
+        code,
+        safeError,
+        ...(typeof record.conversationId === 'string' ? { conversationId: record.conversationId } : {}),
+        ...(typeof record.requestId === 'string' ? { requestId: record.requestId } : {}),
+    };
+}
+function turnCancelFailure(code, safeError, input) {
+    const record = isRecord(input) ? input : {};
+    return {
+        success: false,
+        code,
+        safeError,
+        ...(typeof record.conversationId === 'string' ? { conversationId: record.conversationId } : {}),
+        ...(typeof record.requestId === 'string' ? { requestId: record.requestId } : {}),
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Coordination — the team-agent primitives (`XENO_AGENT_COORDINATION_SPEC.md`).
+ *
+ * Exported from the PORTABLE entry rather than `./node`: these are
+ * provider-neutral rules with no Node dependency, and the host is the only party
+ * that can arbitrate them because it is the only party that sees every run.
+ */
+export * from './coordination/claims.js';
+export * from './coordination/messages.js';
+export * from './coordination/query.js';
+export * from './coordination/CoordinationService.js';
+export * from './coordination/laneBridge.js';
+export * from './coordination/coordinationTools.js';
+export * from './coordination/permissionWaitRegistry.js';
+export * from './coordination/renderInbox.js';
+export * from './coordination/runtimeEvents.js';
+export * from './knowledge/WorkspaceKnowledgeService.js';
+export * from './intake/IntakeService.js';
+// 🔴 The two TODO intake SOURCES are exported from `./node.js`, not here.
+// They import `node:fs/promises`, `node:path` and `node:crypto`; this barrel is
+// the browser-facing one, reached by any renderer that builds a fixture host,
+// and exporting them from here broke `apps/embed-preview`'s bundle outright
+// ("stat is not exported by __vite-browser-external"). `IntakeService` itself
+// stays here — it takes its sources by injection and touches no I/O.
+export * from './observation/RunObservationService.js';
+export * from './isolation/RunIsolationService.js';
+/**
+ * The confining implementation — browser-safe, and that is not an accident.
+ *
+ * It reaches the substrate over `fetch` and imports nothing from `node:`, so it
+ * belongs in THIS barrel while `RunExecutionEnvironment` does not: the
+ * environment constructs a `LocalCommandExecutor`, which spawns processes.
+ * Exporting the environment here made the browser barrel transitively reach
+ * `node:child_process` — caught by `browserBarrelPurity.test.ts` rather than by
+ * review, which is the whole reason that gate exists.
+ */
+export * from './isolation/SandboxCommandExecutor.js';
+export * from './observation/XenoUseObservationSource.js';
+export * from './observation/XenoUseRunObserver.js';
+export * from './session/AgentSessionService.js';
+export * from './session/runtimeEventChannel.js';
+export * from './session/renderSupport.js';
+/**
+ * Which run a coordination event belongs to on a timeline.
+ *
+ * A message has two runs; the entry belongs to the one the event is ABOUT — the
+ * sender for a send, the receiver for a delivery. Writing both would double
+ * every message in the record and make a reviewer counting messages wrong.
+ */
+/** Counts by kind for the fleet view. Separate from the observation service's
+ *  `summarise`: that one shapes an EVENT payload and this one a query result,
+ *  and folding them together would couple two contracts that change for
+ *  different reasons. */
+/**
+ * A session on the wire.
+ *
+ * The lease is FLATTENED: `holder` is a discriminated union internally, and a
+ * surface that had to switch on `kind` to learn who is typing would reimplement
+ * that logic in every client. `holder: null` means the agent, which is the
+ * state a surface renders as "the agent is driving".
+ */
+/** Knowledge on the wire. Provenance is FLATTENED so a surface can render "run
+ *  r7, claude, two days ago" without walking a nested object. */
+function summariseKnowledge(entry) {
+    return {
+        id: entry.id,
+        subject: entry.subject,
+        fact: entry.fact,
+        ...(entry.pinned ? { pinned: true } : {}),
+        runId: entry.provenance.runId,
+        ...(entry.provenance.providerId ? { providerId: entry.provenance.providerId } : {}),
+        at: entry.provenance.at,
+    };
+}
+/** One shape for every claim outcome, so a refusal always carries its reason. */
+function intakeClaimResponse(result, claimState) {
+    return {
+        ok: result.ok,
+        claimState,
+        ...(result.reason ? { reason: result.reason } : {}),
+        ...(result.heldBy ? { heldBy: result.heldBy } : {}),
+        ...(result.runId ? { runId: result.runId } : {}),
+    };
+}
+function summariseSession(session) {
+    return {
+        sessionId: session.sessionId,
+        runId: session.runId,
+        mode: session.mode,
+        switchable: session.switchable,
+        hasProtocolChannel: session.hasProtocolChannel,
+        openedAt: session.openedAt,
+        viewers: [...session.viewers],
+        lease: summariseLease(session.lease),
+    };
+}
+function summariseLease(lease) {
+    const human = lease.holder.kind === 'human' ? lease.holder.viewerId ?? null : null;
+    return {
+        holder: human,
+        // `heldSince` is null for the agent too: "since when" is a fact about a
+        // human takeover, and reporting the session's open time there would read as
+        // a takeover that never happened.
+        heldSince: human ? lease.since : null,
+        interventions: lease.interventions,
+    };
+}
+function countChangeKinds(changes) {
+    return {
+        added: changes.filter((change) => change.kind === 'added').length,
+        modified: changes.filter((change) => change.kind === 'modified').length,
+        deleted: changes.filter((change) => change.kind === 'deleted').length,
+    };
+}
+function coordinationSubjectRun(event) {
+    if (event.type === 'coordination.message.sent')
+        return event.fromRunId;
+    if (event.type === 'coordination.message.delivered')
+        return event.toRunId;
+    return event.runId;
+}
+//# sourceMappingURL=index.js.map