@pellux/goodvibes-tui 0.25.0 → 0.26.0

package/src/daemon/handlers/register.ts

@@ -0,0 +1,161 @@
+/**
+ * Linchpin helper that binds a typed host handler to an SDK-registered gateway
+ * method descriptor BY ID.
+ *
+ * The SDK's `GatewayMethodCatalog` constructor auto-registers every builtin
+ * descriptor (channels.* / email.* / calendar.* / ...) with `handler:undefined`.
+ * The host attaches its implementation by looking up that canonical descriptor
+ * via `catalog.get(id)` and re-registering it WITH the handler using
+ * `{ replace: true }`. Only the handler slot changes; the SDK's id, schema,
+ * access, scopes, and dangerous flags are preserved verbatim. No descriptor or
+ * schema is ever authored here.
+ */
+import type {
+  GatewayMethodCatalog,
+  GatewayMethodInvocation,
+  GatewayMethodInvocationContext,
+} from './contracts.ts';
+import { HandlerError, REQUIRE_CONFIRM } from './errors.ts';
+
+/** Function returned by every registration; calling it removes the attached handler. */
+export type Unregister = () => void;
+
+/** Normalized, host-facing principal/auth context derived from the SDK invocation. */
+export interface HandlerContextEnvelope {
+  readonly principalId: string;
+  readonly admin: boolean;
+  readonly scopes: string[];
+  readonly explicitUserRequest: boolean;
+  readonly authToken: string;
+}
+
+/** Typed, host-facing shape of a single method invocation. */
+export interface HandlerInvocation<TBody> {
+  readonly body: TBody;
+  readonly query: Record<string, string>;
+  readonly context: HandlerContextEnvelope;
+}
+
+/** A host handler: receives the typed invocation, returns the method result. */
+export type TypedHandler<TBody, TResult> = (
+  input: HandlerInvocation<TBody>,
+) => Promise<TResult>;
+
+export interface RegisterHandlerOptions {
+  /**
+   * When true, the wrapper enforces a confirmation gate before the handler
+   * runs: `body.confirm === true` AND `context.explicitUserRequest === true`.
+   */
+  readonly confirm?: boolean;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/**
+ * Derive the host-facing context envelope from the raw SDK invocation context.
+ * `explicitUserRequest` is carried in `context.metadata.explicitUserRequest`.
+ */
+export function normalizeContext(c: GatewayMethodInvocationContext): HandlerContextEnvelope {
+  const metadata = c.metadata ?? {};
+  return {
+    principalId: c.principalId ?? '',
+    admin: c.admin === true,
+    scopes: c.scopes ? [...c.scopes] : [],
+    explicitUserRequest: metadata.explicitUserRequest === true,
+    authToken: c.authToken ?? '',
+  };
+}
+
+function normalizeQuery(query: GatewayMethodInvocation['query']): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!query) return out;
+  for (const [key, value] of Object.entries(query)) {
+    if (typeof value === 'string') out[key] = value;
+    else if (value != null) out[key] = String(value);
+  }
+  return out;
+}
+
+/**
+ * Guard a confirmation-gated mutation. Throws `HandlerError(REQUIRE_CONFIRM, 403)`
+ * unless the caller both set `body.confirm === true` and the request was an
+ * explicit user request.
+ */
+export function assertConfirmed(
+  body: unknown,
+  ctx: { readonly explicitUserRequest: boolean },
+): void {
+  const confirmed =
+    typeof body === 'object'
+    && body !== null
+    && (body as { confirm?: unknown }).confirm === true;
+  if (!confirmed || ctx.explicitUserRequest !== true) {
+    throw new HandlerError('explicit user confirmation required', REQUIRE_CONFIRM, 403);
+  }
+}
+
+/**
+ * Attach a typed handler to the SDK-registered descriptor identified by
+ * `methodId`. Reuses the descriptor the catalog already holds and re-registers
+ * it with the wrapped handler via `{ replace: true }`, flipping the builtin
+ * method from HTTP-fallback to in-process execution.
+ */
+export function registerCatalogHandler<TBody, TResult>(
+  catalog: GatewayMethodCatalog,
+  methodId: string,
+  handler: TypedHandler<TBody, TResult>,
+  options?: RegisterHandlerOptions,
+): Unregister {
+  const descriptor = catalog.get(methodId);
+  if (!descriptor) {
+    throw new HandlerError(`Unknown gateway method: ${methodId}`, 'UNKNOWN_METHOD', 404);
+  }
+
+  const wrapped = async (inv: GatewayMethodInvocation): Promise<unknown> => {
+    const context = normalizeContext(inv.context);
+    const body = inv.body as TBody;
+    if (options?.confirm) assertConfirmed(inv.body, context);
+    try {
+      return await handler({ body, query: normalizeQuery(inv.query), context });
+    } catch (error) {
+      if (error instanceof HandlerError) throw error;
+      throw new HandlerError(errorMessage(error), 'HANDLER_FAILED', 500);
+    }
+  };
+
+  return catalog.register(descriptor, wrapped, { replace: true });
+}
+
+/** A single id→handler binding for batch registration. */
+export interface CatalogHandlerEntry {
+  readonly id: string;
+  readonly handler: TypedHandler<unknown, unknown>;
+  readonly options?: RegisterHandlerOptions;
+}
+
+/**
+ * Register many handlers at once. Returns a single `Unregister` that tears them
+ * down in REVERSE registration order (best-effort: a failing teardown never
+ * aborts the rest).
+ */
+export function registerCatalogHandlers(
+  catalog: GatewayMethodCatalog,
+  entries: readonly CatalogHandlerEntry[],
+): Unregister {
+  const teardowns: Unregister[] = [];
+  for (const entry of entries) {
+    teardowns.push(registerCatalogHandler(catalog, entry.id, entry.handler, entry.options));
+  }
+  return () => {
+    for (let i = teardowns.length - 1; i >= 0; i -= 1) {
+      try {
+        teardowns[i]!();
+      } catch {
+        // best-effort teardown; continue unwinding the rest
+      }
+    }
+  };
+}

