@pellux/goodvibes-daemon 1.28.0

package/src/daemon/handlers/remote/backends/process-runner.ts

@@ -0,0 +1,127 @@
+// Shared subprocess runner built on Bun.spawn. Captures stdout/stderr/exit code
+// with a hard timeout. Used by every backend that shells out (docker/ssh/cloud/
+// local-process). No credentials are ever passed as argv — callers pass key
+// material via files or the `env` overlay.
+
+export interface RunOptions {
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs: number;
+}
+
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+interface BunSubprocessLike {
+  readonly stdout: ReadableStream<Uint8Array> | null;
+  readonly stderr: ReadableStream<Uint8Array> | null;
+  readonly stdin: { write(chunk: string): void; end(): void | Promise<void> } | null;
+  readonly exited: Promise<number>;
+  kill(signal?: number | string): void;
+}
+
+interface BunSpawnOptions {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stdin?: 'pipe' | 'ignore';
+  stdout: 'pipe';
+  stderr: 'pipe';
+}
+
+type BunSpawn = (cmd: string[], options: BunSpawnOptions) => BunSubprocessLike;
+
+function getBunSpawn(): BunSpawn {
+  const globalBun = (globalThis as { Bun?: { spawn?: unknown } }).Bun;
+  if (!globalBun || typeof globalBun.spawn !== 'function') {
+    throw new Error('Bun.spawn is unavailable in this runtime.');
+  }
+  return globalBun.spawn as unknown as BunSpawn;
+}
+
+async function readStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (!stream) return '';
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let out = '';
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+  return out;
+}
+
+/**
+ * Spawn a subprocess and capture its output with a hard timeout. The first
+ * element of `args` is the executable. Throws only on spawn failure; non-zero
+ * exit codes are returned in the result.
+ *
+ * On timeout the child is killed with SIGKILL and `child.exited` is awaited so
+ * no orphaned subprocess is left running after the timeout fires.
+ */
+export async function runProcess(options: RunOptions): Promise<RunResult> {
+  if (options.args.length === 0) {
+    throw new Error('runProcess requires at least one argument (the executable).');
+  }
+  const spawn = getBunSpawn();
+  const mergedEnv: Record<string, string | undefined> = {
+    ...process.env,
+    ...(options.env ?? {}),
+  };
+
+  const child = spawn(options.args, {
+    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    env: mergedEnv,
+    stdin: options.stdin !== undefined ? 'pipe' : 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  if (options.stdin !== undefined && child.stdin) {
+    child.stdin.write(options.stdin);
+    await child.stdin.end();
+  }
+
+  let timedOut = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // process may have already exited
+      }
+      resolve();
+    }, options.timeoutMs);
+  });
+
+  // Always await the child's real exit. On timeout we SIGKILL above, then the
+  // race resolves via child.exited (which settles once the kill takes effect),
+  // guaranteeing the subprocess is reaped rather than orphaned.
+  const [stdout, stderr, exitCode] = await Promise.all([
+    readStream(child.stdout),
+    readStream(child.stderr),
+    Promise.race([child.exited, timeoutPromise.then(() => child.exited)]),
+  ]);
+
+  if (timer) clearTimeout(timer);
+
+  return {
+    exitCode: typeof exitCode === 'number' ? exitCode : -1,
+    stdout,
+    stderr,
+    timedOut,
+  };
+}

package/src/daemon/handlers/remote/backends/ssh.ts

