@pellux/goodvibes-tui 1.22.0 → 1.24.0

package/src/runtime/cluster-group-composition.ts

@@ -0,0 +1,284 @@
+/**
+ * cluster-group-composition.ts — this machine's membership of a LAN group.
+ *
+ * Leader election answers "which of us reads the inbox". This answers the
+ * question underneath it: "which machines are US". Without a group, any daemon
+ * that happened to be on the same network — a neighbour's, a colleague's, a
+ * container someone left running — would join the same coordination and one of
+ * you would silently stop receiving messages.
+ *
+ * The group layer owns the socket and the election rides on it: every
+ * coordination datagram is wrapped in the group envelope and signed with the
+ * current group key, so a datagram from outside the group never reaches the
+ * election at all. That is why `createClusterComposition` is handed a transport
+ * from here instead of opening one of its own.
+ *
+ * Key material lives ONLY in the encrypted secrets store. Never in config,
+ * never in a log line, never in `/status`.
+ */
+import {
+  ClusterGroupRuntime,
+  createClusterGroupVerbs,
+  createSystemClusterClock,
+  readClusterSettings,
+  rejoinGroup,
+  resolveClusterGroupSettings,
+  resolveNodeIdentity,
+  stillOnRoster,
+  UdpClusterTransport,
+  type ClusterGroupVerbSurface,
+  type ClusterSurfaceHolding,
+  type GroupOperationsContext,
+} from '@pellux/goodvibes-sdk/platform/cluster';
+import type { ConfigManager, SecretsManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ClusterTransport } from '@pellux/goodvibes-sdk/platform/cluster';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { createClusterComposition } from './cluster-composition.ts';
+import type { ClusterCoordinator } from '@pellux/goodvibes-sdk/platform/cluster';
+import { GOODVIBES_TUI_SURFACE_ROOT } from '../config/surface.ts';
+import { VERSION } from '../version.ts';
+
+export interface ClusterGroupComposition {
+  readonly runtime: ClusterGroupRuntime;
+  readonly verbs: ClusterGroupVerbSurface;
+  /** The transport the leader election must use, so its traffic is group-signed. */
+  readonly electionTransport: ClusterTransport;
+  /** Start the group layer. Safe to call more than once. */
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+/**
+ * A label for THIS machine in the member list.
+ *
+ * Deliberately NOT the hostname. The roster replicates to every member and the
+ * group name reaches the network in a beacon, so defaulting to a hostname would
+ * quietly publish "mikes-laptop" to anything listening. A short slice of the
+ * node id is meaningless and safe, and `cluster nodes` shows it plainly so an
+ * operator who wants a real name can see there is one to set.
+ */
+function defaultNodeDisplayName(nodeId: string): string {
+  return `machine ${nodeId.slice(0, 8)}`;
+}
+
+/**
+ * Build the group layer.
+ *
+ * Constructing it is inert: no socket is opened and no key material is read
+ * until `start()`, so composing a runtime in a test never touches the network
+ * or the secrets store.
+ */
+export function createClusterGroupComposition(options: {
+  readonly configManager: ConfigManager;
+  readonly shellPaths: ShellPathService;
+  readonly secretsManager: SecretsManager;
+  /**
+   * The leader election's own answer to "am I the master".
+   *
+   * Config replication needs exactly one machine issuing revisions, and it must
+   * be the SAME machine leadership already picked — two notions of master in
+   * one process would disagree the moment one of them changed.
+   *
+   * Late-bound because the coordinator is built from this composition's
+   * transport: it does not exist yet when this function runs.
+   */
+  readonly isMaster?: (() => boolean) | undefined;
+  /**
+   * Which surfaces this machine currently holds, and why.
+   *
+   * The per-surface election establishes this; the group layer only reports it,
+   * in `cluster status` and in /status. Late-bound for the same reason
+   * `isMaster` is. Absent means the group layer reports that the information is
+   * unavailable rather than reporting an empty list as though this machine held
+   * nothing — a distinction an operator diagnosing a silent inbox depends on.
+   */
+  readonly surfaceHoldings?: (() => readonly ClusterSurfaceHolding[]) | undefined;
+}): ClusterGroupComposition {
+  const settings = readClusterSettings(options.configManager);
+  const groupSettings = resolveClusterGroupSettings(
+    (options.configManager as { getCategory?: (name: string) => unknown }).getCategory?.('cluster'),
+  );
+  // Surface-scoped, alongside the election's node identity and this surface's
+  // other durable state.
+  const stateDirectory = options.shellPaths.resolveProjectPath(GOODVIBES_TUI_SURFACE_ROOT, 'cluster');
+  const nodeId = resolveNodeIdentity({ stateDirectory, logger }).nodeId;
+
+  const runtime = new ClusterGroupRuntime({
+    settings: groupSettings,
+    transport: new UdpClusterTransport({
+      port: settings.port,
+      multicastGroup: settings.multicastGroup,
+      peers: settings.peers,
+      logger,
+    }),
+    // Narrower than the SecretsManager itself: the group layer gets get/set/
+    // delete on one key and nothing else.
+    secrets: {
+      get: (key) => options.secretsManager.get(key),
+      set: (key, value) => options.secretsManager.set(key, value),
+      delete: (key) => options.secretsManager.delete(key),
+    },
+    stateDirectory,
+    nodeId,
+    nodeDisplayName: defaultNodeDisplayName(nodeId),
+    version: VERSION,
+    clock: createSystemClusterClock(),
+    logger,
+    ...(options.isMaster ? { isMaster: options.isMaster } : {}),
+    ...(options.surfaceHoldings ? { surfaceHoldings: options.surfaceHoldings } : {}),
+    // Only daemon-owned, group-scoped keys ever reach this; the SDK's
+    // replication policy decides which, and refuses anything machine-specific.
+    config: {
+      get: (path) => (options.configManager as unknown as {
+        get(key: string): unknown;
+      }).get(path),
+      set: (path, value) => (options.configManager as unknown as {
+        set(key: string, value: unknown): void;
+      }).set(path, value),
+    },
+  });
+
+  const context: GroupOperationsContext = {
+    runtime,
+    secrets: {
+      get: (key) => options.secretsManager.get(key),
+      set: (key, value) => options.secretsManager.set(key, value),
+      delete: (key) => options.secretsManager.delete(key),
+    },
+    settings: groupSettings,
+    nodeId,
+    nodeDisplayName: defaultNodeDisplayName(nodeId),
+    version: VERSION,
+    now: () => Date.now(),
+  };
+
+  let started = false;
+  return {
+    runtime,
+    verbs: createClusterGroupVerbs(context),
+    electionTransport: runtime.electionTransport(),
+    start: async () => {
+      if (started) return;
+      started = true;
+      await runtime.start();
+      await announceReturn(runtime, context, nodeId);
+    },
+    stop: async () => {
+      started = false;
+      await runtime.stop();
+    },
+  };
+}
+
+/**
+ * Build both halves of the LAN cluster, wired to each other.
+ *
+ * They are mutually dependent and the dependency runs both ways, which is why
+ * this exists rather than two calls at the composition root: the election
+ * coordinates over the GROUP's transport, and the group's config replication
+ * needs the ELECTION's answer to "am I the master". The master signal is read
+ * through a closure because the coordinator does not exist yet when the group
+ * layer is constructed.
+ *
+ * Constructing either is inert — no socket, no key material read — until
+ * `startCluster` runs.
+ */
+export function createClusterServices(options: {
+  readonly configManager: ConfigManager;
+  readonly shellPaths: ShellPathService;
+  readonly secretsManager: SecretsManager;
+}): { readonly clusterGroup: ClusterGroupComposition; readonly clusterCoordinator: ClusterCoordinator } {
+  let coordinator: ClusterCoordinator | null = null;
+  const clusterGroup = createClusterGroupComposition({
+    ...options,
+    isMaster: () => coordinator?.isMaster ?? false,
+    // The elections actually running are the only honest source for this, so
+    // the group layer reads them rather than keeping a second tally that could
+    // disagree. Before the coordinator exists there is nothing to report, and
+    // an empty list is the truthful answer at that point: no election has been
+    // held, so this machine holds nothing.
+    surfaceHoldings: () => coordinator?.surfaceHoldings() ?? [],
+  });
+  coordinator = createClusterComposition({
+    configManager: options.configManager,
+    shellPaths: options.shellPaths,
+    transport: clusterGroup.electionTransport,
+  });
+  return { clusterGroup, clusterCoordinator: coordinator };
+}
+
+/**
+ * Start the LAN cluster, in the order it has to be started in.
+ *
+ * The group layer FIRST: it owns the socket the leader election coordinates
+ * over, and starting the election against a transport whose group is not yet
+ * loaded would sign its first datagrams with nothing. Both calls are
+ * idempotent, so a composition root that reaches this twice is fine.
+ */
+export async function startClusterServices(services: {
+  readonly clusterGroup: Pick<ClusterGroupComposition, 'start'>;
+  readonly clusterCoordinator: { start(): Promise<void> };
+}): Promise<void> {
+  await services.clusterGroup.start();
+  await services.clusterCoordinator.start();
+}
+
+/**
+ * Ask the group to take this machine back, on start.
+ *
+ * This is the zero-touch return. A machine that has been switched off for
+ * months — through many group-key rotations and possibly a join-key change —
+ * comes up holding stale keys, says "it is still me" with a key that never
+ * rotates, and is re-keyed to the current generation by whichever member
+ * answers. The operator does nothing.
+ *
+ * It runs only when this machine still believes it is on the roster. A machine
+ * that was REMOVED asks for nothing: it would be refused, and asking anyway
+ * would put a pointless refusal in everyone's logs every time it started.
+ */
+async function announceReturn(
+  runtime: ClusterGroupRuntime,
+  context: GroupOperationsContext,
+  nodeId: string,
+): Promise<void> {
+  if (runtime.membership !== 'member') return;
+  if (!stillOnRoster(runtime.groupState, nodeId)) return;
+  const result = await rejoinGroup(context);
+  if (result.ok) {
+    logger.info('cluster: rejoined the group and took the current group key', {
+      group: result.data.groupName,
+      members: result.data.memberCount,
+    });
+    return;
+  }
+  if (result.terminal) {
+    // A member refused this machine and proved it was a member when it did.
+    // Retrying will never succeed, so this is not a quiet debug line: without
+    // it the operator sees a healthy daemon that is simply never given any
+    // work, with nothing anywhere saying why. Stated at ERROR with the command
+    // that fixes it, the same standard a surface this node cannot serve is
+    // held to.
+    logger.error('cluster: this machine is no longer in its group and will not be given work', {
+      reason: result.error,
+      action: result.fix,
+    });
+    return;
+  }
+  if (result.failure === 'unverifiable-replies') {
+    // Something answered and none of it could be authenticated. This machine
+    // cannot tell a removal it slept through from a stranger making noise, so
+    // it says exactly that and does not assert either. WARN rather than ERROR
+    // for the same reason: anything on the network can produce this, and a
+    // machine that shouted "you were removed" on cue would be worse than one
+    // that stayed quiet.
+    logger.warn('cluster: replies to this machine\'s return could not be authenticated', {
+      reason: result.error,
+      action: result.fix,
+    });
+    return;
+  }
+  // Not an error. A machine that starts first, or is alone on the network, has
+  // nobody to answer it and carries on with the keys it already holds.
+  logger.debug('cluster: no other machine answered the return announcement', { reason: result.error });
+}

package/src/runtime/daemon-handler-composition.ts

@@ -0,0 +1,80 @@
+/**
+ * daemon-handler-composition.ts — the daemon's HOST-side handler surfaces.
+ *
+ * Attaches this repository's handlers to the SDK-auto-registered builtin
+ * gateway descriptors (channels.* / email.* / calendar.*) via
+ * catalog.register(descriptor, handler, { replace: true }) — the SDK owns
+ * every id, descriptor and schema; only the behaviour is ours. The remote
+ * surface reuses the SAME DistributedRuntimeManager the SDK facade injects.
+ *
+ * Split out of services.ts for the 800-line file cap, the same reason
+ * channel-composition.ts exists.
+ *
+ * The one behavioural decision that lives here: the inbox poller is handed to
+ * the cluster coordinator instead of being started eagerly. It is this
+ * product's own inbound consumer — the SDK facade does not know it exists —
+ * so if it is not gated here it is not gated anywhere, and two goodvibes nodes
+ * on one network each read the shared inbox and answer the same message twice.
+ */
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ClusterCoordinator } from '@pellux/goodvibes-sdk/platform/cluster';
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { SecretsManager } from '@pellux/goodvibes-sdk/platform/config';
+import { registerDaemonHandlers, type DaemonHandlerSurfaces } from '../daemon/handlers/index.ts';
+import type { HandlerContext, HandlerLogger } from '../daemon/handlers/context.ts';
+import { createDaemonCredentialStore } from '../daemon/handlers/credentials.ts';
+import { registerRouting } from '../daemon/handlers/routing/index.ts';
+import { registerInboxMethods } from '../daemon/handlers/inbox/index.ts';
+import { registerTriagedInbox } from '../daemon/handlers/triage/index.ts';
+import { registerDraftMethods } from '../daemon/handlers/drafts/index.ts';
+import { registerCalendar } from '../daemon/handlers/calendar/index.ts';
+import { registerEmailMethods } from '../daemon/handlers/email/index.ts';
+import { registerRemoteSurface } from '../daemon/handlers/remote/index.ts';
+import { inboxPollerGate } from './cluster-composition.ts';
+
+export interface DaemonHandlerCompositionOptions {
+  readonly gatewayMethods: GatewayMethodCatalog;
+  readonly secretsManager: SecretsManager;
+  readonly configManager: ConfigManager;
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  readonly distributedRuntime: NonNullable<Parameters<typeof registerRemoteSurface>[1]>['manager'];
+  /**
+   * Decides whether THIS node polls the shared inbox. Always supplied by the
+   * composition root; the poller is never started outside it.
+   */
+  readonly clusterCoordinator: ClusterCoordinator;
+}
+
+export function createDaemonHandlerComposition(
+  options: DaemonHandlerCompositionOptions,
+): DaemonHandlerSurfaces {
+  const handlerLogger: HandlerLogger = {
+    info: (message, meta) => console.info(message, meta ?? ''),
+    warn: (message, meta) => console.warn(message, meta ?? ''),
+    error: (message, meta) => console.error(message, meta ?? ''),
+  };
+  const handlerContext: HandlerContext = {
+    catalog: options.gatewayMethods,
+    credentials: createDaemonCredentialStore(options.secretsManager),
+    configManager: options.configManager,
+    workingDirectory: options.workingDirectory,
+    homeDirectory: options.homeDirectory,
+    logger: handlerLogger,
+  };
+  return registerDaemonHandlers(handlerContext, {
+    registerRouting,
+    registerInbox: (ctx, routing) =>
+      registerTriagedInbox(ctx, (inboxCtx) => registerInboxMethods(inboxCtx, routing, {
+        // Hands polling to leadership. The `channels.inbox.list` read stays
+        // available on every node — a standby still SERVES the persisted feed,
+        // it just does not FETCH into it.
+        gatePolling: (providerId, control) =>
+          options.clusterCoordinator.register(inboxPollerGate(providerId, control)),
+      })).unregister,
+    registerDrafts: (ctx) => registerDraftMethods(ctx),
+    registerCalendar,
+    registerEmail: (ctx) => registerEmailMethods(ctx),
+    registerRemote: (ctx) => registerRemoteSurface(ctx, { manager: options.distributedRuntime }),
+  });
+}