package/src/daemon/{remote → handlers/remote}/backends/cloud-terminal.ts

@@ -10,6 +10,7 @@ import {
   type DispatchPayload,
   BackendDispatchError,
   resolveTimeout,
+  buildRemoteShellCommand,
 } from './types.ts';
 import { runProcess } from './process-runner.ts';
 import { tokenizeCommand } from './local-process.ts';
@@ -100,9 +101,7 @@ export function createCloudTerminalBackend(ctx: BackendContext): Backend {
           'REMOTE_BACKEND_CREDENTIAL_MISSING',
         );
       }
-      const remoteCommand = payload?.args && payload.args.length > 0
-        ? `${command} ${payload.args.join(' ')}`
-        : command;
+      const remoteCommand = buildRemoteShellCommand(command, payload?.args);
       const { args, credEnvKey } = buildArgs(config, remoteCommand);
       const credPath = await writeCredentialFile(peer.peerId, credential);
       const env: Record<string, string> = { ...(payload?.env ?? {}) };
@@ -133,5 +132,11 @@ export function createCloudTerminalBackend(ctx: BackendContext): Backend {
         await rm(credPath, { force: true }).catch(() => {});
       }
     },
+    async teardown(): Promise<void> {
+      // Per-invocation cred files are already removed in dispatch's finally;
+      // sweep the cloud-creds/ dir on teardown to clear any file orphaned by a
+      // hard crash mid-dispatch so no provider credential outlives the daemon.
+      await rm(credDir, { recursive: true, force: true }).catch(() => {});
+    },
   };
 }

package/src/daemon/{remote → handlers/remote}/backends/docker.ts

@@ -7,6 +7,7 @@ import {
   type DispatchPayload,
   BackendDispatchError,
   resolveTimeout,
+  buildRemoteShellCommand,
 } from './types.ts';
 import { runProcess } from './process-runner.ts';
 import { tokenizeCommand } from './local-process.ts';