@@ -0,0 +1,126 @@
+import { mkdir, writeFile, rm, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import type { PeerRecord } from '../peer-registry.ts';
+import type { SshBackendConfig } from '../peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type BackendDispatchResult,
+  type DispatchPayload,
+  BackendDispatchError,
+  resolveTimeout,
+  buildRemoteShellCommand,
+} from './types.ts';
+import { runProcess } from './process-runner.ts';
+import { tokenizeCommand } from './local-process.ts';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../../../../config/surface.ts';
+
+/**
+ * Persistent-key material is written to {homeDirectory}/.goodvibes/tui/operator/
+ * ssh-keys/{peerId}.key with 0600 permissions and reused across invocations
+ * (connection pooling via the OpenSSH ControlMaster multiplexer). The key value
+ * itself comes only from the daemon credential store — never argv, never logs.
+ */
+interface PooledIdentity {
+  keyPath: string;
+  controlPath: string;
+  identityRef: string;
+}
+
+export function createSshBackend(ctx: BackendContext): Backend {
+  const pool = new Map<string, PooledIdentity>();
+  const keyDir = join(ctx.homeDirectory, '.goodvibes', GOODVIBES_DAEMON_SURFACE_ROOT, 'operator', 'ssh-keys');
+
+  async function ensureIdentity(
+    peer: PeerRecord,
+    config: SshBackendConfig,
+  ): Promise<PooledIdentity> {
+    const existing = pool.get(peer.peerId);
+    if (existing && existing.identityRef === config.identityRef) {
+      return existing;
+    }
+    const key = await ctx.credentials.resolveRef(config.identityRef);
+    if (!key || key.length === 0) {
+      throw new BackendDispatchError(
+        `Could not resolve SSH identity for peer '${peer.peerId}'.`,
+        'REMOTE_BACKEND_CREDENTIAL_MISSING',
+      );
+    }
+    await mkdir(keyDir, { recursive: true });
+    await chmod(keyDir, 0o700).catch(() => {});
+    const suffix = randomBytes(4).toString('hex');
+    const keyPath = join(keyDir, `${peer.peerId}.${suffix}.key`);
+    const normalizedKey = key.endsWith('\n') ? key : `${key}\n`;
+    await writeFile(keyPath, normalizedKey, { mode: 0o600 });
+    await chmod(keyPath, 0o600).catch(() => {});
+    const controlPath = join(keyDir, `${peer.peerId}.${suffix}.ctl`);
+    const identity: PooledIdentity = { keyPath, controlPath, identityRef: config.identityRef };
+    // Replace any prior identity for this peer and clean up its key file.
+    if (existing) await rm(existing.keyPath, { force: true }).catch(() => {});
+    pool.set(peer.peerId, identity);
+    return identity;
+  }
+
+  return {
+    kind: 'ssh',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'ssh') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not an ssh peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'ssh' } & SshBackendConfig;
+      if (tokenizeCommand(command).length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+      const identity = await ensureIdentity(peer, config);
+      const port = config.sshPort ?? 22;
+      const target = `${config.sshUser}@${config.sshHost}`;
+      const remoteCommand = buildRemoteShellCommand(command, payload?.args);
+
+      const args = [
+        'ssh',
+        '-i', identity.keyPath,
+        '-p', String(port),
+        '-o', 'StrictHostKeyChecking=accept-new',
+        '-o', 'BatchMode=yes',
+        '-o', 'ConnectTimeout=15',
+        // Connection pooling: reuse a multiplexed master for ~60s.
+        '-o', 'ControlMaster=auto',
+        '-o', `ControlPath=${identity.controlPath}`,
+        '-o', 'ControlPersist=60',
+        target,
+        remoteCommand,
+      ];
+
+      ctx.logger.info('remote ssh dispatch', {
+        peerId: peer.peerId,
+        host: config.sshHost,
+        port,
+      });
+      const result = await runProcess({
+        args,
+        timeoutMs: resolveTimeout(payload),
+        ...(payload?.env !== undefined ? { env: payload.env } : {}),
+        ...(payload?.stdin !== undefined ? { stdin: payload.stdin } : {}),
+      });
+      return {
+        exitCode: result.timedOut ? 124 : result.exitCode,
+        stdout: result.stdout,
+        stderr: result.timedOut ? `${result.stderr}\n[remote] ssh command timed out` : result.stderr,
+      };
+    },
+    async teardown(): Promise<void> {
+      // Sweep every pooled key file plus the ssh-keys/ dir so no private-key
+      // material (or stale ControlMaster sockets) outlives the daemon process.
+      pool.clear();
+      await rm(keyDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}

package/src/daemon/handlers/remote/backends/types.ts

@@ -0,0 +1,97 @@
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import type { HandlerLogger } from '../../context.ts';
+import type { PeerRecord } from '../peer-registry.ts';
+
+/**
+ * Payload accepted alongside a command on remote.peers.invoke. All fields are
+ * optional; backends interpret what they support.
+ */
+export interface DispatchPayload {
+  /** Positional args appended to the command (already tokenized). */
+  args?: string[];
+  /** Data piped to the process stdin. */
+  stdin?: string;
+  /** Per-invocation environment overlay (never includes secrets). */
+  env?: Record<string, string>;
+  /** Hard timeout for synchronous execution, in milliseconds. */
+  timeoutMs?: number;
+  /** Working directory override (backend-dependent). */
+  cwd?: string;
+}
+
+export interface BackendDispatchResult {
+  exitCode?: number;
+  workId?: string;
+  stdout: string;
+  stderr: string;
+}
+
+export interface BackendContext {
+  credentials: DaemonCredentialStore;
+  logger: HandlerLogger;
+  /** Daemon home dir — used for ephemeral key material under a 0700 subdir. */
+  homeDirectory: string;
+}
+
+/**
+ * A remote execution backend. Each backend dispatches a single command for a
+ * given peer and returns the captured stdout/stderr plus an exit code.
+ *
+ * Backends must NEVER place raw credentials in the returned stdout/stderr or in
+ * any thrown error message. Credentials are resolved internally from the daemon
+ * credential store via secret references on the peer's backendConfig.
+ */
+export interface Backend {
+  readonly kind: PeerRecord['backendKind'];
+  dispatch(
+    peer: PeerRecord,
+    command: string,
+    payload?: DispatchPayload,
+  ): Promise<BackendDispatchResult>;
+  /**
+   * Best-effort cleanup of any on-disk material the backend created (ephemeral
+   * key/credential files and their containing dirs). Called from the surface
+   * teardown so secrets do not outlive the daemon process. Optional: backends
+   * that write nothing to disk omit it.
+   */
+  teardown?(): Promise<void>;
+}
+
+export const DEFAULT_SYNC_TIMEOUT_MS = 120_000;
+export const MAX_SYNC_TIMEOUT_MS = 600_000;
+
+export function resolveTimeout(payload?: DispatchPayload): number {
+  const requested = payload?.timeoutMs;
+  if (typeof requested === 'number' && Number.isFinite(requested) && requested > 0) {
+    return Math.min(requested, MAX_SYNC_TIMEOUT_MS);
+  }
+  return DEFAULT_SYNC_TIMEOUT_MS;
+}
+
+export class BackendDispatchError extends Error {
+  readonly code: string;
+  constructor(message: string, code = 'REMOTE_BACKEND_DISPATCH_FAILED') {
+    super(message);
+    this.name = 'BackendDispatchError';
+    this.code = code;
+  }
+}
+
+/**
+ * Compose the remote-shell command line for the shell-style backends
+ * (docker `sh -c`, ssh remote command, cloud-CLI `--command`/`--scripts`).
+ *
+ * REMOTE-SHELL SEMANTICS (intentional, documented asymmetry vs local-process):
+ * positional `payload.args` are joined onto the command with a single space and
+ * are NOT shell-escaped, because these backends hand a single command STRING to
+ * a remote shell — the operator's `command` may itself contain pipes, redirects,
+ * globs, or quoting that must survive the hop verbatim. The local-process
+ * backend, by contrast, never invokes a shell and passes args as discrete argv.
+ *
+ * This surface is operator/admin-gated (the SDK route enforces
+ * confirmation/explicitUserRequest before dispatch), so callers that need
+ * literal arguments must pre-quote them inside `command` or `args`.
+ */
+export function buildRemoteShellCommand(command: string, args?: string[]): string {
+  return args && args.length > 0 ? `${command} ${args.join(' ')}` : command;
+}

package/src/daemon/handlers/remote/dispatcher.ts

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+import type { HandlerLogger } from '../context.ts';
+import type { DaemonCredentialStore } from '../credentials.ts';
+import { PeerRegistry, type PeerRecord } from './peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type DispatchPayload,
+  BackendDispatchError,
+  createBackends,
+} from './backends/index.ts';
+
+/** SHA-256 of input, truncated to the first `hexChars` hex characters. */
+function sha256First(input: string, hexChars: number): string {
+  const digest = createHash('sha256').update(input, 'utf-8').digest('hex');
+  return digest.slice(0, Math.max(0, hexChars));
+}
+
+// ---------------------------------------------------------------------------
+// Work-item hook — long-running invocations are enqueued as work items visible
+// in remote.work.list. The dispatcher does not own the distributed runtime; the
+// integrator wires this hook to the DistributedRuntimeManager work queue.
+// ---------------------------------------------------------------------------
+
+export interface RemoteWorkItemInput {
+  peerId: string;
+  command: string;
+  payload?: DispatchPayload;
+  /** Echoed onto the work item so the runner can pick the right backend. */
+  backendKind: PeerRecord['backendKind'];
+  queuedBy: string;
+}
+
+export interface RemoteWorkEnqueuer {
+  enqueue(item: RemoteWorkItemInput): Promise<{ workId: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Invoke result — returned to the agent through remote.peers.invoke. Includes
+// stdoutDigest (sha256 of FULL stdout, 64 hex chars) per the receipt contract.
+// The agent may receive only a truncated stdout preview.
+// ---------------------------------------------------------------------------
+
+export const STDOUT_PREVIEW_LIMIT = 4_096;
+
+export interface RemoteInvokeResult {
+  peerId: string;
+  backendKind: PeerRecord['backendKind'];
+  /** Present for synchronous completion. */
+  exitCode?: number;
+  /** Present for async/long-running dispatch. */
+  workId?: string;
+  completed: boolean;
+  stdout: string;
+  stderr: string;
+  /** SHA-256 of the full stdout, 64 hex chars. */
+  stdoutDigest: string;
+}
+
+export interface RemoteDispatcherOptions {
+  registry: PeerRegistry;
+  credentials: DaemonCredentialStore;
+  logger: HandlerLogger;
+  homeDirectory: string;
+  /** Optional hook for enqueuing long-running work items. */
+  workEnqueuer?: RemoteWorkEnqueuer;
+  /** Override the backend map (tests inject fakes). */
+  backends?: Map<PeerRecord['backendKind'], Backend>;
+}
+
+export interface DispatchRequest {
+  peerId: string;
+  command: string;
+  payload?: DispatchPayload;
+  /** Principal that requested the dispatch (for work-item attribution). */
+  principalId: string;
+  /** When true (and a work enqueuer exists), run as an async work item. */
+  async?: boolean;
+}
+
+function truncate(value: string, limit: number): string {
+  return value.length > limit ? value.slice(0, limit) : value;
+}
+
+/**
+ * Routes remote.peers.invoke commands to the correct execution backend.
+ * Synchronous commands return an exitCode; long-running commands (async:true
+ * with a configured work enqueuer) return a workId tracked via remote.work.list.
+ */
+export class RemoteDispatcher {
+  private readonly registry: PeerRegistry;
+  private readonly backends: Map<PeerRecord['backendKind'], Backend>;
+  private readonly workEnqueuer?: RemoteWorkEnqueuer;
+  private readonly logger: HandlerLogger;
+
+  constructor(options: RemoteDispatcherOptions) {
+    this.registry = options.registry;
+    this.logger = options.logger;
+    if (options.workEnqueuer) this.workEnqueuer = options.workEnqueuer;
+    const backendContext: BackendContext = {
+      credentials: options.credentials,
+      logger: options.logger,
+      homeDirectory: options.homeDirectory,
+    };
+    this.backends = options.backends ?? createBackends(backendContext);
+  }
+
+  async dispatch(request: DispatchRequest): Promise<RemoteInvokeResult> {
+    const peerId = typeof request.peerId === 'string' ? request.peerId.trim() : '';
+    if (peerId.length === 0) {
+      throw new BackendDispatchError('peerId is required.', 'REMOTE_PEER_ID_REQUIRED');
+    }
+    const command = typeof request.command === 'string' ? request.command : '';
+    if (command.trim().length === 0) {
+      throw new BackendDispatchError('command is required.', 'REMOTE_COMMAND_REQUIRED');
+    }
+    const peer = this.registry.get(peerId);
+    if (!peer) {
+      throw new BackendDispatchError(
+        `No registered peer with id '${peerId}'.`,
+        'REMOTE_PEER_NOT_FOUND',
+      );
+    }
+    const backend = this.backends.get(peer.backendKind);
+    if (!backend) {
+      throw new BackendDispatchError(
+        `No backend available for kind '${peer.backendKind}'.`,
+        'REMOTE_BACKEND_UNAVAILABLE',
+      );
+    }
+
+    // Async path: enqueue a work item and return its id immediately.
+    if (request.async === true && this.workEnqueuer) {
+      const { workId } = await this.workEnqueuer.enqueue({
+        peerId: peer.peerId,
+        command,
+        backendKind: peer.backendKind,
+        queuedBy: request.principalId,
+        ...(request.payload !== undefined ? { payload: request.payload } : {}),
+      });
+      this.logger.info('remote invoke enqueued', { peerId: peer.peerId, workId });
+      return {
+        peerId: peer.peerId,
+        backendKind: peer.backendKind,
+        workId,
+        completed: false,
+        stdout: '',
+        stderr: '',
+        stdoutDigest: sha256First('', 64),
+      };
+    }
+
+    // Synchronous path: run on the backend and capture output.
+    const result = await backend.dispatch(peer, command, request.payload);
+    const fullStdout = result.stdout ?? '';
+    return {
+      peerId: peer.peerId,
+      backendKind: peer.backendKind,
+      ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+      ...(result.workId !== undefined ? { workId: result.workId } : {}),
+      completed: result.workId === undefined,
+      stdout: truncate(fullStdout, STDOUT_PREVIEW_LIMIT),
+      stderr: truncate(result.stderr ?? '', STDOUT_PREVIEW_LIMIT),
+      stdoutDigest: sha256First(fullStdout, 64),
+    };
+  }
+
+  /**
+   * Best-effort teardown: invoke every backend's optional teardown so ephemeral
+   * key/credential material (ssh-keys/, cloud-creds/) is swept from disk and
+   * does not outlive the daemon. Failures are swallowed — teardown must never
+   * throw during surface shutdown.
+   */
+  async teardown(): Promise<void> {
+    await Promise.all(
+      [...this.backends.values()].map((backend) =>
+        backend.teardown ? backend.teardown().catch(() => {}) : Promise.resolve(),
+      ),
+    );
+  }
+}

package/src/daemon/handlers/remote/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Remote handler surface — the host backend for `remote.peers.*`.
+ *
+ * `remote.peers.invoke` is NOT a catalog method: the SDK publishes it as an HTTP
+ * route and injects a `DistributedRuntimeRouteService` (the host's
+ * `HostDistributedRuntime`) into `DaemonRemoteRouteContext.distributedRuntime`.
+ * This module wires that service together:
+ *
+ *   - a `PeerRegistry` (peer-registry.sqlite; credential fields are
+ *     goodvibes://secrets/ refs, embedded secrets rejected),
+ *   - a `RemoteDispatcher` routing by backendKind to the docker/ssh/
+ *     cloud-terminal/local-process backends,
+ *   - the SDK `DistributedRuntimeManager` (store: tui/remote/distributed-runtime.json)
+ *     backing the 16 peer/pairing/work methods,
+ *   - the `HostDistributedRuntime` service implementing the 17-method contract.
+ *
+ * The returned registration is plugged into the foundation
+ * `DaemonHandlerSurfaceProviders.registerRemote` and surfaced on
+ * `DaemonHandlerSurfaces.remoteSurface` + `.remoteDispatch`. Stores init lazily
+ * (peer registry init is backgrounded) so wiring stays synchronous.
+ */
+import { join } from 'node:path';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+import type { HandlerContext } from '../context.ts';
+import type {
+  RemoteSurfaceRegistration,
+  RemoteInvokeAdapter,
+} from '../index.ts';
+import { PeerRegistry } from './peer-registry.ts';
+import { RemoteDispatcher, type RemoteWorkEnqueuer } from './dispatcher.ts';
+import { HostDistributedRuntime } from './service.ts';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../../../config/surface.ts';
+
+type DistributedRuntimeManager = operations.DistributedRuntimeManager;
+
+const DISTRIBUTED_RUNTIME_STORE = join(GOODVIBES_DAEMON_SURFACE_ROOT, 'remote', 'distributed-runtime.json');
+
+export interface RegisterRemoteSurfaceOptions {
+  /**
+   * Inject the distributed runtime manager (integration may construct it in
+   * services.ts so other runtime bridges can attach to the same instance). When
+   * omitted, the surface builds its own manager rooted under the project's
+   * .goodvibes directory.
+   */
+  readonly manager?: DistributedRuntimeManager;
+}
+
+/**
+ * Build the remote surface. Returns the teardown, the host
+ * `DistributedRuntimeRouteService` the SDK facade injects, and the
+ * `remote.peers.invoke` dispatch adapter.
+ */
+export function registerRemoteSurface(
+  ctx: HandlerContext,
+  options?: RegisterRemoteSurfaceOptions,
+): RemoteSurfaceRegistration {
+  const registry = new PeerRegistry(ctx.workingDirectory);
+
+  const manager =
+    options?.manager
+    ?? new operations.DistributedRuntimeManager(
+      join(ctx.workingDirectory, '.goodvibes', DISTRIBUTED_RUNTIME_STORE),
+    );
+
+  // Adapt the SDK manager's work queue to the dispatcher's enqueue hook so a
+  // production `remote.peers.invoke {async:true}` creates a work item visible
+  // in remote.work.list and returns its id (instead of running synchronously).
+  const workEnqueuer: RemoteWorkEnqueuer = {
+    enqueue: async (item) => {
+      // item.backendKind is intentionally NOT forwarded: the SDK enqueueWork
+      // contract has no backendKind parameter, and the work runner re-resolves
+      // the backend from the live peer record at claim time (so a peer that is
+      // re-registered onto a different backend before the work runs is honored).
+      const work = await manager.enqueueWork({
+        peerId: item.peerId,
+        command: item.command,
+        actor: item.queuedBy,
+        ...(item.payload !== undefined ? { payload: item.payload } : {}),
+      });
+      return { workId: work.id };
+    },
+  };
+
+  const dispatcher = new RemoteDispatcher({
+    registry,
+    credentials: ctx.credentials,
+    logger: ctx.logger,
+    homeDirectory: ctx.homeDirectory,
+    workEnqueuer,
+  });
+
+  const service = new HostDistributedRuntime(manager, dispatcher);
+
+  // Initialize persistent state lazily in the background so surface
+  // construction stays synchronous and never blocks daemon bootstrap.
+  void registry.init().catch((error) => {
+    ctx.logger.error('remote peer registry init failed', { error });
+  });
+  if (!options?.manager) {
+    void manager.start().catch((error) => {
+      ctx.logger.error('distributed runtime manager start failed', { error });
+    });
+  }
+
+  const dispatch: RemoteInvokeAdapter = {
+    invoke: (input: Record<string, unknown>) => service.invokePeer(input),
+  };
+
+  const unregister = (): void => {
+    registry.close();
+    // Best-effort, fire-and-forget sweep of ephemeral key/credential material
+    // (ssh-keys/, cloud-creds/) so no secret-bearing file outlives the surface.
+    // Kept off the synchronous teardown path; failures are swallowed inside.
+    void dispatcher.teardown().catch((error) => {
+      ctx.logger.error('remote backend teardown failed', { error });
+    });
+  };
+
+  return { unregister, service, dispatch };
+}