package/src/runtime/disposal-wiring.ts

@@ -0,0 +1,66 @@
+/**
+ * disposal-wiring.ts
+ *
+ * Teardown for every poller this surface's runtime graph starts.
+ *
+ * The mechanics — the ordered, best-effort, idempotent scope and the
+ * all-required owner list — live in the SDK (`platform/runtime/disposal`), so
+ * this surface and the SDK's own composition root cannot drift into two
+ * different ideas of what "stop the graph" means. What lives here is only the
+ * mapping from this fork's assembled graph onto that list.
+ *
+ * It is a separate module because `runtime/services.ts` sits against the repo's
+ * 800-line source cap (check-architecture.ts) with no room for the wiring.
+ *
+ * Ownership note, and the reason any of this exists: this surface builds the
+ * graph and hands the SAME object to `DaemonServer`. The SDK facade disposes
+ * only a graph it constructed itself, so it deliberately leaves this one alone
+ * — nothing upstream will ever stop these pollers. The shutdown paths in
+ * daemon/cli.ts, main.ts's teardown registry and the one-shot CLI commands are
+ * the only things that can.
+ *
+ * The owner type below is declared structurally rather than imported from
+ * services.ts: that module imports this one, and a type-only edge is still a
+ * cycle to the architecture check.
+ */
+
+import {
+  createDisposalScope,
+  registerRuntimePollers,
+  type DisposalRegistry,
+  type RuntimePollerOwners,
+} from '@pellux/goodvibes-sdk/platform/runtime/disposal';
+
+/** Re-exported so the composition root reaches the whole seam through one import. */
+export { createDisposalScope };
+
+/** The assembled graph, narrowed to the poller owners it exposes as fields. */
+export interface SurfaceRuntimePollerOwners extends Omit<RuntimePollerOwners, 'stopConfigWatch'> {
+  /** Fork-only: the repeating crash-residue sweep (durability-services.ts). */
+  readonly stopDurabilityHousekeeping: () => void;
+}
+
+/**
+ * The poller owners this fork holds that are NOT reachable from the assembled
+ * graph — handles the factory keeps as locals.
+ */
+export interface RuntimeDisposalExtras {
+  /** Handle returned by `ConfigManager.watchConfigFiles()` (durability-services.ts). */
+  readonly stopConfigWatch: () => void;
+}
+
+/**
+ * Register the stop call for every poller the graph started.
+ *
+ * `services` is the fully-assembled graph, which already exposes each poller
+ * owner as a field — so a poller whose owner reaches the public surface is
+ * wired by name rather than by threading another local out of the factory.
+ */
+export function registerSurfaceRuntimePollers(
+  registry: DisposalRegistry,
+  services: SurfaceRuntimePollerOwners,
+  extras: RuntimeDisposalExtras,
+): void {
+  registerRuntimePollers(registry, { ...services, stopConfigWatch: extras.stopConfigWatch });
+  registry.add('durability housekeeping', services.stopDurabilityHousekeeping);
+}