@@ -52,9 +53,7 @@ export function createDockerBackend(ctx: BackendContext): Backend {
         env.DOCKER_HOST = resolved;
       }
 
-      const innerCommand = payload?.args && payload.args.length > 0
-        ? `${command} ${payload.args.join(' ')}`
-        : command;
+      const innerCommand = buildRemoteShellCommand(command, payload?.args);
 
       const args = ['docker', 'exec'];
       if (payload?.stdin !== undefined) args.push('-i');

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

@@ -0,0 +1,40 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import { type Backend, type BackendContext } from './types.ts';
+import { createLocalProcessBackend } from './local-process.ts';
+import { createDockerBackend } from './docker.ts';
+import { createSshBackend } from './ssh.ts';
+import { createCloudTerminalBackend } from './cloud-terminal.ts';
+
+export type {
+  Backend,
+  BackendContext,
+  BackendDispatchResult,
+  DispatchPayload,
+} from './types.ts';
+export {
+  BackendDispatchError,
+  DEFAULT_SYNC_TIMEOUT_MS,
+  MAX_SYNC_TIMEOUT_MS,
+  resolveTimeout,
+} from './types.ts';
+
+/**
+ * Build the full backend map keyed by backendKind. Each backend resolves its
+ * own credentials lazily from the daemon credential store on dispatch; no
+ * network or process work happens at construction time.
+ */
+export function createBackends(
+  ctx: BackendContext,
+): Map<PeerRecord['backendKind'], Backend> {
+  const backends: Backend[] = [
+    createLocalProcessBackend(ctx),
+    createDockerBackend(ctx),
+    createSshBackend(ctx),
+    createCloudTerminalBackend(ctx),
+  ];
+  const map = new Map<PeerRecord['backendKind'], Backend>();
+  for (const backend of backends) {
+    map.set(backend.kind, backend);
+  }
+  return map;
+}

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

@@ -44,10 +44,9 @@ function getBunSpawn(): BunSpawn {
   return globalBun.spawn as unknown as BunSpawn;
 }
 
-type StreamReader = ReadableStreamDefaultReader<Uint8Array>;
-
-async function drainReader(reader: StreamReader | null): Promise<string> {
-  if (!reader) return '';
+async function readStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (!stream) return '';
+  const reader = stream.getReader();
   const decoder = new TextDecoder();
   let out = '';
   try {
@@ -57,14 +56,8 @@ async function drainReader(reader: StreamReader | null): Promise<string> {
       if (value) out += decoder.decode(value, { stream: true });
     }
     out += decoder.decode();
-  } catch {
-    // Reader was cancelled (e.g. on timeout) or errored — return what we have.
   } finally {
-    try {
-      reader.releaseLock();
-    } catch {
-      // lock already released
-    }
+    reader.releaseLock();
   }
   return out;
 }
@@ -73,6 +66,9 @@ async function drainReader(reader: StreamReader | null): Promise<string> {
  * 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) {
@@ -97,15 +93,6 @@ export async function runProcess(options: RunOptions): Promise<RunResult> {
     await child.stdin.end();
   }
 
-  // Begin draining stdout/stderr immediately, holding the readers so we can
-  // cancel them on timeout. Otherwise a killed shell whose grandchild (e.g.
-  // `sh -c 'sleep 5'`) inherited the stdout pipe keeps the stream open until
-  // that orphan exits, blocking us for the child's full lifetime.
-  const stdoutReader = child.stdout ? child.stdout.getReader() : null;
-  const stderrReader = child.stderr ? child.stderr.getReader() : null;
-  const stdoutPromise = drainReader(stdoutReader);
-  const stderrPromise = drainReader(stderrReader);
-
   let timedOut = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timeoutPromise = new Promise<void>((resolve) => {
@@ -120,27 +107,16 @@ export async function runProcess(options: RunOptions): Promise<RunResult> {
     }, options.timeoutMs);
   });
 
