@xenosystem/agent-interface-runtime 0.1.12

package/dist/composeHost.js

@@ -0,0 +1,877 @@
+/**
+ * The Agent host composition — ONE of them, used by every product surface.
+ *
+ * ADE §9 build-order step 3 needs the host to be able to run in a process with
+ * no windows. The obvious way to get there is to write a second, smaller
+ * composition for the detached entry. That is a fork, and this repo's own
+ * invariant (`AGENTS.md`: no surface-specific fork) says why it is the wrong
+ * shape: two compositions drift, and the one that drifts is always the one
+ * fewer people run.
+ *
+ * So there is one builder, and the Electron-only capabilities are INJECTED. A
+ * surface that has windows passes them; a headless process passes none.
+ *
+ * ## 🔴 Absent capabilities are declared, never silently dropped
+ *
+ * ⚠️ CORRECTED 2026-08-18. This said the SDK-native lane cannot run without
+ * `createSdkRuntimeWindow`, "its tools take a live BrowserWindow". Measured, that
+ * is false: the loop takes an `SdkAgentSurface` (send + isDestroyed) and loads in
+ * plain Node, and the surface tools act through `SdkAgentSurfaceRuntimeAdapter`,
+ * whose unregistered default refuses honestly. A window is now one way to run the
+ * lane; the headless runner is the other, and it differs only in where events go
+ * and who can answer a prompt.
+ *
+ * The principle the paragraph was written for is untouched, and still applies to
+ * every capability that IS genuinely absent here: the tempting response is to
+ * leave the provider out of the catalog entirely.
+ *
+ * That is wrong, and the reason generalises: **a provider that vanishes looks
+ * like a configuration error.** An operator sees a shorter list and goes looking
+ * for what they broke. A provider that is PRESENT and reports
+ * `runnable: false` with a reason has told them the truth — this build cannot
+ * run that lane, and here is why. The descriptor already carries
+ * `safeUnavailableReason` for exactly this, so honesty costs a string.
+ *
+ * ## §9 step 3 — ADOPTED
+ *
+ * Both entries run this. `apps/desktop/src/main/index.ts` calls it with a full
+ * `surface`; `detachedHostEntry.ts` calls it with `{}`. The fork it existed to
+ * remove is gone, and with it the failure mode that made the case: for weeks
+ * each composition was missing services the other had, in both directions —
+ * the four §5 services reached the detached host and never the app, while
+ * tier-1 observation and the §5.7 landing queue reached the app and never the
+ * detached host. Neither gap is visible from inside one composition, and a test
+ * that mounts its own fixture cannot see them at all.
+ *
+ * 🔴 `createCoordinator()` is DEFERRED, and that is the one thing not to
+ * "simplify". Composing is safe in any process; the coordinator opens the
+ * durable SQLite state, and two of those open at once is the split-brain the
+ * host lease exists to prevent. So the composition is eager — a surface still
+ * needs its shell service and registry while another process owns the host —
+ * and only the coordinator waits for the election.
+ */
+import { XENO_AGENT_HOST_MIN_PROTOCOL_VERSION, XENO_AGENT_HOST_PROTOCOL_VERSION, } from '@xenosystem/agent-interface-contract';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { AcpAgentRegistryService, AcpNativeProviderLauncherResolver, AcpAgentTurnExecutionAdapter, AcpInteractivePermissionBridge, AgentHostCoordinator, DirectoryBaselineScanner, DurableAcpPermissionPolicyStore, DurableInterruptedTurnStore, DurablePendingInjectionStore, EngineeringWorkbenchService, LandingService, MountContentReader, ProviderLaneService, RunExecutionEnvironment, RunObservationService, RunIsolationService, RuntimeEventStore, RuntimeEventStoreRepositoryAdapter, SdkNativeAgentTurnExecutionAdapter, SubagentScheduler, setSubagentScheduler, createHostTurnSubagentExecutionAdapter, getSubagentRunService, WorkspaceHostService, WorkspaceShellService, XenoCloudAgentTurnExecutionAdapter, XenoUseRunObserver, createAcpApprovalPortAdapter, createAcpAgentRegistryPort, createAcpNativeTuiLane, createAcpRuntimeProviderDescriptors, createAgentStateRepository, createFixtureAcpAgentConfig, createSdkNativeRuntimeProviderDescriptor, createXenoCloudRuntimeProviderDescriptor, resolveLocalAgentHostPaths, toXenoCloudAgentModelDescriptors, } from '@xenosystem/agent-interface-host/node';
+import { createXenoCloudNodeAgentsClient, discoverXenoCloudNodeRuntime, readXenoCloudCredentials, } from '@xenosystem/agents-client/node';
+/**
+ * 🔴 `@xenosystem/agent-interface-electron-host` is imported
+ * DYNAMICALLY, everywhere, and only when a surface supplies a window.
+ *
+ * Its `sdkAgent` module does `import { app, dialog, ipcMain } from 'electron'`
+ * at module scope. A static import here puts `electron` in the shared main
+ * chunk, so the detached host entry — a plain Node process — dies on
+ * `SyntaxError: Named export 'app' not found` before it runs a line.
+ *
+ * ⚠️ Spawning it as `electron --run-as-node` does NOT rescue this: under
+ * `ELECTRON_RUN_AS_NODE` the `electron` module resolves to the executable's
+ * PATH STRING, not the API, so the named import fails there too.
+ *
+ * The headless composition test did not catch it, because vite resolves
+ * `electron` in-process. Only spawning the BUILT entry did.
+ */
+import { createSharedHostServices } from './hostServices.js';
+import { declaredUnavailableLanes, deliverElicitationThrough, sdkUnavailableReasonFor } from './hostLanePolicy.js';
+import { resolveObservationConfig } from './observationConfig.js';
+import { standaloneCloudOptions } from './cloudOptions.js';
+export async function composeAgentHost(options) {
+    const env = options.env ?? process.env;
+    const fixtureEnabled = env.XENO_AGENT_ENABLE_FIXTURE === '1';
+    const paths = resolveLocalAgentHostPaths({
+        homeDirectory: options.homeDirectory,
+        ...(env.XENO_AGENT_HOST_ROOT ? { hostRootDirectory: env.XENO_AGENT_HOST_ROOT } : {}),
+        ...(env.XENO_AGENT_ACP_REGISTRY_ROOT
+            ? { acpRegistryRootDirectory: env.XENO_AGENT_ACP_REGISTRY_ROOT }
+            : {}),
+    });
+    const hostRoot = paths.hostRootDirectory;
+    const registry = new AcpAgentRegistryService({ rootDir: paths.acpRegistryRootDirectory });
+    if (fixtureEnabled) {
+        const fixtureMode = env.XENO_AGENT_FIXTURE_MODE || 'normal';
+        const fixturePath = env.XENO_AGENT_FIXTURE_PATH
+            || join(options.fixtureBaseDirectory, '..', '..', 'tests', 'fixtures', 'acp', 'fixture-acp-agent.mjs');
+        const fixture = createFixtureAcpAgentConfig(registry.rootDir, fixtureMode, 'fixture-acp');
+        const saved = registry.saveAgent({
+            ...fixture,
+            args: [fixturePath, `--mode=${fixtureMode}`],
+            env: { XENO_ACP_FIXTURE_MODE: fixtureMode, ELECTRON_RUN_AS_NODE: '1' },
+        });
+        if (!saved.success)
+            throw new Error(saved.error || 'Could not register the standalone ACP fixture.');
+    }
+    const runtimeStore = new RuntimeEventStore(paths.runtimeEventsDirectory);
+    const cloudOptions = standaloneCloudOptions({ homeDirectory: options.homeDirectory, hostRoot, env });
+    const cloudClient = createXenoCloudNodeAgentsClient(cloudOptions);
+    const cloudRunClient = {
+        createRun: (input, runOptions) => cloudClient.createRun(input, runOptions),
+        attach: (runId, runOptions) => cloudClient.attach(runId, {
+            transport: 'sse',
+            reconnect: true,
+            ...(runOptions?.signal ? { signal: runOptions.signal } : {}),
+        }),
+        getRun: (runId, runOptions) => cloudClient.getRun(runId, runOptions),
+        stopRun: (runId, runOptions) => cloudClient.stopRun(runId, runOptions),
+    };
+    const acpPermissionPolicyStore = new DurableAcpPermissionPolicyStore({ rootDirectory: hostRoot });
+    const interruptedTurnStore = new DurableInterruptedTurnStore({ rootDirectory: hostRoot });
+    /**
+     * Pinned nodes waiting for a next turn (XENO SPAWN §2.2, §3).
+     *
+     * Durable here for the same reason the two stores above it are: this host has a real root, and
+     * §3 puts a `deferred` row on an append-only record the moment a node is pinned. Held in memory,
+     * a restart left that row promising a delivery nothing could still make.
+     */
+    const pendingInjectionStore = new DurablePendingInjectionStore({ rootDirectory: hostRoot });
+    const acpPermissionBridge = new AcpInteractivePermissionBridge({
+        messenger: {
+            send: (channel, payload) => {
+                const send = options.surface.sendElicitation;
+                // Throwing is the CORRECT direction here: the bridge treats an
+                // unreachable surface as a refusal, and a permission prompt nobody can
+                // answer must not resolve as an approval.
+                if (!send)
+                    throw new Error('This Agent host has no surface able to show a permission prompt.');
+                send(channel, payload);
+            },
+        },
+    });
+    const permissionPolicyService = {
+        listRules: () => ({
+            success: true,
+            rules: acpPermissionPolicyStore.list().map((rule) => ({
+                id: rule.id,
+                decision: rule.decision,
+                ...(rule.kind ? { toolKind: rule.kind } : {}),
+                ...(rule.pathPrefix ? { pathPrefix: rule.pathPrefix } : {}),
+                ...(rule.createdAt === undefined ? {} : { createdAt: rule.createdAt }),
+            })),
+        }),
+        revokeRule: (input) => ({
+            success: true,
+            revoked: acpPermissionPolicyStore.remove(input.ruleId),
+        }),
+    };
+    // Loaded only when the SDK lane can actually run. A headless composition has
+    // no window, cannot run that lane at all (it is declared unrunnable below),
+    // and so has no reason to pay for — or be broken by — this module.
+    const sdkInteractionService = options.surface.createSdkRuntimeWindow
+        ? (await import('@xenosystem/agent-interface-electron-host'))
+            .createSdkNativeInteractionService()
+        : undefined;
+    const interactionService = {
+        answerPermission: (input) => {
+            const routed = acpPermissionBridge.answerPermission({
+                permissionId: input.permissionId,
+                granted: input.granted,
+                ...(input.selectedOptionId ? { selectedOptionId: input.selectedOptionId } : {}),
+            });
+            if (routed.handled)
+                return { success: true };
+            // 🔴 Not silently "handled". With no SDK lane there is nobody to route
+            // this to, and reporting success for an answer nothing received would
+            // leave the asker waiting forever on a prompt already marked resolved.
+            if (!sdkInteractionService) {
+                return { success: false, error: 'This host has no SDK-native lane to answer.' };
+            }
+            return sdkInteractionService.answerPermission(input);
+        },
+        answerAskUser: sdkInteractionService
+            ? sdkInteractionService.answerAskUser
+            : () => ({ success: false, error: 'This host has no SDK-native lane to answer.' }),
+    };
+    /**
+     * The four §5 services, from the ONE builder both compositions call.
+     *
+     * 🔴 They used to be constructed here and NOWHERE else, which meant they
+     * reached this composition — the detached host — and not the app the user
+     * launches. Closing that by pasting the constructions into `index.ts` would
+     * have left two spellings of the same decisions in the two files least likely
+     * to be read together, so the decisions moved to `hostServices.ts` instead.
+     */
+    const { knowledgeService, intakeService, sessionService, coordinationService, coordinationPort, } = createSharedHostServices({
+        resolveIntakeRoots: () => workspaceAuthority.grantedDirectories(),
+    });
+    const engineeringControlService = new EngineeringWorkbenchService({ runtimeEventStore: runtimeStore });
+    /**
+     * Tier-1 run observation (ADE §2.9).
+     *
+     * 🔴 Built HERE, in the shared composition, and that is a fix rather than a
+     * move. It used to live only in `index.ts`, so the DETACHED host — the whole
+     * point of §9 step 3 — ran with no observation and no landing gate at all:
+     * the exact mirror of the four §5 services that used to reach only the
+     * detached host and never the app. A capability that exists in one
+     * composition and not the other is the fork this module exists to remove.
+     *
+     * 🔒 **Out of process, HTTP only** (locked decision 17). `xeno-use` is
+     * AGPL-3.0 and this app is proprietary, so nothing here imports it, links its
+     * N-API binding, or takes it as a dependency. The observer speaks its
+     * `/v1/use/*` surface and nothing else.
+     *
+     * 🔴 **Unconfigured means NO observation, not an empty one.** With no
+     * endpoint the service is not constructed and no binder is passed, so the host
+     * reports review unavailable and `mayLand` refuses for want of a diff — all
+     * of which is true and correct. An empty service would instead report every
+     * run as a clean diff of changes nobody watched.
+     */
+    /**
+     * Records where EVERY run executes — with or without observation configured.
+     *
+     * 🔴 Deliberately outside the `if (observationConfig.enabled)` block below.
+     * Isolation and observation are different questions, and a run that nothing
+     * watches is still a run whose containment the user is entitled to know. Bound
+     * here with no sandbox, so it resolves to the local executor and reports
+     * `none` — a fact, not an absence. Binding only observed runs would leave
+     * every other run reporting `unknown`, which reads as "cannot account for it"
+     * when the truth is plainly "nothing confines it".
+     */
+    const bindRunExecution = (context) => {
+        // 🔴 CONFINEMENT REQUIRES A DIRECTORY TO MOUNT. A run with none has nothing
+        // to bind a sandbox around, so it is bound unconfined and reports `none` —
+        // truthfully. Substituting a directory would mount the wrong tree.
+        if (!resolveRunSandbox || !context.primaryDirectory) {
+            runExecutionEnvironment.bind({
+                runId: context.runId,
+                conversationId: context.conversationId,
+            });
+            return;
+        }
+        runExecutionEnvironment.bind({
+            runId: context.runId,
+            conversationId: context.conversationId,
+            pendingSandbox: resolveRunSandbox(context.runId, context.primaryDirectory),
+        });
+    };
+    const knownRunIds = new Set();
+    let runObservationService;
+    let runObserver;
+    let observationBegin;
+    /**
+     * Spawns (or joins) the run's sandbox and describes it for execution.
+     *
+     * Defined only when a `xeno-use` endpoint is configured — so with no sandbox
+     * substrate installed, `bindRunExecution` binds every run unconfined and the
+     * app reports `none`, which is the truth and is what §5.3 asks it to say.
+     */
+    let resolveRunSandbox;
+    const observationConfig = resolveObservationConfig(env);
+    if (observationConfig.reason) {
+        // Said once, at startup. Half-configured otherwise fails silently, one 401
+        // per run, with nothing pointing at configuration as the cause.
+        console.warn(`[xeno-agent-host] run observation is off: ${observationConfig.reason}`);
+    }
+    if (observationConfig.enabled && observationConfig.baseUrl && observationConfig.token) {
+        runObservationService = new RunObservationService();
+        const observer = new XenoUseRunObserver({
+            baseUrl: observationConfig.baseUrl,
+            token: observationConfig.token,
+            ...(observationConfig.image ? { image: observationConfig.image } : {}),
+            service: runObservationService,
+            baselineScanner: new DirectoryBaselineScanner(),
+            // Hunk content is read from the HOST side of the mount — a bind mount is
+            // the host directory, so this needs no sandbox call and no dependency.
+            createContentReader: ({ hostDirectory, containerDirectory }) => new MountContentReader({ mounts: [{ source: hostDirectory, target: containerDirectory }] }),
+            onProblem: ({ runId, reason }) => console.warn(`[xeno-agent-host] observation problem${runId ? ` for ${runId}` : ''}: ${reason}`),
+        });
+        runObserver = observer;
+        observationBegin = ({ runId, primaryDirectory }) => {
+            // 🔴 Recorded BEFORE the early return below.
+            //
+            // A run with no directory is never observed, and that is exactly the run
+            // the landing gate must not silently ignore. Recording it here is what
+            // lets `landingOverlaps` report the combination as incomplete instead of
+            // clearing a merge over work nobody watched.
+            knownRunIds.add(runId);
+            // No directory means nothing to watch. Substituting one would mount the
+            // wrong tree into a sandbox and report another project's files as this
+            // run's work.
+            if (!primaryDirectory)
+                return;
+            // Not awaited: attaching spawns a container and the turn is the user's
+            // actual work. `start` resolves false rather than throwing, and an
+            // unobserved run is reported honestly everywhere downstream.
+            void observer.start(runId, { hostDirectory: primaryDirectory });
+        };
+        /**
+         * Routes EXECUTION into the sandbox this run is already observed in.
+         *
+         * 🔴 One container, both roles — which is ADE §2.9's architecture ("every
+         * run is sandboxed, so the sandbox is an observation plane"), not a
+         * shortcut. `isolationIsNotObservation.test.ts` forbids deriving
+         * `sandboxed` from an observation binding *while execution still goes to
+         * the host*; its own stated exit is "turn execution actually being routed
+         * into one", which is this. The binding was never sufficient on its own —
+         * it is necessary, and now it is accompanied.
+         *
+         * The spawn is handed over as a PENDING sandbox rather than awaited here.
+         * Awaiting would stall every turn behind a container start; not awaiting at
+         * all would let the first command run on the host and still report
+         * `sandboxed`. Passing the promise makes the EXECUTOR wait instead, so no
+         * command reaches the host and no turn is blocked for a run that never
+         * executes anything.
+         */
+        resolveRunSandbox = async (runId, primaryDirectory) => {
+            const started = await observer.start(runId, { hostDirectory: primaryDirectory });
+            if (!started)
+                return undefined;
+            const descriptor = observer.sandboxFor(runId);
+            if (!descriptor)
+                return undefined;
+            return {
+                sandboxId: descriptor.sandboxId,
+                mount: {
+                    hostDirectory: descriptor.hostDirectory,
+                    containerDirectory: descriptor.containerDirectory,
+                },
+                baseUrl: observationConfig.baseUrl,
+                token: observationConfig.token,
+                mechanism: 'container (xeno-use)',
+            };
+        };
+    }
+    /**
+     * The binder the host always gets.
+     *
+     * 🔴 Unconditional, because isolation must be recorded for every run whether
+     * or not observation is configured — and the two used to share one optional
+     * hook, so an unobserved run was also an unaccounted-for run. The observation
+     * half stays conditional inside it: with no endpoint `runObservationService`
+     * is still undefined, so review remains unavailable and `mayLand` still
+     * refuses for want of a diff. Nothing about that changed.
+     */
+    const runObservationBinder = {
+        begin: (context) => {
+            bindRunExecution({
+                runId: context.runId,
+                conversationId: context.conversationId,
+                ...(context.primaryDirectory === undefined
+                    ? {}
+                    : { primaryDirectory: context.primaryDirectory }),
+            });
+            observationBegin?.(context);
+        },
+    };
+    /**
+     * §5.7's landing queue — the serialised, gated path to trunk.
+     *
+     * 🔴 Its overlap picture is read from the OBSERVATION service above. With
+     * observation unconfigured there are no observed diffs, so `landingOverlaps()`
+     * reports nothing and the gate refuses every landing as `unverified` —
+     * correct, and not a degradation to route around: conflict-aware landing
+     * without observed change sets would be a verdict about a world nobody
+     * looked at.
+     *
+     * The merge itself is a plain `git merge --no-ff` of the run's branch.
+     * `--no-ff` on purpose: a landing is a decision, and a decision should be
+     * visible in the history as one commit that can be reverted, rather than
+     * dissolved into trunk by a fast-forward.
+     */
+    engineeringControlService.configureLandingService(new LandingService({
+        context: {
+            contextFor: () => ({
+                overlaps: runObservationService
+                    // 🔴 The known set is passed, not just the observed one. Without it
+                    // the gate compares only what it happened to watch and calls the
+                    // answer complete — which is how a merge lands on top of an
+                    // unobserved run's work.
+                    ? runObservationService.landingOverlaps({}, [...knownRunIds])
+                    // An empty report, which yields `unverified` and refuses. Deliberately
+                    // NOT a fabricated all-clear: the gate must never clear a landing on
+                    // facts nobody collected.
+                    : { runs: [], overlaps: [], complete: false, incompleteRuns: [] },
+                verifications: [],
+            }),
+        },
+        checkRunner: {
+            run: async ({ rootDirectory, checkId }) => {
+                const discovered = engineeringControlService.discoverChecks({ rootDirectory });
+                const check = checkId
+                    ? discovered.checks?.find((candidate) => candidate.id === checkId)
+                    : discovered.checks?.[0];
+                if (!check) {
+                    return { passed: false, checks: [], problem: 'No check could be discovered for this workspace.' };
+                }
+                const result = await engineeringControlService.runCheck({ rootDirectory, checkId: check.id });
+                // 🔴 `exitCode === 0`, not `result.success`. `success` means the check
+                // RAN; a suite that ran perfectly and reported three failures is a
+                // successful run of a red check, and treating that as green is the
+                // whole failure this gate exists to prevent.
+                const passed = result.run?.exitCode === 0;
+                return {
+                    passed,
+                    checks: [check.id],
+                    ...(passed
+                        ? {}
+                        : {
+                            problem: result.error
+                                ?? result.run?.error
+                                ?? `${check.id} exited ${result.run?.exitCode ?? 'without a status'}`,
+                        }),
+                };
+            },
+        },
+        executor: {
+            merge: async ({ rootDirectory, runId, base }) => {
+                const branch = await engineeringControlService.gitBranch({
+                    rootDirectory,
+                    name: base || 'main',
+                    create: false,
+                });
+                if (!branch.success) {
+                    return { merged: false, error: branch.error || `Could not switch to ${base || 'main'} to land.` };
+                }
+                return await engineeringControlService.gitMergeForLanding({ rootDirectory, branch: runId });
+            },
+        },
+    }));
+    /**
+     * Where each run's commands execute, and what containment to report — ADE §5.3.
+     *
+     * 🔴 One object answers both, so the app cannot confine a run while telling
+     * the user it does not, or claim containment it does not have. It is
+     * constructed unconditionally: with no sandbox bound it hands out the local
+     * executor and reports `none`, which is exactly today's truth and is what
+     * §5.3 asks the product to say out loud.
+     *
+     * Binding a run to an execution sandbox happens in `bindRunExecution` when
+     * a `xeno-use` endpoint is configured. Workspace commands, the agent's
+     * Bash tool, and the workspace PTY all resolve through this object. A
+     * confined PTY is `/bin/sh -i` with `tty: true` on `CommandStreamPort`.
+     */
+    const runExecutionEnvironment = new RunExecutionEnvironment();
+    let providerLaneServiceForPty;
+    const workspaceAuthority = new WorkspaceHostService({
+        rootDirectory: paths.workspaceAuthorityRoot,
+        managedConversationRoot: paths.managedConversationRoot,
+        executionEnvironment: runExecutionEnvironment,
+        providerSessionPtyResolver: (profile, cwd, platform) => (providerLaneServiceForPty?.resolveProviderSessionPty(profile, cwd, platform)
+            ?? { code: 'NATIVE_TUI_UNSUPPORTED', error: 'Provider lane authority is not ready.' }),
+    });
+    const workspaceShellService = options.surface.shell
+        ? new WorkspaceShellService({ workspaceAuthority, shell: options.surface.shell })
+        // Absent rather than a stub. A shell service that accepted "reveal in
+        // folder" and did nothing would report success it does not have.
+        : undefined;
+    /**
+     * 🔴 Two ways to run the SDK-native lane now, and a window is only one of them.
+     *
+     * A composition with a renderer runs it through `createSdkNativeElectronRunner`, exactly as
+     * before. A composition without one runs the SAME loop through the headless runner, which
+     * routes the two blocking channels to attached clients and REFUSES them when nobody is there.
+     * That refusal is what makes the headless lane runnable rather than a trap: an elicitation that
+     * is neither answered nor refused wedges the turn forever, because `requestSurfacePermission`
+     * has no timeout.
+     *
+     * So the lane is runnable in both, and `canResolveElicitations` is true in both — for different
+     * reasons, which is why the parameter asks about resolving rather than about a window.
+     */
+    const hasWindow = Boolean(options.surface.createSdkRuntimeWindow);
+    const sdkRunnable = true;
+    const declaredUnavailable = declaredUnavailableLanes({
+        hasWindow,
+        canResolveElicitations: true,
+    });
+    const loadProviders = () => loadAgentHostProviders(registry, cloudOptions, {
+        sdkRunnable,
+        // The store decides, not a literal — one object, so the declaration cannot drift from it.
+        durablePendingInjections: pendingInjectionStore.durable,
+    });
+    const providers = await loadProviders();
+    // Typed as the shared interface, not inferred: inference from the initial two
+    // entries produces a union that the SDK adapter is not a member of, and the
+    // fix for that must not be a cast — the whole point is that every lane
+    // satisfies one contract.
+    const turnExecutionAdapters = [
+        new AcpAgentTurnExecutionAdapter({
+            registryService: registry,
+            runtimeStore,
+            permissionDelegate: acpPermissionBridge,
+            permissionPolicyStore: acpPermissionPolicyStore,
+            /**
+             * \u{1F534} A PORT, not the service. What an ACP agent may do is exactly these
+             * four calls; passing the service itself would put `endRun` and
+             * `setInboundPolicy` within reach of the lane, and those are the host's.
+             */
+            coordinationPort,
+            /**
+             * \u{1F534} Late-bound on purpose. The adapter is built BEFORE the coordinator
+             * that owns the roster — the same ordering `setEventSink` already solves
+             * — so this closes over the binding rather than the value. Before the
+             * coordinator exists there is no run to report on, so the no-op is
+             * correct rather than a swallowed signal.
+             */
+            onRunActivity: (signal) => { coordinator?.reportRunActivity(signal); },
+            ...(fixtureEnabled ? { requestTimeoutMs: 5_000 } : {}),
+        }),
+        new XenoCloudAgentTurnExecutionAdapter({ client: cloudRunClient, runtimeStore }),
+    ];
+    if (!options.surface.createSdkRuntimeWindow) {
+        // The headless lane. Same loop, same coordination port, same run-activity reporter — the
+        // only difference is where its events go and who can answer its prompts.
+        const { createSdkNativeHeadlessRunner } = await import('@xenosystem/agent-interface-electron-host/headless');
+        turnExecutionAdapters.splice(1, 0, new SdkNativeAgentTurnExecutionAdapter(createSdkNativeHeadlessRunner({
+            getAuthToken: () => readXenoCloudCredentials(cloudOptions).apiKey || null,
+            getPlatformAuthToken: () => readXenoCloudCredentials(cloudOptions).webToken || null,
+            runtimeEventStore: runtimeStore,
+            executionEnvironment: runExecutionEnvironment,
+            /**
+             * 🔴 Delivery is answered from HANDSHAKES, never from subscribers. The RPC server
+             * subscribes exactly one listener and fans out to however many sockets it holds, so a
+             * listener count is equally consistent with ten attached clients and none. Only a client
+             * that completed a handshake AND declared `canPresentElicitations` can actually answer.
+             *
+             * Late-bound through `coordinator` for the same reason `onRunActivity` is: the adapters
+             * are built before the coordinator that owns the client registry exists.
+             */
+            deliverElicitation: (channel, payload) => deliverElicitationThrough(coordinator, channel, payload),
+        }), coordinationPort, (signal) => { coordinator?.reportRunActivity(signal); }, 
+        // The SAME store the windowed lane gets: a pin is made against a CONVERSATION, and which
+        // lane happens to execute its next turn is not something an operator chose.
+        pendingInjectionStore));
+    }
+    if (options.surface.createSdkRuntimeWindow) {
+        // Registered only where it can actually run. The adapter registry answers
+        // `adapter_unavailable` BY NAME for an unregistered lane, so an attempt to
+        // use it here fails with the reason rather than with a crash inside a tool
+        // reaching for a window that does not exist.
+        const { createSdkNativeElectronRunner } = await import('@xenosystem/agent-interface-electron-host');
+        const sdkRunner = createSdkNativeElectronRunner({
+            getAuthToken: () => readXenoCloudCredentials(cloudOptions).apiKey || null,
+            getPlatformAuthToken: () => readXenoCloudCredentials(cloudOptions).webToken || null,
+            createRuntimeWindow: options.surface.createSdkRuntimeWindow,
+            runtimeEventStore: runtimeStore,
+            executionEnvironment: runExecutionEnvironment,
+        });
+        // The SAME port the ACP lane gets. Two vocabularies, one implementation — a
+        // primitive that behaved differently by lane would leave an agent with two
+        // answers and no way to tell which to believe.
+        turnExecutionAdapters.splice(1, 0, new SdkNativeAgentTurnExecutionAdapter(sdkRunner, coordinationPort, 
+        // The SAME reporter the ACP lane gets. A run blocked on a human must look
+        // the same to a peer whichever runtime is executing it.
+        (signal) => { coordinator?.reportRunActivity(signal); }, pendingInjectionStore));
+    }
+    // Read by `onRunActivity` above, which is created first; see the note there.
+    let coordinator;
+    /**
+     * Subagent execution — ADE §5.2, step 6.
+     *
+     * 🔴 The adapter runs each subagent as a TURN on this host, so a fan-out inherits the same
+     * admission budget, deadlines and abandonment as every other surface's work rather than getting
+     * a second execution path that would drift from all three.
+     *
+     * ⚠️ Provider selection goes through `fleet.plan`, not a local capability check. Duplicating the
+     * matching would give the fleet two answers to "who can run this", and the one nobody is looking
+     * at would be the one that drifts.
+     */
+    // 🔴 Anchored to THIS host's home. The default is the real user's `~/.xeno`, which an
+    // isolated host must never write to — and until this line existed, every one did.
+    const subagentRunService = getSubagentRunService(join(options.homeDirectory, '.xeno', 'subagent-runs.json'));
+    const subagentScheduler = new SubagentScheduler(subagentRunService, runtimeStore);
+    // Diagnostics read the REGISTERED scheduler. Without this line they build their own, report its
+    // empty status as the system's, and an operator reads "scheduler not running" during an incident
+    // where it is running fine.
+    setSubagentScheduler(subagentScheduler);
+    /**
+     * The scheduler is a SURFACE, so it must complete the host handshake before its first turn.
+     *
+     * 🔴 It never did, and the consequence was invisible: every `turn.start` was refused with
+     * "The requesting surface must complete the host handshake before starting a turn.", the adapter
+     * read a refusal as an acceptance, and the run sat in `running` with zero runtime events until its
+     * lease expired. Measured with scripts/delegation-probe.mjs.
+     *
+     * ⚠️ Cached as a PROMISE so concurrent launches share one handshake instead of racing to
+     * register the same surface — and NOT cached on failure, because a handshake that failed while the
+     * coordinator was still starting must stay retryable rather than poisoning every later run.
+     *
+     * ⚠️ It lives here rather than in the adapter because the adapter's port is deliberately
+     * `turn.start | turn.cancel` only. The composition owns the coordinator and the identity below;
+     * the adapter should not need a handshake-capable host to be testable.
+     */
+    const subagentIdentity = {
+        clientId: 'xeno-agent-subagent-scheduler',
+        clientVersion: options.hostVersion,
+        instanceId: `${options.hostInstanceId}:subagents`,
+        surface: 'headless-client',
+    };
+    /**
+     * Host-event subscribers registered BEFORE the coordinator exists.
+     *
+     * 🔴 `subscribe: (listener) => coordinator?.subscribe(...) ?? (() => {})` ran at adapter
+     * CONSTRUCTION, when `coordinator` is still undefined — so it returned the no-op and the subagent
+     * adapter never received one host event. It therefore never saw `turn.execution.completed` and
+     * never settled a run: a child that finished successfully left its run at `running` until the
+     * lease expired, at which point recovery RE-RAN work that had already succeeded.
+     *
+     * ⚠️ The `request` property beside it is late-bound correctly, because it re-reads
+     * `coordinator` inside an async function on every call. The same comment covered both and only
+     * one of them actually deferred.
+     */
+    const pendingHostSubscribers = new Map();
+    const subscribeToHost = (listener) => {
+        if (coordinator)
+            return coordinator.subscribe(listener);
+        // ⚠️ The slot is captured by the returned unsubscribe, so it keeps working after the flush
+        // clears the map — the caller cannot tell whether it subscribed before or after the
+        // coordinator existed, which is what makes this correct rather than merely working today.
+        const slot = {};
+        pendingHostSubscribers.set(listener, slot);
+        return () => {
+            pendingHostSubscribers.delete(listener);
+            slot.dispose?.();
+        };
+    };
+    const attachPendingHostSubscribers = () => {
+        if (!coordinator)
+            return;
+        for (const [listener, slot] of pendingHostSubscribers) {
+            slot.dispose = coordinator.subscribe(listener);
+        }
+        pendingHostSubscribers.clear();
+    };
+    let subagentHandshake;
+    const ensureSubagentHandshake = async () => {
+        if (subagentHandshake)
+            return subagentHandshake;
+        subagentHandshake = (async () => {
+            try {
+                await coordinator?.request('host.handshake', {
+                    identity: subagentIdentity,
+                    supportedProtocol: {
+                        min: XENO_AGENT_HOST_MIN_PROTOCOL_VERSION,
+                        max: XENO_AGENT_HOST_PROTOCOL_VERSION,
+                    },
+                });
+            }
+            catch (error) {
+                subagentHandshake = undefined;
+                throw error;
+            }
+        })();
+        return subagentHandshake;
+    };
+    const subagentAdapter = createHostTurnSubagentExecutionAdapter({
+        // Late-bound for the same reason as `onRunActivity`: adapters are built before the
+        // coordinator that executes their turns exists.
+        host: {
+            request: (async (method, request) => {
+                if (!coordinator)
+                    throw new Error('The Agent host is not ready to execute subagent runs.');
+                // Handshake first, every time, idempotently — see ensureSubagentHandshake above.
+                if (method !== 'host.handshake')
+                    await ensureSubagentHandshake();
+                return coordinator.request(method, request);
+            }),
+            subscribe: (listener) => subscribeToHost(listener),
+        },
+        identity: subagentIdentity,
+        selectProvider: async (run) => {
+            /**
+             * ⚠️ No `requiredCapabilities` is passed, and that is deliberate rather than a TODO.
+             * `SubagentCapabilityMatch` carries score/reasons/missingCapabilities — it is the RESULT of
+             * matching, not the requirement — so there is nothing on a run to forward. Inventing a
+             * requirement here would make `fleet.plan` refuse runs for a constraint no one stated.
+             * Carrying the requirement onto the run is a contract change, not a line of glue.
+             */
+            // 🔴 AWAITED. `request` is async, and the previous version cast the Promise to a plain
+            // object with `as unknown as` — so `assignments` was always undefined, selection always
+            // failed, and every subagent run terminated with "No runtime could be selected for this
+            // subagent run." The cast is what made it typecheck.
+            const plan = await coordinator?.request('fleet.plan', {
+                tasks: [{ taskId: run.id }],
+            });
+            const providerId = plan?.assignments?.[0]?.providerId;
+            if (!providerId)
+                return undefined;
+            const provider = providers.find((entry) => entry.id === providerId);
+            const modelId = provider?.models.find((model) => model.isDefault)?.id ?? provider?.models[0]?.id;
+            if (!provider || !modelId)
+                return undefined;
+            return { providerId, catalogRevision: provider.catalogRevision, modelId };
+        },
+    });
+    subagentScheduler.registerAdapter(subagentAdapter);
+    /**
+     * The port the host gets: create and list from the run service, cancel from the SCHEDULER —
+     * because cancelling a launched run has to reach the adapter that launched it.
+     */
+    const subagentRuns = {
+        createRun: (request) => {
+            const result = subagentRunService.createRun(request);
+            // 🔴 Drain immediately, or a created run waits for the next sweep — and before this line
+            // existed, forever: nothing claimed a queued run at all, so `subagent.run.create` persisted a
+            // run that never executed. Proven with scripts/delegation-probe.mjs, which saw `queued` sixty
+            // seconds later with zero runtime events.
+            //
+            // ⚠️ Safe to call on every create because the ceiling lives in `claimNextRun`, which counts
+            // active runs per slot and refuses beyond `maxConcurrentRuns`. This adds no policy; it only
+            // stops the queue from standing still.
+            if (result.success)
+                subagentScheduler.drain();
+            return result;
+        },
+        listRuns: (request) => subagentRunService.listRuns(request),
+        cancelRun: (request) => subagentScheduler.cancelRun(request),
+    };
+    // The periodic sweep recovers runs whose worker died AND launches anything queued while every
+    // slot was full. It was never started, so neither happened.
+    subagentScheduler.start();
+    let stateRepository;
+    const createCoordinator = async () => {
+        // Idempotent: the lease is won once, but shutdown and retry paths can race,
+        // and opening the durable state twice from one process is no better than
+        // opening it from two.
+        if (coordinator)
+            return coordinator;
+        stateRepository = await createAgentStateRepository(paths);
+        const runtimeEventRepository = new RuntimeEventStoreRepositoryAdapter(runtimeStore);
+        const nativeLauncherResolver = new AcpNativeProviderLauncherResolver(registry);
+        const providerLaneService = new ProviderLaneService({
+            repository: stateRepository,
+            workspaceService: workspaceAuthority,
+            hostInstanceId: options.hostInstanceId,
+            hostStorageIdentity: createHash('sha256')
+                .update(`xeno-agent-state-v2\0${paths.stateDatabaseFile.toLowerCase()}`, 'utf8')
+                .digest('hex'),
+            getProviders: () => loadProviders(),
+            resolveNativeLauncher: (input) => nativeLauncherResolver.resolve(input),
+            runtimeEventRepository,
+        });
+        providerLaneServiceForPty = providerLaneService;
+        coordinator = new AgentHostCoordinator({
+            hostVersion: options.hostVersion,
+            hostInstanceId: options.hostInstanceId,
+            processBoundary: 'per-user-service',
+            storageSchemaVersion: 2,
+            eventSchemaVersion: 1,
+            providers,
+            providerCatalogLoader: () => loadProviders(),
+            runtimeEventRepository,
+            /**
+             * ADE §2.8's `native-tui` lane, finally reachable.
+             *
+             * Resolved from the ACP registry: a provider offers its own interface iff
+             * its agent config carries a `nativeTui` command, which is written only
+             * when the vendor's binary was actually FOUND on PATH. So a machine
+             * without Claude CLI installed reports `nativeTui: false` for
+             * `claude-local` and the mode is refused by name — the honest answer,
+             * not a broken session.
+             *
+             * 🔴 Passing the resolver rather than a snapshot: the registry changes
+             * when a user adds an agent, and a value captured here would answer for
+             * the providers that existed at boot.
+             */
+            nativeTuiLane: createAcpNativeTuiLane(registry),
+            acpAgentRegistry: createAcpAgentRegistryPort(registry),
+            stateRepository,
+            workspaceService: workspaceAuthority,
+            interactionService,
+            permissionPolicyService,
+            interruptedTurnStore,
+            // Same rule as the interaction service: absent without a window, never a
+            // stub that accepts control commands for a lane that cannot run.
+            ...(options.surface.createSdkRuntimeWindow
+                ? {
+                    sdkControlService: (await import('@xenosystem/agent-interface-electron-host'))
+                        .createSdkNativeControlService(),
+                }
+                : {}),
+            engineeringControlService,
+            providerLaneService,
+            ...(runObservationService ? { runObservationService } : {}),
+            runObservationBinder,
+            knowledgeService,
+            intakeService,
+            sessionService,
+            coordinationService,
+            // 🔴 Supplied with NO source, and that is the point rather than a gap.
+            // §5.3 requires the user to always know whether a run is contained, so
+            // the shipped app must ANSWER — and with no substrate installed the
+            // true answer is `none`. This is also the seam an out-of-process
+            // `xeno-use` adapter plugs into later: supplying a source here changes
+            // every surface at once, and changes nothing else.
+            // 🔴 The SAME object that chose the executor. Constructing a bare
+            // `RunIsolationService()` here — as this line did — meant the report was
+            // computed from nothing while execution was decided elsewhere, which is
+            // precisely the drift the environment exists to make unrepresentable.
+            runIsolationService: new RunIsolationService({ source: runExecutionEnvironment }),
+            subagentRuns,
+            acpApprovalService: createAcpApprovalPortAdapter({
+                registry,
+                resolveConfig: (agentId) => registry.getAgentInternal(agentId),
+            }),
+            turnExecutionAdapters,
+        });
+        // Anything that subscribed before this point is attached now. Without this the subagent
+        // adapter's terminal-event listener stays in the pending set forever.
+        attachPendingHostSubscribers();
+        return coordinator;
+    };
+    let disposed = false;
+    const dispose = async () => {
+        if (disposed)
+            return;
+        disposed = true;
+        // Observation sandboxes go first: a container that outlives the process
+        // that spawned it is a leak nothing later will clean up, and the detached
+        // host had no owner for these at all until they moved here.
+        await runObserver?.stopAll();
+        // `stateRepository` is undefined when this composition never won the lease
+        // and so never created a coordinator — the ordinary case for a second app
+        // process. `close` is separately OPTIONAL on the port (the JSON
+        // implementation holds nothing), so both marks are load-bearing and neither
+        // is a defensive reflex.
+        await stateRepository?.close?.();
+    };
+    return {
+        createCoordinator,
+        paths,
+        registry,
+        runtimeStore,
+        workspaceAuthority,
+        workspaceShellService,
+        engineeringControlService,
+        runObservationService,
+        runObserver,
+        declaredUnavailable,
+        turnExecutionAdapterIds: turnExecutionAdapters.map((adapter) => adapter.id),
+        dispose,
+    };
+}
+/**
+ * The provider catalog.
+ *
+ * `sdkRunnable` is a parameter rather than being derived here, because whether
+ * the lane can run is a fact about the SURFACE, and this function only knows
+ * about credentials. Deriving it would make a headless host advertise a lane it
+ * cannot execute — the capability-honesty failure (§7.1) in its plainest form.
+ */
+export async function loadAgentHostProviders(registry, cloudOptions, options) {
+    const [acpProviders, cloudDiscovery] = await Promise.all([
+        createAcpRuntimeProviderDescriptors(registry),
+        discoverXenoCloudNodeRuntime(cloudOptions),
+    ]);
+    const hostedStatus = cloudDiscovery.hostedStatus;
+    const models = toXenoCloudAgentModelDescriptors(cloudDiscovery.modelCatalog.models);
+    const sdkUnavailableReason = sdkUnavailableReasonFor({
+        sdkRunnable: options.sdkRunnable,
+        directCredentialAvailable: cloudDiscovery.directCredentialAvailable,
+        modelCatalogError: cloudDiscovery.modelCatalog.error,
+    });
+    const sdkProvider = createSdkNativeRuntimeProviderDescriptor({
+        models,
+        runnable: options.sdkRunnable && cloudDiscovery.directCredentialAvailable,
+        // So the `context.inject` capability a client reads describes the store this host actually
+        // composed, rather than a sentence written when only one store existed.
+        durablePendingInjections: options.durablePendingInjections === true,
+        ...(sdkUnavailableReason ? { safeUnavailableReason: sdkUnavailableReason } : {}),
+    });
+    const safeUnavailableReason = hostedStatus.safeUnavailableReason || cloudDiscovery.modelCatalog.error;
+    const cloudProvider = createXenoCloudRuntimeProviderDescriptor({
+        authenticated: hostedStatus.authenticated && hostedStatus.ok,
+        controlCapabilities: hostedStatus.capabilities,
+        models,
+        ...(safeUnavailableReason ? { safeUnavailableReason } : {}),
+    });
+    return [sdkProvider, cloudProvider, ...acpProviders];
+}
+//# sourceMappingURL=composeHost.js.map