package/src/runtime/durability-services.ts

@@ -93,6 +93,8 @@ export interface DurabilityServices {
    * the work rather than to release the loop.
    */
   readonly stopDurabilityHousekeeping: () => void;
+  /** Stops the live config-file watch this factory started. */
+  readonly stopConfigWatch: () => void;
 }
 
 export function createDurabilityServices(input: DurabilityServicesInput): DurabilityServices {
@@ -141,11 +143,13 @@ export function createDurabilityServices(input: DurabilityServicesInput): Durabi
     extraQuarantineDirs: [configManager.getControlPlaneConfigDir()],
   });
   // External config edits apply LIVE through the same subscribe() pipeline an
-  // in-process set() uses; the underlying watchers are unref'd.
-  configManager.watchConfigFiles();
+  // in-process set() uses; the underlying watchers are unref'd. The returned
+  // handle is the only way to stop them — dropping it left a 250ms poll running
+  // for the life of the process after the graph that started it was gone.
+  const stopConfigWatch = configManager.watchConfigFiles();
 
   const userPermissionRuleStore = new UserPermissionRuleStore(join(configManager.getControlPlaneConfigDir(), 'permission-rules.json'));
   void userPermissionRuleStore.init().catch((error) => logger.warn('user permission rule store init failed; asks will prompt', { error: summarizeError(error) }));
 
