@botcord/daemon 0.1.1

package/src/daemon-config-map.ts

@@ -0,0 +1,200 @@
+import type {
+  GatewayChannelConfig,
+  GatewayConfig,
+  GatewayRoute,
+  RouteMatch,
+  TrustLevel as GatewayTrustLevel,
+} from "./gateway/index.js";
+import type { DaemonConfig, RouteRule } from "./config.js";
+import { resolveAgentIds } from "./config.js";
+import { agentWorkspaceDir } from "./agent-workspace.js";
+import { log as daemonLog } from "./log.js";
+
+/** Options accepted by {@link toGatewayConfig}. */
+export interface ToGatewayConfigOptions {
+  /**
+   * Explicit list of agent ids to bind channels to. When provided, overrides
+   * anything derivable from the daemon config itself. P1 passes discovered
+   * credentials in via this field so `toGatewayConfig` stays pure.
+   */
+  agentIds?: string[];
+  /**
+   * Per-agent runtime/cwd cached from credentials (see
+   * `docs/agent-runtime-property-plan.md`). When present for an agent id,
+   * `toGatewayConfig` synthesizes a terminal route pinning that agent's
+   * turns to its runtime. Explicit `cfg.routes` entries still win because
+   * synthesized routes are appended after them.
+   */
+  agentRuntimes?: Record<string, { runtime?: string; cwd?: string }>;
+}
+
+/**
+ * Historical channel id used when the daemon bound a single agent. Kept as a
+ * named export for any downstream reader that still references it; no new
+ * code paths in the daemon emit this id — channels are now keyed by agentId.
+ *
+ * @deprecated Channel ids are now the agentId itself.
+ */
+export const DEFAULT_BOTCORD_CHANNEL_ID = "botcord-main";
+
+/** Channel `type` tag used by `createBotCordChannel`. */
+export const BOTCORD_CHANNEL_TYPE = "botcord";
+
+/**
+ * Map daemon's historical narrower TrustLevel ("owner" | "untrusted") onto
+ * gateway's ("owner" | "trusted" | "public"). Matches the adapter-level
+ * mapping in `adapters/runtimes.ts`: "untrusted" collapses to "public".
+ * Accepts `undefined` → `undefined` so callers can pass through.
+ */
+function mapTrustLevel(
+  level: "owner" | "untrusted" | undefined,
+): GatewayTrustLevel | undefined {
+  if (level === undefined) return undefined;
+  return level === "owner" ? "owner" : "public";
+}
+
+/**
+ * Translate a single daemon route rule into a gateway route. Gateway matches
+ * on the channel-agnostic fields; the daemon surface keeps the legacy
+ * `roomId`/`roomPrefix` aliases for backward compatibility. When both a
+ * legacy alias and its canonical field are present, the canonical field
+ * wins and a warning is logged.
+ */
+function mapRoute(r: RouteRule): GatewayRoute {
+  const match: RouteMatch = {};
+  if (r.match.channel) match.channel = r.match.channel;
+  if (r.match.accountId) match.accountId = r.match.accountId;
+
+  if (r.match.conversationId && r.match.roomId && r.match.conversationId !== r.match.roomId) {
+    daemonLog.warn("daemon.config.route.conflict", {
+      field: "conversationId",
+      roomId: r.match.roomId,
+      conversationId: r.match.conversationId,
+      resolution: "conversationId wins",
+    });
+  }
+  const conversationId = r.match.conversationId ?? r.match.roomId;
+  if (conversationId) match.conversationId = conversationId;
+
+  if (
+    r.match.conversationPrefix &&
+    r.match.roomPrefix &&
+    r.match.conversationPrefix !== r.match.roomPrefix
+  ) {
+    daemonLog.warn("daemon.config.route.conflict", {
+      field: "conversationPrefix",
+      roomPrefix: r.match.roomPrefix,
+      conversationPrefix: r.match.conversationPrefix,
+      resolution: "conversationPrefix wins",
+    });
+  }
+  const conversationPrefix = r.match.conversationPrefix ?? r.match.roomPrefix;
+  if (conversationPrefix) match.conversationPrefix = conversationPrefix;
+
+  if (r.match.conversationKind) match.conversationKind = r.match.conversationKind;
+  if (r.match.senderId) match.senderId = r.match.senderId;
+  if (typeof r.match.mentioned === "boolean") match.mentioned = r.match.mentioned;
+
+  const rawTrust = (r as { trustLevel?: "owner" | "untrusted" }).trustLevel;
+  return {
+    match,
+    runtime: r.adapter,
+    cwd: r.cwd,
+    extraArgs: r.extraArgs,
+    trustLevel: mapTrustLevel(rawTrust),
+  };
+}
+
+/**
+ * Convert the daemon's on-disk config into a gateway runtime config. Only
+ * used in-process at daemon boot; the daemon config file itself is the
+ * user-facing contract.
+ *
+ * When `opts.agentIds` is provided (discovery or explicit override), the
+ * mapper trusts that list verbatim. Otherwise it falls back to the legacy
+ * `resolveAgentIds(cfg)` path so callers that haven't been updated for P1
+ * keep working.
+ */
+export function toGatewayConfig(
+  cfg: DaemonConfig,
+  opts: ToGatewayConfigOptions = {},
+): GatewayConfig {
+  // One channel per configured agent. Channel id = agentId so session keys
+  // (`runtime:channel:accountId:kind:convId`) and activity records carry
+  // the agent identity end-to-end. Pre-multi-agent single-agent installs
+  // previously used the fixed id "botcord-main"; existing on-disk session
+  // entries keyed by that id are silently dropped on the first message
+  // after upgrade — a one-time reset, not a bug.
+  const agentIds = opts.agentIds ?? resolveAgentIds(cfg);
+  const channels: GatewayChannelConfig[] = agentIds.map((agentId) => ({
+    id: agentId,
+    type: BOTCORD_CHANNEL_TYPE,
+    accountId: agentId,
+    agentId,
+  }));
+
+  // DaemonConfig's typed surface doesn't carry `trustLevel`, but we read it
+  // defensively so future config extensions can propagate without a shape bump.
+  const rawDefaultTrust = (cfg.defaultRoute as { trustLevel?: "owner" | "untrusted" })
+    .trustLevel;
+  const defaultRoute: GatewayRoute = {
+    runtime: cfg.defaultRoute.adapter,
+    cwd: cfg.defaultRoute.cwd,
+    extraArgs: cfg.defaultRoute.extraArgs,
+    // queueMode: omitted — dispatcher's kind-based default wins
+    // (direct → cancel-previous, group → serial).
+    trustLevel: mapTrustLevel(rawDefaultTrust),
+  };
+
+  const routes: GatewayRoute[] = (cfg.routes ?? []).map(mapRoute);
+
+  // Synthesize a per-agent route for every bound agent and hand it to the
+  // gateway via the managed-routes bucket (plan §10.1). User-authored
+  // `cfg.routes[]` stay untouched so an explicit operator override still
+  // wins on conflict — the gateway matches `routes[] → managedRoutes →
+  // defaultRoute` in that order.
+  const managedMap = buildManagedRoutes(
+    agentIds,
+    opts.agentRuntimes ?? {},
+    defaultRoute,
+  );
+
+  return {
+    channels,
+    defaultRoute,
+    routes,
+    managedRoutes: Array.from(managedMap.values()),
+    streamBlocks: cfg.streamBlocks,
+  };
+}
+
+/**
+ * Build the daemon's managed per-agent routes. Emits exactly one route per
+ * `agentId`, keyed by `accountId`. `runtime` comes from the agent's cached
+ * metadata when present (credentials file), otherwise falls back to
+ * `defaultRoute.runtime`. `cwd` prefers the cached value but falls back to
+ * the agent's workspace directory (see plan §10) so every agent runs inside
+ * its own dedicated tree by default.
+ *
+ * Iteration order of `agentIds` is preserved in the resulting Map for test
+ * determinism; the gateway router does not depend on map order.
+ *
+ * Exported so `reload_config` and `provisionAgent` hot-add can share the
+ * same synthesis logic (plan §10.5).
+ */
+export function buildManagedRoutes(
+  agentIds: string[],
+  agentRuntimes: Record<string, { runtime?: string; cwd?: string }>,
+  defaultRoute: GatewayRoute,
+): Map<string, GatewayRoute> {
+  const out = new Map<string, GatewayRoute>();
+  for (const agentId of agentIds) {
+    const meta = agentRuntimes[agentId] ?? {};
+    out.set(agentId, {
+      match: { accountId: agentId },
+      runtime: meta.runtime ?? defaultRoute.runtime,
+      cwd: meta.cwd || agentWorkspaceDir(agentId),
+    });
+  }
+  return out;
+}

