@pellux/goodvibes-daemon 1.28.0

package/src/daemon/handlers/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Composition root for the daemon handler layer — the only module that
+ * `src/runtime/services.ts` imports. It assembles every surface (routing,
+ * inbox+triage, drafts, calendar, email, remote) onto the SDK gateway catalog
+ * and returns a single teardown plus the cross-surface handles the runtime
+ * needs (routing resolver, the remote `DistributedRuntimeRouteService` the SDK
+ * facade injects, and the `remote.peers.invoke` dispatch adapter).
+ *
+ * Surfaces are provided by the caller as `SurfaceRegister` functions so this
+ * foundation module stays free of import cycles and does not author any SDK
+ * descriptor or schema. Registration order is fixed; teardown runs in reverse.
+ */
+import type { DistributedRuntimeRouteService } from './contracts.ts';
+import type { HandlerContext, SurfaceRegister } from './context.ts';
+import type { Unregister } from './register.ts';
+
+/** Routing surface handle: teardown plus the resolver other surfaces consume. */
+export interface RoutingRegistration {
+  readonly unregister: Unregister;
+  /** Resolve an inbound channel target to a profile id (exact → wildcard → null). */
+  readonly resolveProfileId: (surfaceKind: string, routeId?: string) => string | null;
+}
+
+/** Adapter the runtime wires into the published `remote.peers.invoke` route. */
+export interface RemoteInvokeAdapter {
+  invoke(input: Record<string, unknown>): Promise<unknown>;
+}
+
+/** Remote surface handle: the host service the SDK facade injects + its teardown. */
+export interface RemoteSurfaceRegistration {
+  readonly unregister: Unregister;
+  readonly service: DistributedRuntimeRouteService;
+  readonly dispatch: RemoteInvokeAdapter;
+}
+
+/** Aggregate result returned to the runtime for teardown and cross-surface wiring. */
+export interface DaemonHandlerSurfaces {
+  readonly unregister: Unregister;
+  readonly routing: RoutingRegistration;
+  readonly remoteSurface: { readonly service: DistributedRuntimeRouteService };
+  readonly remoteDispatch: RemoteInvokeAdapter;
+}
+
+/**
+ * The surface implementations the runtime supplies. Each builds its stores and
+ * attaches handlers to the SDK catalog via `registerCatalogHandler(s)`.
+ *
+ * Order of composition (and reverse teardown) is enforced by
+ * `registerDaemonHandlers`: routing → inbox(+triage) → drafts → calendar →
+ * email → remote.
+ */
+export interface DaemonHandlerSurfaceProviders {
+  /** channels.routing.* — returns the resolver consumed by the inbox surface. */
+  readonly registerRouting: (ctx: HandlerContext) => RoutingRegistration;
+  /** channels.inbox.list (triage-decorated) + inbox.triage.* (daemon-internal). */
+  readonly registerInbox: (ctx: HandlerContext, routing: RoutingRegistration) => Unregister;
+  /** channels.drafts.* */
+  readonly registerDrafts: SurfaceRegister;
+  /** remote.peers.* — supplies the host DistributedRuntimeRouteService + dispatch adapter. */
+  readonly registerRemote: (ctx: HandlerContext) => RemoteSurfaceRegistration;
+}
+
+/**
+ * Compose all daemon handler surfaces onto the gateway catalog held by `ctx`.
+ * Returns a single teardown (reverse order, best-effort) and the handles the
+ * runtime must expose: the routing registration, the remote service the SDK
+ * facade injects into `DaemonRemoteRouteContext.distributedRuntime`, and the
+ * remote invoke dispatch adapter.
+ */
+export function registerDaemonHandlers(
+  ctx: HandlerContext,
+  providers: DaemonHandlerSurfaceProviders,
+): DaemonHandlerSurfaces {
+  const teardowns: Unregister[] = [];
+
+  const routing = providers.registerRouting(ctx);
+  teardowns.push(routing.unregister);
+
+  teardowns.push(providers.registerInbox(ctx, routing));
+  teardowns.push(providers.registerDrafts(ctx));
+  // calendar.* and email.* are NOT registered here any more. Both are served
+  // by the SDK (control-plane/routes/{calendar,email}.ts over the platform
+  // CalDAV/Google and IMAP/SMTP implementations), registered through
+  // registerGatewayVerbGroups in runtime/services.ts. This product used to
+  // carry its own handlers for the same descriptor ids and, registering later,
+  // won — two implementations behind one path, which is the drift the hoist
+  // exists to end.
+
+  const remote = providers.registerRemote(ctx);
+  teardowns.push(remote.unregister);
+
+  // Idempotent: teardown is reachable from more than one shutdown path now that
+  // the runtime disposal scope owns it, and the surfaces underneath are not all
+  // safe to unwind twice — the inbox surface closes a SQLite handle, which a
+  // second pass would close again inside a floating promise (an unhandled
+  // rejection, not a caught one). Running once is also simply the honest
+  // meaning of "release these surfaces".
+  let torn = false;
+  const unregister: Unregister = () => {
+    if (torn) return;
+    torn = true;
+    for (let i = teardowns.length - 1; i >= 0; i -= 1) {
+      try {
+        teardowns[i]!();
+      } catch (error) {
+        ctx.logger.warn('daemon handler surface teardown failed', { error });
+      }
+    }
+  };
+
+  return {
+    unregister,
+    routing,
+    remoteSurface: { service: remote.service },
+    remoteDispatch: remote.dispatch,
+  };
+}