-  return { storeSnapshotScheduler, appendOnlyRetentionScheduler, userPermissionRuleStore, stopDurabilityHousekeeping };
+  return { storeSnapshotScheduler, appendOnlyRetentionScheduler, userPermissionRuleStore, stopDurabilityHousekeeping, stopConfigWatch };
 }

package/src/runtime/embedded-service-factories.ts

@@ -11,12 +11,23 @@
  * at all. See daemon/lifecycle.ts.
  */
 import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
+import type { ClusterCoordinator, ClusterGroupVerbSurface } from '@pellux/goodvibes-sdk/platform/cluster';
 import { createSafeHostServeFactory } from '../daemon/safe-serve.ts';
 import type { startExternalServices } from '@/runtime/index.ts';
 
 export type ExternalServiceFactories = NonNullable<Parameters<typeof startExternalServices>[4]>;
 
-export function createEmbeddedServiceFactories(sharedDaemonToken: string): ExternalServiceFactories {
+/**
+ * `clusterCoordinator` is threaded through explicitly rather than read off the
+ * runtimeServices the SDK hands the factory: that object is typed by the SDK,
+ * which has no field for a coordinator this product composed. Passing it here
+ * keeps the ONE-coordinator-per-process rule enforceable by the type checker.
+ */
+export function createEmbeddedServiceFactories(
+  sharedDaemonToken: string,
+  clusterCoordinator: ClusterCoordinator,
+  clusterGroupVerbs: ClusterGroupVerbSurface,
+): ExternalServiceFactories {
   return {
     sharedDaemonToken,
     createDaemonServer: (bus, userAuth, runtimeServices) => {
@@ -27,6 +38,13 @@ export function createEmbeddedServiceFactories(sharedDaemonToken: string): Exter
         userAuth,
         runtimeServices,
         serveFactory: createSafeHostServeFactory('Embedded daemon'),
+        // The SAME coordinator the inbox poller registered with. Letting the
+        // facade compose its own would put two election nodes in one process,
+        // and whichever lost would silence consumers the other owns.
+        clusterCoordinator,
+        // The `cluster` verbs (/api/cluster/*), so the CLI and the TUI command
+        // reach one implementation whether the daemon is embedded or standalone.
+        clusterGroupVerbs,
       });
       return daemonServer;
     },

package/src/runtime/process-lifecycle.ts

@@ -19,7 +19,7 @@
  * `unsubs` registry is shared by reference and drained on exit.
  */
 import { existsSync } from 'node:fs';
-import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { flushActivityLogSync, logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { createTerminalLifecycle, TERMINAL_ESCAPES } from '@pellux/goodvibes-terminal-shell';
 import { formatUserFacingErrorLine } from '../core/format-user-error.ts';
 import { allowTerminalWrite } from './terminal-output-guard.ts';
@@ -201,11 +201,17 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
   const uncaughtExceptionHandler = (err: Error): void => {
     restoreTerminal();
     logger.error('uncaughtException — terminal restored, exiting', { error: summarizeError(err) });
+    // The line naming the crash is the only record of it. process.exit does not
+    // drain the activity log's buffer, so it goes to disk here rather than
+    // relying on the exit hook that also runs — the crash log is worth stating
+    // the intent for at the site that produces it.
+    flushActivityLogSync();
     process.exit(1);
   };
   const terminationSignalHandler = (signal: NodeJS.Signals): void => {
     restoreTerminal();
     logger.error(`Received ${signal} — terminal restored, exiting`, {});
+    flushActivityLogSync();
     process.exit(signal === 'SIGHUP' ? 129 : 143);
   };
   const exitListener = (): void => { restoreTerminal(); };
@@ -285,6 +291,8 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     // stop claiming the session is live regardless of whether the durable
     // save itself completed in time.
     removeLivenessMarker(ctx.services.surface, ctx.runtime.sessionId);
+    // An orderly exit's own record lands before the process stops being one.
+    flushActivityLogSync();
     process.exit(0);
   };
 

package/src/runtime/remote-execution-composition.ts

@@ -0,0 +1,62 @@
+/**
+ * remote-execution-composition.ts — running work somewhere other than here.
+ *
+ * Four collaborators that only make sense together, so they are built together
+ * rather than as four unrelated lines in the middle of the runtime composition:
+ *
+ *   - RemoteRunnerRegistry knows which remote runners exist and how to reach
+ *     them; RemoteSupervisor drives them and is meaningless without it.
+ *
+ *   - SandboxSessionRegistry owns the sandboxes a tool call can be confined to,
+ *     and McpRegistry is the thing that confines them — an MCP server started
+ *     without the sandbox registry runs its tools directly on the host.
+ *
+ * The pairing in each case is the point: handing the supervisor a registry it
+ * did not build, or the MCP registry a sandbox runtime it does not share with
+ * the session registry, produces a runtime that looks wired and quietly is not.
+ */
+import { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp';
+import {
+  RemoteRunnerRegistry,
+  RemoteSupervisor,
+  SandboxSessionRegistry,
+  type RuntimeEventBus,
+} from '@/runtime/index.ts';
+import type { AgentManager } from '@pellux/goodvibes-sdk/platform/tools';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { HookDispatcher } from '@pellux/goodvibes-sdk/platform/hooks';
+
+export interface RemoteExecutionServices {
+  readonly remoteRunnerRegistry: RemoteRunnerRegistry;
+  readonly remoteSupervisor: RemoteSupervisor;
+  readonly sandboxSessionRegistry: SandboxSessionRegistry;
+  readonly mcpRegistry: McpRegistry;
+}
+
+/**
+ * Build the remote-execution and sandboxing seam.
+ *
+ * Constructing these opens no connection and starts no server: a runner is
+ * reached when something asks for it, and an MCP server starts when a session
+ * requests it. Composing a runtime in a test therefore executes nothing.
+ */
+export function createRemoteExecutionServices(options: {
+  readonly agentManager: AgentManager;
+  readonly workingDirectory: string;
+  readonly hookDispatcher: HookDispatcher;
+  readonly configManager: ConfigManager;
+  readonly runtimeBus: RuntimeEventBus;
+}): RemoteExecutionServices {
+  const remoteRunnerRegistry = new RemoteRunnerRegistry(options.agentManager);
+  const remoteSupervisor = new RemoteSupervisor(remoteRunnerRegistry);
+  const sandboxSessionRegistry = new SandboxSessionRegistry(options.workingDirectory);
+  const mcpRegistry = new McpRegistry({
+    hookDispatcher: options.hookDispatcher,
+    sandboxSessions: sandboxSessionRegistry,
+  });
+  mcpRegistry.setRuntimeBus(options.runtimeBus);
+  // The SAME sandbox registry the session registry above owns, so a tool call
+  // confined by one is confined by the other.
+  mcpRegistry.setSandboxRuntime(options.configManager, sandboxSessionRegistry);
+  return { remoteRunnerRegistry, remoteSupervisor, sandboxSessionRegistry, mcpRegistry };
+}