package/src/daemon.ts

@@ -0,0 +1,478 @@
+import { CONTROL_FRAME_TYPES } from "@botcord/protocol-core";
+import {
+  Gateway,
+  createBotCordChannel,
+  sanitizeUntrustedContent,
+  type ChannelAdapter,
+  type GatewayChannelConfig,
+  type GatewayInboundMessage,
+  type GatewayLogger,
+  type GatewayRuntimeSnapshot,
+} from "./gateway/index.js";
+import { ActivityTracker } from "./activity-tracker.js";
+import type { DaemonConfig } from "./config.js";
+import { SESSIONS_PATH, SNAPSHOT_PATH } from "./config.js";
+import { resolveBootAgents, type BootAgentsResult } from "./agent-discovery.js";
+import { ensureAgentWorkspace } from "./agent-workspace.js";
+import { ControlChannel } from "./control-channel.js";
+import { toGatewayConfig } from "./daemon-config-map.js";
+import { log as daemonLog } from "./log.js";
+import { collectRuntimeSnapshot, createProvisioner } from "./provision.js";
+import { SnapshotWriter } from "./snapshot-writer.js";
+import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { createRoomStaticContextBuilder } from "./room-context.js";
+import { createRoomContextFetcher } from "./room-context-fetcher.js";
+import { composeBotCordUserTurn } from "./turn-text.js";
+import { UserAuthManager } from "./user-auth.js";
+
+/**
+ * Matches the 10-minute turn timeout the legacy daemon dispatcher used, so
+ * long-running CLI turns behave the same way under the gateway core.
+ */
+const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * Default cadence for writing `gateway.snapshot()` to disk. Override via
+ * `BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS`.
+ */
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 5_000;
+
+function resolveSnapshotIntervalMs(): number {
+  const raw = process.env.BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS;
+  if (!raw) return DEFAULT_SNAPSHOT_INTERVAL_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SNAPSHOT_INTERVAL_MS;
+  return n;
+}
+
+// Sender classification lives in `./sender-classify.ts` so it can be shared
+// with the user-turn composer without a daemon.ts ↔ turn-text.ts cycle.
+import { classifyActivitySender } from "./sender-classify.js";
+export { classifyActivitySender };
+
+/** Minimal activity-tracker surface the inbound observer uses. */
+interface ActivityRecorderTarget {
+  record: (entry: {
+    agentId: string;
+    roomId: string;
+    roomName?: string;
+    topic: string | null;
+    lastInboundPreview: string;
+    lastSenderKind: "agent" | "human" | "owner";
+    lastSender: string;
+  }) => void;
+}
+
+/**
+ * Build the `onInbound` observer wired to the given activity tracker.
+ * Exported for tests.
+ *
+ * The recorded `agentId` is taken from the inbound message's `accountId`
+ * — so a multi-agent daemon files activity under whichever configured
+ * agent actually received the message. An optional `fallbackAgentId`
+ * covers pathological inputs where `accountId` is empty (should never
+ * happen from the gateway, but defensive).
+ */
+export function createActivityRecorder(opts: {
+  activityTracker: ActivityRecorderTarget;
+  fallbackAgentId?: string;
+}): (msg: GatewayInboundMessage) => void {
+  return (msg: GatewayInboundMessage): void => {
+    const { kind, label } = classifyActivitySender(msg);
+    const rawText = typeof msg.text === "string" ? msg.text : "";
+    // Owner text passes through verbatim; everything else gets the same
+    // sanitization the legacy dispatcher applied before recording a preview.
+    const preview = kind === "owner" ? rawText : sanitizeUntrustedContent(rawText);
+    const agentId = msg.accountId || opts.fallbackAgentId || "";
+    opts.activityTracker.record({
+      agentId,
+      roomId: msg.conversation.id,
+      roomName: msg.conversation.title,
+      topic: msg.conversation.threadId ?? null,
+      lastInboundPreview: preview,
+      lastSenderKind: kind,
+      lastSender: label,
+    });
+  };
+}
+
+/**
+ * Minimal send-capable surface used by {@link pushRuntimeSnapshot}.
+ * Exists so the helper is trivially mockable from unit tests without needing
+ * a full `ControlChannel` + user-auth harness.
+ */
+export interface RuntimeSnapshotSink {
+  send: (frame: {
+    id: string;
+    type: string;
+    params?: Record<string, unknown>;
+    ts?: number;
+  }) => boolean;
+}
+
+/**
+ * Emit one `runtime_snapshot` event frame on the control channel. Plan §8.5
+ * P0: first-connect push only — reconnect-push and diffing are P1. A send
+ * failure is non-fatal (the Hub will re-query via `list_runtimes` on demand
+ * or wait for the next daemon restart). Exported for unit tests.
+ */
+export function pushRuntimeSnapshot(sink: RuntimeSnapshotSink): boolean {
+  const snap = collectRuntimeSnapshot();
+  const ok = sink.send({
+    id: `rt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    type: CONTROL_FRAME_TYPES.RUNTIME_SNAPSHOT,
+    params: snap as unknown as Record<string, unknown>,
+    ts: Date.now(),
+  });
+  if (!ok) {
+    daemonLog.warn("runtime-snapshot: control-channel send returned false", {
+      runtimes: snap.runtimes.length,
+    });
+  }
+  return ok;
+}
+
+/** Options accepted by {@link startDaemon} — the P0.5 compatibility shim. */
+export interface DaemonRuntimeOptions {
+  config: DaemonConfig;
+  /** Informational only; surfaced in startup logs. */
+  configPath: string;
+  /** Override the JSON session store location; defaults to `~/.botcord/daemon/sessions.json`. */
+  sessionStorePath?: string;
+  /** Override the snapshot file path; defaults to `~/.botcord/daemon/snapshot.json`. */
+  snapshotPath?: string;
+  /** Override snapshot write cadence in ms; defaults to 5s or `BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS`. */
+  snapshotIntervalMs?: number;
+  log?: GatewayLogger;
+  /** Override Hub base URL; defaults to the one stored in credentials. */
+  hubBaseUrl?: string;
+  /** Override credentials JSON path; defaults to `~/.botcord/credentials/<agentId>.json`. */
+  credentialsPath?: string;
+  /**
+   * Inject a pre-resolved boot-agent list (e.g. from tests). When omitted,
+   * `startDaemon` resolves boot agents from `config.agents`/`config.agentId`
+   * or falls back to credential discovery.
+   */
+  bootAgents?: BootAgentsResult;
+  /**
+   * Inject a pre-built user-auth manager. Typically only set by tests; in
+   * production the daemon calls `UserAuthManager.load()` internally, and
+   * only starts the control channel when a user-auth record exists.
+   */
+  userAuth?: UserAuthManager | null;
+  /** Skip the control channel even when user-auth is available. Test hook. */
+  disableControlChannel?: boolean;
+}
+
+/** Handle returned by {@link startDaemon}. */
+export interface DaemonHandle {
+  /** Graceful shutdown — idempotent. */
+  stop: (reason?: string) => Promise<void>;
+  /** Channel + turn status snapshot, straight from `Gateway.snapshot()`. */
+  snapshot: () => GatewayRuntimeSnapshot;
+}
+
+/**
+ * Adapt daemon's file-based `log` module into the gateway logger contract.
+ * Writes go to `~/.botcord/logs/daemon.log` + stderr, preserving the format
+ * existing `logs -f` watchers rely on. Debug lines stay gated by
+ * `BOTCORD_DAEMON_DEBUG`, mirroring pre-migration behavior.
+ */
+function buildDaemonLogger(): GatewayLogger {
+  return {
+    info: (msg, meta) => daemonLog.info(msg, meta),
+    warn: (msg, meta) => daemonLog.warn(msg, meta),
+    error: (msg, meta) => daemonLog.error(msg, meta),
+    debug: (msg, meta) => daemonLog.debug(msg, meta),
+  };
+}
+
+/**
+ * Boot the gateway using a daemon-shaped config. This is the P0.5 compat
+ * entry point: the on-disk config at `~/.botcord/daemon/config.json` keeps
+ * its existing shape, and `Gateway` handles channels/dispatch/sessions
+ * under the hood.
+ *
+ * Only the BotCord channel is supported today; `channels[]` in the
+ * translated gateway config has exactly one entry (`botcord-main`).
+ */
+export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHandle> {
+  const logger = opts.log ?? buildDaemonLogger();
+
+  // Resolve boot agents: explicit `agents` config wins; otherwise scan the
+  // credentials directory. A zero-agent result is valid in P1 — the daemon
+  // still starts with zero channels so operators can drop credentials in
+  // and restart without re-running `init`.
+  const boot = opts.bootAgents ?? resolveBootAgents(opts.config);
+  for (const w of boot.warnings) {
+    logger.warn("daemon.discovery.warning", { message: w });
+  }
+  const agentIds = boot.agents.map((a) => a.agentId);
+  const { credentialPathByAgentId, agentRuntimes } = backfillBootAgents(
+    boot.agents,
+    { logger },
+  );
+
+  const gwConfig = toGatewayConfig(opts.config, { agentIds, agentRuntimes });
+
+  // ActivityTracker lives at the daemon layer (not the gateway core). We
+  // expose it to the gateway via (a) the `buildSystemContext` hook so the
+  // cross-room digest reflects current activity, and (b) the `onInbound`
+  // observer so incoming messages get recorded before the turn runs —
+  // mirroring the pre-P0.5 dispatcher's "record-before-adapter-run" ordering.
+  const activityTracker = new ActivityTracker();
+
+  // Shared room-context fetcher — one BotCordClient per accountId, created
+  // lazily and reused across turns so JWT refreshes amortize. The builder
+  // wrapping it adds a TTL cache on top so group rooms don't hit Hub every
+  // turn.
+  const roomContextFetcher = createRoomContextFetcher({
+    credentialPathByAgentId,
+    ...(opts.credentialsPath ? { defaultCredentialsPath: opts.credentialsPath } : {}),
+    ...(opts.hubBaseUrl ? { hubBaseUrl: opts.hubBaseUrl } : {}),
+    log: logger,
+  });
+  const roomContextBuilder = createRoomStaticContextBuilder({
+    fetchRoomInfo: roomContextFetcher,
+    log: logger,
+  });
+
+  // Cache one system-context builder per configured agentId. The gateway
+  // calls this with each inbound message and we pick the right builder by
+  // `message.accountId` — so per-agent working memory + activity digests
+  // stay scoped when a single daemon hosts multiple agents.
+  type PerAgentBuilder = (
+    msg: GatewayInboundMessage,
+  ) => Promise<string | undefined> | string | undefined;
+  const scBuilders = new Map<string, PerAgentBuilder>();
+  for (const aid of agentIds) {
+    scBuilders.set(
+      aid,
+      createDaemonSystemContextBuilder({
+        agentId: aid,
+        activityTracker,
+        roomContextBuilder,
+      }),
+    );
+  }
+  const buildSystemContext = (
+    message: GatewayInboundMessage,
+  ): Promise<string | undefined> | string | undefined => {
+    const b = scBuilders.get(message.accountId);
+    if (b) return b(message);
+    // Unknown accountId (shouldn't happen in practice): fall back to the
+    // first configured agent so we still emit *something* rather than
+    // silently dropping the context block. When no agents are bound the
+    // daemon has no context to surface — return undefined.
+    const first = agentIds[0];
+    if (!first) return undefined;
+    const fallback = scBuilders.get(first);
+    return fallback ? fallback(message) : undefined;
+  };
+
+  // Observer runs after ack + before runtime.run. Keeping the side effect
+  // outside the system-context builder (option A) means the builder stays
+  // pure — a cleaner contract the gateway can also expose to non-daemon
+  // callers in the future.
+  const onInbound = createActivityRecorder({
+    activityTracker,
+    ...(agentIds[0] ? { fallbackAgentId: agentIds[0] } : {}),
+  });
+
+  const gateway = new Gateway({
+    config: gwConfig,
+    sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
+    createChannel: (chCfg: GatewayChannelConfig): ChannelAdapter => {
+      const agentId =
+        typeof chCfg.agentId === "string" ? chCfg.agentId : chCfg.accountId;
+      return createBotCordChannel({
+        id: chCfg.id,
+        accountId: chCfg.accountId,
+        agentId,
+        credentialsPath:
+          credentialPathByAgentId.get(agentId) ?? opts.credentialsPath,
+        hubBaseUrl: opts.hubBaseUrl,
+      });
+    },
+    log: logger,
+    turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
+    buildSystemContext,
+    onInbound,
+    composeUserTurn: composeBotCordUserTurn,
+  });
+
+  logger.info("daemon starting", {
+    agents: agentIds,
+    source: boot.source,
+    credentialsDir: boot.credentialsDir,
+    configPath: opts.configPath,
+    sessionsPath: opts.sessionStorePath ?? SESSIONS_PATH,
+    channels: gwConfig.channels.map((c) => c.id),
+    routeCount: gwConfig.routes?.length ?? 0,
+  });
+
+  if (agentIds.length === 0) {
+    logger.warn("daemon starting with no channels", {
+      source: boot.source,
+      credentialsDir: boot.credentialsDir,
+      hint: "drop a credentials JSON in the discovery dir and restart, or run `botcord-daemon init --agent <ag_xxx>`",
+    });
+  }
+
+  await gateway.start();
+  logger.info("daemon started", { agents: agentIds });
+
+  // Control channel is optional — daemon still runs (data-plane only)
+  // when user-auth hasn't been set up yet. Operators can `login` later
+  // without restarting, but for P0 we require a restart to pick it up.
+  let controlChannel: ControlChannel | null = null;
+  const userAuth =
+    opts.userAuth === undefined
+      ? tryLoadUserAuth(logger)
+      : opts.userAuth;
+  if (userAuth?.current && !opts.disableControlChannel) {
+    logger.info("control-channel: enabling", {
+      userId: userAuth.current.userId,
+      hubUrl: userAuth.current.hubUrl,
+    });
+    const provisioner = createProvisioner({ gateway });
+    controlChannel = new ControlChannel({
+      auth: userAuth,
+      handle: provisioner,
+    });
+    try {
+      await controlChannel.start();
+      // Plan §8.5 P0 — push one runtime snapshot immediately after connect
+      // so Hub's `daemon_instances.runtimes_json` is populated for the
+      // dashboard even before any user action. No periodic refresh in P0.
+      const pushed = pushRuntimeSnapshot(controlChannel);
+      logger.info("control-channel: initial runtime_snapshot push", {
+        ok: pushed,
+      });
+    } catch (err) {
+      logger.warn("control-channel failed to start; continuing without it", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      // start() schedules its own reconnect; we swallow the initial
+      // failure so the daemon boots either way.
+    }
+  } else if (!userAuth?.current) {
+    logger.info("control-channel skipped: no user-auth record", {
+      hint: "run `botcord-daemon start` to enable Hub control plane (device-code login)",
+    });
+  }
+
+  const snapshotWriter = new SnapshotWriter({
+    path: opts.snapshotPath ?? SNAPSHOT_PATH,
+    intervalMs: opts.snapshotIntervalMs ?? resolveSnapshotIntervalMs(),
+    snapshot: () => gateway.snapshot(),
+    log: logger,
+  });
+  snapshotWriter.start();
+
+  let stopping: Promise<void> | null = null;
+  const stop = (reason?: string): Promise<void> => {
+    if (stopping) return stopping;
+    logger.info("daemon stopping", { reason: reason ?? null });
+    snapshotWriter.stop();
+    // Write one final snapshot so `status` doesn't briefly see stale data,
+    // then delete the file on the way out.
+    snapshotWriter.writeFinal();
+    const controlStopP = controlChannel
+      ? controlChannel.stop().catch(() => undefined)
+      : Promise.resolve();
+    stopping = Promise.all([controlStopP, gateway.stop(reason)]).then(
+      () => undefined,
+    ).finally(() => {
+      snapshotWriter.remove();
+      logger.info("daemon stopped", { reason: reason ?? null });
+    });
+    return stopping;
+  };
+
+  return {
+    stop,
+    snapshot: () => gateway.snapshot(),
+  };
+}
+
+/**
+ * Result of {@link backfillBootAgents}: the maps the boot flow needs to
+ * plumb into `toGatewayConfig` + the channel factory.
+ */
+export interface BootBackfillResult {
+  credentialPathByAgentId: Map<string, string>;
+  agentRuntimes: Record<string, { runtime?: string; cwd?: string }>;
+}
+
+/**
+ * Walk the boot-agent list and (a) populate the credential-path + runtime
+ * caches used downstream, and (b) idempotently create each agent's on-disk
+ * workspace tree (plan §9). One agent's failing workspace must not block
+ * the others — errors are warned and swallowed per agent. Exported for
+ * unit tests; `startDaemon` calls this inline.
+ */
+export function backfillBootAgents(
+  agents: BootAgentsResult["agents"],
+  opts: {
+    logger: GatewayLogger;
+    ensure?: typeof ensureAgentWorkspace;
+  },
+): BootBackfillResult {
+  const ensure = opts.ensure ?? ensureAgentWorkspace;
+  const credentialPathByAgentId = new Map<string, string>();
+  const agentRuntimes: Record<string, { runtime?: string; cwd?: string }> = {};
+  const failed: string[] = [];
+  for (const a of agents) {
+    if (a.credentialsFile) credentialPathByAgentId.set(a.agentId, a.credentialsFile);
+    if (a.runtime || a.cwd) {
+      agentRuntimes[a.agentId] = {
+        ...(a.runtime ? { runtime: a.runtime } : {}),
+        ...(a.cwd ? { cwd: a.cwd } : {}),
+      };
+    }
+    // Seed files are written only when missing (see `ensureAgentWorkspace`),
+    // so a legacy agent whose workspace dir doesn't exist yet gets one on
+    // the next boot — with zero risk of overwriting the user's edits.
+    try {
+      ensure(a.agentId, {
+        ...(a.displayName ? { displayName: a.displayName } : {}),
+        ...(a.runtime ? { runtime: a.runtime } : {}),
+        ...(a.keyId ? { keyId: a.keyId } : {}),
+        ...(a.savedAt ? { savedAt: a.savedAt } : {}),
+        // `bio` is not surfaced on BootAgent — identity.md renders a
+        // placeholder the user can fill in.
+      });
+    } catch (err) {
+      failed.push(a.agentId);
+      opts.logger.warn("ensureAgentWorkspace failed at boot; continuing", {
+        agentId: a.agentId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  if (failed.length > 0) {
+    opts.logger.warn("ensureAgentWorkspace: boot backfill incomplete", {
+      count: failed.length,
+      agentIds: failed,
+    });
+  }
+  return { credentialPathByAgentId, agentRuntimes };
+}
+
+/**
+ * Load the user-auth record if present, swallowing "file missing" as the
+ * expected not-logged-in state. A parse / permission error is logged and
+ * treated as "no record" so a broken user-auth.json can't block the
+ * data-plane from coming up.
+ */
+function tryLoadUserAuth(logger: GatewayLogger): UserAuthManager | null {
+  try {
+    return UserAuthManager.load();
+  } catch (err) {
+    logger.warn("failed to load user-auth", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}