-  // Resolve as soon as the process exits OR the timeout fires.
-  await Promise.race([child.exited, timeoutPromise]);
-  if (timer) clearTimeout(timer);
+  // 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 (timedOut) {
-    // Unblock the drains in case an orphaned grandchild still holds the pipe.
-    try {
-      await stdoutReader?.cancel();
-    } catch {
-      // already closed
-    }
-    try {
-      await stderrReader?.cancel();
-    } catch {
-      // already closed
-    }
-  }
-
-  const stdout = await stdoutPromise;
-  const stderr = await stderrPromise;
-  const exitCode = await child.exited.catch(() => -1);
+  if (timer) clearTimeout(timer);
 
   return {
     exitCode: typeof exitCode === 'number' ? exitCode : -1,

package/src/daemon/{remote → handlers/remote}/backends/ssh.ts

@@ -10,6 +10,7 @@ import {
   type DispatchPayload,
   BackendDispatchError,
   resolveTimeout,
+  buildRemoteShellCommand,
 } from './types.ts';
 import { runProcess } from './process-runner.ts';
 import { tokenizeCommand } from './local-process.ts';
@@ -80,9 +81,7 @@ export function createSshBackend(ctx: BackendContext): Backend {
       const identity = await ensureIdentity(peer, config);
       const port = config.sshPort ?? 22;
       const target = `${config.sshUser}@${config.sshHost}`;
-      const remoteCommand = payload?.args && payload.args.length > 0
-        ? `${command} ${payload.args.join(' ')}`
-        : command;
+      const remoteCommand = buildRemoteShellCommand(command, payload?.args);
 
       const args = [
         'ssh',
@@ -116,5 +115,11 @@ export function createSshBackend(ctx: BackendContext): Backend {
         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/{remote → handlers/remote}/backends/types.ts

@@ -1,5 +1,5 @@
-import type { DaemonCredentialStore } from '../../operator/index.ts';
-import type { OperatorLogger } from '../../operator/index.ts';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import type { HandlerLogger } from '../../context.ts';
 import type { PeerRecord } from '../peer-registry.ts';
 
 /**
@@ -28,7 +28,7 @@ export interface BackendDispatchResult {
 
 export interface BackendContext {
   credentials: DaemonCredentialStore;
-  logger: OperatorLogger;
+  logger: HandlerLogger;
   /** Daemon home dir — used for ephemeral key material under a 0700 subdir. */
   homeDirectory: string;
 }
@@ -48,6 +48,13 @@ export interface Backend {
     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;
@@ -69,3 +76,22 @@ export class BackendDispatchError extends Error {
     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/{remote → handlers/remote}/dispatcher.ts

@@ -1,5 +1,6 @@
-import { sha256First } from '../operator/index.ts';
-import type { OperatorLogger, DaemonCredentialStore } from '../operator/index.ts';
+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,
@@ -9,10 +10,16 @@ import {
   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 surface does not own the distributed runtime; the
-// integrator wires this hook to the existing remoteRunnerRegistry.
+// 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 {
@@ -53,7 +60,7 @@ export interface RemoteInvokeResult {
 export interface RemoteDispatcherOptions {
   registry: PeerRegistry;
   credentials: DaemonCredentialStore;
-  logger: OperatorLogger;
+  logger: HandlerLogger;
   homeDirectory: string;
   /** Optional hook for enqueuing long-running work items. */
   workEnqueuer?: RemoteWorkEnqueuer;
@@ -84,7 +91,7 @@ export class RemoteDispatcher {
   private readonly registry: PeerRegistry;
   private readonly backends: Map<PeerRecord['backendKind'], Backend>;
   private readonly workEnqueuer?: RemoteWorkEnqueuer;
-  private readonly logger: OperatorLogger;
+  private readonly logger: HandlerLogger;
 
   constructor(options: RemoteDispatcherOptions) {
     this.registry = options.registry;
@@ -157,4 +164,18 @@ export class RemoteDispatcher {
       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,119 @@
+/**
+ * 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';
+
+type DistributedRuntimeManager = operations.DistributedRuntimeManager;
+
+const DISTRIBUTED_RUNTIME_STORE = join('tui', '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 };
+}