package/src/daemon/handlers/register.ts

@@ -0,0 +1,180 @@
+/**
+ * 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`.
+ *
+ * An ABSENT context is accepted and read as the empty one: no principal, no
+ * scopes, not admin, nobody claiming a person asked. The type says a context is
+ * always there and at runtime it is not always — an in-process invoke that
+ * builds the invocation by hand can omit it — and reading `.metadata` off
+ * `undefined` turned that into a TypeError thrown out of the handler wrapper
+ * instead of the refusal every caller can act on. Defaulting to the least
+ * privilege is the only safe reading: it can cost a caller an authorization it
+ * never proved, never grant one.
+ */
+export function normalizeContext(
+  c: GatewayMethodInvocationContext | undefined,
+): HandlerContextEnvelope {
+  const context = c ?? ({} as GatewayMethodInvocationContext);
+  const metadata = context.metadata ?? {};
+  return {
+    principalId: context.principalId ?? '',
+    admin: context.admin === true,
+    scopes: context.scopes ? [...context.scopes] : [],
+    explicitUserRequest: metadata.explicitUserRequest === true,
+    authToken: context.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) {
+    // 'METHOD_NOT_FOUND' (not the old locally-coined 'UNKNOWN_METHOD') so this lines
+    // up byte-for-byte with SDKErrorCodes.METHOD_NOT_FOUND — the code the SDK's own
+    // uncataloged-method 404 now carries (method-catalog.ts's GatewayMethodCatalog
+    // .invoke(), daemon/control-plane.ts's invokeGatewayMethodCall, and daemon-sdk's
+    // control-routes.ts getGatewayMethod/invokeGatewayMethod). A literal string, not
+    // an import of SDKErrorCodes: the pinned SDK (0.38.0) predates that constant, and
+    // matching the value this way needs no SDK version bump to stay aligned.
+    throw new HandlerError(`Unknown gateway method: ${methodId}`, 'METHOD_NOT_FOUND', 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/handlers/remote/backends/cloud-terminal.ts

@@ -0,0 +1,143 @@
+import { mkdir, writeFile, chmod, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import type { PeerRecord } from '../peer-registry.ts';
+import type { CloudTerminalBackendConfig } 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';
+
+/**
+ * Cloud-terminal backend: executes a command in a managed cloud shell / VM via
+ * the provider CLI (gcloud / aws / az). The provider credential is resolved from
+ * the daemon credential store and supplied to the CLI via a 0600 credentials
+ * file or a provider-specific env var — never as an argv token, never logged.
+ */
+export function createCloudTerminalBackend(ctx: BackendContext): Backend {
+  const credDir = join(ctx.homeDirectory, '.goodvibes', GOODVIBES_DAEMON_SURFACE_ROOT, 'operator', 'cloud-creds');
+
+  async function writeCredentialFile(peerId: string, value: string): Promise<string> {
+    await mkdir(credDir, { recursive: true });
+    await chmod(credDir, 0o700).catch(() => {});
+    const suffix = randomBytes(4).toString('hex');
+    const path = join(credDir, `${peerId}.${suffix}.cred`);
+    await writeFile(path, value, { mode: 0o600 });
+    await chmod(path, 0o600).catch(() => {});
+    return path;
+  }
+
+  function buildArgs(
+    config: CloudTerminalBackendConfig,
+    remoteCommand: string,
+  ): { args: string[]; credEnvKey?: string } {
+    switch (config.provider) {
+      case 'gcp': {
+        // gcloud compute ssh runs `command` on the target Cloud Shell / instance.
+        const args = ['gcloud', 'compute', 'ssh'];
+        if (config.projectId) args.push('--project', config.projectId);
+        if (config.location) args.push('--zone', config.location);
+        args.push(config.instance ?? 'cloudshell', '--command', remoteCommand);
+        return { args, credEnvKey: 'CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE' };
+      }
+      case 'aws': {
+        // aws ssm send-command style: run shell command on a managed instance.
+        const args = ['aws', 'ssm', 'start-session'];
+        if (config.location) args.push('--region', config.location);
+        if (config.instance) args.push('--target', config.instance);
+        args.push(
+          '--document-name', 'AWS-StartInteractiveCommand',
+          '--parameters', `command=${remoteCommand}`,
+        );
+        return { args, credEnvKey: 'AWS_SHARED_CREDENTIALS_FILE' };
+      }
+      case 'azure': {
+        // az vm run-command invoke executes a script on the target VM.
+        const args = ['az', 'vm', 'run-command', 'invoke'];
+        if (config.projectId) args.push('--resource-group', config.projectId);
+        if (config.instance) args.push('--name', config.instance);
+        args.push(
+          '--command-id', 'RunShellScript',
+          '--scripts', remoteCommand,
+        );
+        return { args, credEnvKey: 'AZURE_AUTH_LOCATION' };
+      }
+      default:
+        throw new BackendDispatchError(
+          `Unsupported cloud provider: ${String(config.provider)}`,
+          'REMOTE_BACKEND_UNSUPPORTED_PROVIDER',
+        );
+    }
+  }
+
+  return {
+    kind: 'cloud-terminal',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'cloud-terminal') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a cloud-terminal peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'cloud-terminal' } & CloudTerminalBackendConfig;
+      if (tokenizeCommand(command).length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+      const credential = await ctx.credentials.resolveRef(config.credentialRef);
+      if (!credential || credential.length === 0) {
+        throw new BackendDispatchError(
+          `Could not resolve cloud credential for peer '${peer.peerId}'.`,
+          'REMOTE_BACKEND_CREDENTIAL_MISSING',
+        );
+      }
+      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 ?? {}) };
+      if (credEnvKey) env[credEnvKey] = credPath;
+
+      ctx.logger.info('remote cloud-terminal dispatch', {
+        peerId: peer.peerId,
+        provider: config.provider,
+      });
+      try {
+        const result = await runProcess({
+          args,
+          timeoutMs: resolveTimeout(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] cloud command timed out`
+            : result.stderr,
+        };
+      } finally {
+        // The plaintext provider credential file is single-use: remove it as
+        // soon as the CLI has run (or failed) so credentials never accumulate
+        // on disk under cloud-creds/.
+        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/handlers/remote/backends/docker.ts

@@ -0,0 +1,79 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import type { DockerBackendConfig } 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';
+
+/**
+ * Docker backend: runs `docker exec {containerName} {command}` against the local
+ * Docker socket (or a configured DOCKER_HOST). The command is executed inside
+ * the target container via `sh -c` so shell semantics survive the hop, while the
+ * docker argv itself is fully tokenized (no shell on the daemon side).
+ */
+export function createDockerBackend(ctx: BackendContext): Backend {
+  return {
+    kind: 'docker',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'docker') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a docker peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'docker' } & DockerBackendConfig;
+      if (tokenizeCommand(command).length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+
+      // Resolve DOCKER_HOST. When it is a secret reference, pull the real value
+      // from the credential store and pass it via env (never argv).
+      const env: Record<string, string> = { ...(payload?.env ?? {}) };
+      if (config.dockerHost) {
+        const resolved = config.dockerHost.startsWith('goodvibes://')
+          ? await ctx.credentials.resolveRef(config.dockerHost)
+          : config.dockerHost;
+        if (!resolved) {
+          throw new BackendDispatchError(
+            `Could not resolve dockerHost for peer '${peer.peerId}'.`,
+            'REMOTE_BACKEND_CREDENTIAL_MISSING',
+          );
+        }
+        env.DOCKER_HOST = resolved;
+      }
+
+      const innerCommand = buildRemoteShellCommand(command, payload?.args);
+
+      const args = ['docker', 'exec'];
+      if (payload?.stdin !== undefined) args.push('-i');
+      args.push(config.containerName, 'sh', '-c', innerCommand);
+
+      ctx.logger.info('remote docker dispatch', {
+        peerId: peer.peerId,
+        container: config.containerName,
+      });
+      const result = await runProcess({
+        args,
+        timeoutMs: resolveTimeout(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] docker exec timed out` : result.stderr,
+      };
+    },
+  };
+}

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/handlers/remote/backends/local-process.ts

@@ -0,0 +1,113 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import type { LocalProcessBackendConfig } from '../peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type BackendDispatchResult,
+  type DispatchPayload,
+  BackendDispatchError,
+  resolveTimeout,
+} from './types.ts';
+import { runProcess } from './process-runner.ts';
+
+/** Split a command string into argv, honoring single/double quotes. */
+export function tokenizeCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  let started = false;
+  for (const ch of command) {
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      started = true;
+      continue;
+    }
+    if (ch === '\\' && quote !== "'") {
+      escaped = true;
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      continue;
+    }
+    if (ch === ' ' || ch === '\t' || ch === '\n') {
+      if (started) {
+        tokens.push(current);
+        current = '';
+        started = false;
+      }
+      continue;
+    }
+    current += ch;
+    started = true;
+  }
+  if (started) tokens.push(current);
+  if (quote) {
+    throw new BackendDispatchError('Unterminated quote in command string.', 'REMOTE_BACKEND_BAD_COMMAND');
+  }
+  return tokens;
+}
+
+/**
+ * Local-process backend: spawns the command directly on the daemon host. This is
+ * the lowest-friction backend, used for self-hosted peers. An optional
+ * allowlist on backendConfig restricts which executables may run.
+ */
+export function createLocalProcessBackend(ctx: BackendContext): Backend {
+  return {
+    kind: 'local-process',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'local-process') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a local-process peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'local-process' } & LocalProcessBackendConfig;
+      const tokens = tokenizeCommand(command);
+      if (tokens.length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+      const executable = tokens[0]!;
+      if (config.allowedCommands && config.allowedCommands.length > 0) {
+        if (!config.allowedCommands.includes(executable)) {
+          throw new BackendDispatchError(
+            `Command '${executable}' is not in the peer allowlist.`,
+            'REMOTE_BACKEND_COMMAND_DENIED',
+          );
+        }
+      }
+      const args = [...tokens, ...(payload?.args ?? [])];
+      const cwd = payload?.cwd ?? config.cwd;
+      ctx.logger.info('remote local-process dispatch', { peerId: peer.peerId, executable });
+      const result = await runProcess({
+        args,
+        timeoutMs: resolveTimeout(payload),
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(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] command timed out` : result.stderr,
+      };
+    },
+  };
+}