@pellux/goodvibes-daemon 1.28.0

package/src/daemon/cli.ts

@@ -0,0 +1,878 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  ConfigManager,
+  daemonConfigPathForHome,
+  describeDerivedBindMismatch,
+  readControlPlaneBinding,
+  resolveDaemonEnabled,
+} from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../config/surface.ts';
+import { formatProviderModel, getModelIdFromProviderModel, getProviderIdFromModel } from '@pellux/goodvibes-sdk/platform/providers';
+import { resolveGoodVibesHomeOwnership } from '@pellux/goodvibes-sdk/platform/config';
+import { RuntimeEventBus, GlobalNetworkTransportInstaller, configureRuntimeEventBusDefaults, runtimeEventBusOptionsFrom } from '@/runtime/index.ts';
+import { createHostedSessionOptions } from '@/runtime/hosted-session-composition.ts';
+import { bindFeatureSettingsBridge, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
+import { createRuntimeStore } from '@pellux/goodvibes-sdk/platform/runtime/store';
+import { createRuntimeServices } from '../runtime/services.ts';
+import { startDeviceHousekeeping } from '../runtime/device-posture-composition.ts';
+import { runDaemonBootTasks } from '../runtime/boot-tasks.ts';
+import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
+import { createHostPowerSeam } from '@pellux/goodvibes-sdk/platform/power';
+import { configureActivityLogger, flushActivityLogSync, logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { reportFatalBootFailure, writeExitingStdoutLine, writeFatalLine } from '@pellux/goodvibes-sdk/platform/daemon';
+import {
+  availablePairingOffers,
+  ensurePublicBaseUrl,
+  getOrCreateCompanionToken,
+  pruneStaleOperatorTokens,
+} from '@pellux/goodvibes-sdk/platform/pairing';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+import {
+  scan,
+  loadPersistedProviders,
+  persistProviders,
+} from '@pellux/goodvibes-sdk/platform/discovery';
+import { createSafeHostServeFactory } from '@pellux/goodvibes-sdk/platform/daemon';
+import { runProvisionWakeModelCommand } from './provision-wake-model.ts';
+import { runWebuiCommand } from './webui-command.ts';
+import { runSendCommand } from './send/command.ts';
+import { createSendStack } from './send/composition.ts';
+import { readAllStdin } from './send/stdin.ts';
+import { isDaemonServiceSubcommand, resolveInstalledDaemonBinary, runDaemonServiceCli } from './service-commands.ts';
+import { resolveConfiguredServiceName } from '../runtime/legacy-daemon-migration.ts';
+import { runDaemonConfigMigration } from '../config/run-daemon-config-migration.ts';
+import { reconcileRedundantLegacyUnit } from '../runtime/legacy-daemon-reconcile.ts';
+import { resolveRuntimeEndpointBinding, runClusterCommand } from '@pellux/goodvibes-terminal-shell';
+import { resolveDaemonUpdateArtifact } from './lifecycle.ts';
+import { VERSION } from '../version.ts';
+
+import {
+  parseDaemonCli,
+  isRawInterceptCommand,
+  renderGoodVibesDaemonHelp,
+  renderDaemonCommandHelp,
+  renderGoodVibesVersion,
+  renderDaemonStartupBanner,
+  runCompletionCommand,
+} from '../cli/index.ts';
+import {
+  applyRuntimeConfigOverrides,
+  applyRuntimeConfigValue,
+  applyRuntimeEndpointFlagOverrides,
+  applyRuntimeFeatureFlagOverrides,
+} from '@pellux/goodvibes-terminal-shell';
+import { runConfigCommand } from './config-command.ts';
+import { runPairCommand } from './pair-command.ts';
+import { runSessionsCommand } from './sessions-command.ts';
+import { runStatusCommand, runUpdateCommand, type DaemonCommandResult } from './status-command.ts';
+import { renderPairingBanner } from '../core/pairing-banner.ts';
+import { readOperatorTokenFile } from '@pellux/goodvibes-sdk/platform/workspace';
+type DaemonCliOwnership = {
+  readonly workingDirectory: string;
+  /** The GoodVibes tree root — settings, workspace, and discovery all hang off this. */
+  readonly homeDirectory: string;
+  /** The daemon's OWN identity home (auth users, operator tokens, daemon settings). */
+  readonly daemonHomeDirectory: string;
+  /** True when GOODVIBES_HOME or GOODVIBES_DAEMON_HOME named an override — see goodvibes-home.ts. */
+  readonly isOverridden: boolean;
+};
+
+// CLI flag parsing delegated to shared module — see src/cli-flags.ts
+
+type DaemonCliTokens = {
+  readonly daemonToken: string | undefined;
+  readonly httpToken: string | undefined;
+};
+
+/**
+ * Two different directories that used to be one.
+ *
+ * `GOODVIBES_DAEMON_HOME` names the DAEMON's home — the identity directory
+ * holding auth-users.json, operator-tokens.json, and daemon-settings.json. That
+ * is what the name says and what the SDK's `resolveDaemonHomeDir()` has always
+ * meant by it. This function used to read it as the GoodVibes tree ROOT, so
+ * setting it relocated settings, workspace, and every discovery root as well —
+ * far more than the daemon's own state.
+ *
+ * `GOODVIBES_HOME` is the variable for relocating the tree root. It is what a
+ * test harness or a service unit should set when it wants an isolated tree; the
+ * daemon home then falls under it unless separately overridden.
+ */
+function resolveDaemonCliOwnership(): DaemonCliOwnership {
+  // Both roots come from the SDK's platform/config goodvibes-home, which the CLIENT entry
+  // point also uses. They were resolved independently, and the client's copy
+  // simply did not read GOODVIBES_HOME — so a redirected client wrote into the
+  // real tree while the daemon honoured the redirect.
+  const { homeDirectory, daemonHomeDirectory, isOverridden } = resolveGoodVibesHomeOwnership();
+  return {
+    workingDirectory: process.env['GOODVIBES_WORKING_DIR'] ?? process.cwd(),
+    homeDirectory,
+    daemonHomeDirectory,
+    isOverridden,
+  };
+}
+
+function readDaemonCliTokens(env: NodeJS.ProcessEnv): DaemonCliTokens {
+  const daemonToken = env.GOODVIBES_DAEMON_TOKEN;
+  return {
+    daemonToken,
+    httpToken: env.GOODVIBES_HTTP_TOKEN ?? daemonToken,
+  };
+}
+
+async function main(): Promise<void> {
+  // `cluster …` is intercepted before the daemon's own flag parser runs, and
+  // before any runtime is composed.
+  //
+  // Before the parser, because the subcommand has its own flag vocabulary
+  // (--group, --key, --host, --port, --token) that the daemon parser would
+  // reject as unknown. Before the runtime, because this command talks to a
+  // daemon that is ALREADY RUNNING — composing a second runtime here would
+  // build a competing set of state on a machine that already has one.
+  //
+  // See the terminal shell's cluster-remote-daemon-target for the
+  // --host/--port/--token convention that
+  // every later remote-capable subcommand should follow.
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === 'cluster') {
+    const ownership = resolveDaemonCliOwnership();
+    const clusterConfig = new ConfigManager({
+      workingDir: ownership.workingDirectory,
+      homeDir: ownership.homeDirectory,
+      surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT,
+      // Named explicitly rather than left to ConfigManager's own
+      // `<homeDir>/.goodvibes/daemon/settings.json` derivation, so the daemon
+      // tier this reads/writes agrees with `ownership.daemonHomeDirectory`
+      // even when `GOODVIBES_DAEMON_HOME` moved it away from the plain home.
+      daemonTierPath: daemonConfigPathForHome(ownership.daemonHomeDirectory),
+    });
+    const result = await runClusterCommand({
+      argv: rawArgs.slice(1),
+      configManager: clusterConfig,
+      daemonHomeDir: ownership.daemonHomeDirectory,
+    });
+    // Every write below is immediately followed by process.exit, so all of them
+    // go to the descriptor synchronously rather than through a stream that can
+    // still be in flight when the process stops existing — see
+    // fatal-boot-report.ts. (The OSC 52 clipboard sequence is unterminated
+    // either way; the line terminator this adds after it is inert.)
+    if (result.rawOutput) writeExitingStdoutLine(`\u001b${result.rawOutput}`);
+    for (const line of result.lines) {
+      if (result.exitCode === 0) writeExitingStdoutLine(line);
+      else writeFatalLine(line);
+    }
+    process.exit(result.exitCode);
+  }
+
+  // `send …` is intercepted here for both of the reasons `cluster` is, plus one
+  // of its own.
+  //
+  // Before the parser, because the message is arbitrary operator text: a
+  // message beginning with a dash, or one carrying `--port` inside it, must
+  // reach the channel rather than be eaten as a daemon flag.
+  //
+  // Before the runtime, because this composes only the services a delivery
+  // needs (see send/composition.ts) and must not start a second copy of the
+  // pollers, cluster election and LAN scan a running daemon already owns.
+  //
+  // And it must work when NO daemon is running, which is much of the point: the
+  // reason to message the owner is usually that something stopped.
+  if (rawArgs[0] === 'send') {
+    const ownership = resolveDaemonCliOwnership();
+    // Named before the delivery runs, because the flushActivityLogSync() below
+    // is what preserves this send's OUTBOUND_HTTP record — and a logger with no
+    // destination has nothing to flush, so that record was never written.
+    configureActivityLogger(join(ownership.workingDirectory, '.goodvibes', 'logs'));
+    runDaemonConfigMigration(ownership.homeDirectory);
+    const stack = createSendStack({
+      workingDirectory: ownership.workingDirectory,
+      homeDirectory: ownership.homeDirectory,
+      daemonHomeDirectory: ownership.daemonHomeDirectory,
+    });
+    const result = await runSendCommand(rawArgs.slice(1), {
+      configManager: stack.configManager,
+      deliver: stack.deliver,
+      readStdin: readAllStdin,
+      stdinIsTty: process.stdin.isTTY === true,
+    });
+    // Descriptor writes, not stream writes: the exit two lines below can leave
+    // a `console.log` still in flight, and `send` is most often run precisely
+    // because something has already stopped. See fatal-boot-report.ts.
+    for (const line of result.lines) {
+      if (result.exitCode === 0) writeExitingStdoutLine(line);
+      else writeFatalLine(line);
+    }
+    // The activity log holds the OUTBOUND_HTTP record for the send that just
+    // happened (or did not); a process exiting this promptly would drop it.
+    flushActivityLogSync();
+    process.exit(result.exitCode);
+  }
+
+  // `provision-wake-model …` is intercepted here for the same two reasons, plus
+  // its own: the curl installer runs it on the binary it has just placed, before
+  // any daemon exists, and it must reach the SDK's pinned manifest rather than
+  // have install.sh carry a second copy of the pins. It composes no runtime — it
+  // resolves a home directory, derives the managed voice root the running daemon
+  // uses, and calls one SDK function. See provision-wake-model.ts for why it
+  // exits 0 on a failed download.
+  if (rawArgs[0] === 'provision-wake-model') {
+    const ownership = resolveDaemonCliOwnership();
+    const result = await runProvisionWakeModelCommand(rawArgs.slice(1), {
+      homeDirectory: ownership.homeDirectory,
+    });
+    // The curl installer runs this on a binary it has just placed and reads the
+    // result; an exit that discards the receipt would report nothing at all.
+    for (const line of result.lines) {
+      writeExitingStdoutLine(line);
+    }
+    process.exit(result.exitCode);
+  }
+
+  // `webui …` is intercepted here for the same two reasons the commands above
+  // are, plus its own: the curl installer runs it on the binary it has just
+  // placed, right after unpacking the web UI bundle, so that the key names, the
+  // settings-tier routing and the "which listener actually serves this" question
+  // all stay in one implementation instead of being copied into shell. It
+  // composes no runtime — it resolves a home directory, opens the same config
+  // manager the daemon boots with, and writes two or three keys. See
+  // webui-command.ts.
+  if (rawArgs[0] === 'webui') {
+    const ownership = resolveDaemonCliOwnership();
+    runDaemonConfigMigration(ownership.homeDirectory);
+    const webuiConfig = new ConfigManager({
+      workingDir: ownership.workingDirectory,
+      homeDir: ownership.homeDirectory,
+      surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT,
+      // Same reason the cluster branch names it: the daemon tier this writes
+      // must be the file the booting daemon reads, even when GOODVIBES_DAEMON_HOME
+      // moved it away from the plain home.
+      daemonTierPath: daemonConfigPathForHome(ownership.daemonHomeDirectory),
+    });
+    const result = runWebuiCommand(rawArgs.slice(1), {
+      configManager: webuiConfig,
+      baseDirectory: ownership.workingDirectory,
+    });
+    // The installer runs this on a binary it has just placed and prints the
+    // result into its own receipt; a stream write lost to the exit below would
+    // leave the install saying nothing about the web UI at all.
+    for (const line of result.lines) {
+      if (result.exitCode === 0) writeExitingStdoutLine(line);
+      else writeFatalLine(line);
+    }
+    process.exit(result.exitCode);
+  }
+
+  // Parse CLI flags first so --daemon-home and --working-dir env vars are set
+  // before resolveDaemonCliOwnership() reads them.
+  //
+  // Everything the vocabulary does not contain is refused HERE, which is the
+  // change that makes the rest of this function honest. An unmatched word used
+  // to become a positional nothing read, and the process fell through to
+  // "start serving": `goodvibes-daemon doctor`, `goodvibes-daemon sessions`
+  // and `goodvibes-daemon install-servce` all silently started a daemon in the
+  // foreground. Serving now happens on a bare invocation or on `serve`, and on
+  // nothing else. See src/cli/command-catalog.ts.
+  const cli = parseDaemonCli(process.argv.slice(2), 'goodvibes-daemon');
+  if (cli.errors.length > 0) {
+    // A parse refusal is the most common reason a service unit's daemon never
+    // starts, so it goes on the descriptor the journal is attached to rather
+    // than through a stream that exits out from under it.
+    writeFatalLine(cli.errors.join('\n'));
+    writeFatalLine('');
+    writeFatalLine(renderGoodVibesDaemonHelp('goodvibes-daemon'));
+    process.exit(2);
+  }
+  if (cli.warnings.length > 0) {
+    for (const warning of cli.warnings) {
+      console.warn(`[goodvibes-daemon] warning: ${warning}`);
+    }
+  }
+  if (cli.flags.help || cli.command === 'help') {
+    // `help <command>` prints that command's own page; an unrecognized word
+    // gets the same refusal the parser would have given it, not a help page for
+    // something that does not exist.
+    const topic = cli.command === 'help' ? cli.commandArgs[0] : undefined;
+    if (topic !== undefined) {
+      const page = renderDaemonCommandHelp(topic, 'goodvibes-daemon');
+      if (page === null) {
+        writeFatalLine(`Unknown command: ${topic}`);
+        writeFatalLine('');
+        writeFatalLine(renderGoodVibesDaemonHelp('goodvibes-daemon'));
+        process.exit(2);
+      }
+      writeExitingStdoutLine(page);
+      process.exit(0);
+    }
+    // `--help` on a real command prints that command's page too, so
+    // `goodvibes-daemon sessions --help` answers about sessions.
+    if (cli.flags.help && cli.rawCommand !== undefined && cli.command !== 'help') {
+      const page = renderDaemonCommandHelp(cli.command, 'goodvibes-daemon');
+      if (page !== null) {
+        writeExitingStdoutLine(page);
+        process.exit(0);
+      }
+    }
+    writeExitingStdoutLine(renderGoodVibesDaemonHelp('goodvibes-daemon'));
+    process.exit(0);
+  }
+  if (cli.flags.version || cli.command === 'version') {
+    writeExitingStdoutLine(renderGoodVibesVersion('goodvibes-daemon'));
+    process.exit(0);
+  }
+  // `cluster`, `send`, `webui` and `provision-wake-model` are handled at the top
+  // of this function, off the raw argument list, for the reasons stated there —
+  // which means they only work as the FIRST word. Reaching one here means a
+  // global flag was written in front of it. Refusing says so; falling through
+  // would start a daemon in the foreground, which is the exact behaviour this
+  // vocabulary exists to end.
+  if (isRawInterceptCommand(cli.command)) {
+    writeFatalLine(
+      `\`${cli.command}\` has to be the first argument: goodvibes-daemon ${cli.command} …`,
+    );
+    writeFatalLine(
+      'It is dispatched before the daemon parses anything, so it keeps its own flags '
+      + '(and, for `send`, message text that starts with a dash).',
+    );
+    process.exit(2);
+  }
+  if (cli.command === 'completion') {
+    const result = runCompletionCommand(cli.commandArgs, 'goodvibes-daemon');
+    for (const line of result.lines) {
+      if (result.exitCode === 0) writeExitingStdoutLine(line);
+      else writeFatalLine(line);
+    }
+    process.exit(result.exitCode);
+  }
+  const cliFlags = cli.flags;
+  if (cliFlags.daemonHome !== undefined) {
+    process.env['GOODVIBES_DAEMON_HOME'] = cliFlags.daemonHome;
+    logger.info('daemon: --daemon-home flag applied', { daemonHome: cliFlags.daemonHome });
+  }
+  if (cliFlags.workingDir !== undefined) {
+    process.env['GOODVIBES_WORKING_DIR'] = cliFlags.workingDir;
+    logger.info('daemon: --working-dir flag applied', { workingDir: cliFlags.workingDir });
+  }
+
+  const { workingDirectory: workingDir, homeDirectory, daemonHomeDirectory, isOverridden: hasOverriddenHome } = resolveDaemonCliOwnership();
+  // Give the shared logger a destination before anything else runs. It never
+  // had one in this entrypoint: `logger` only writes to a file once
+  // `configureActivityLogger()` has named one, so every logger.info/warn/error
+  // in this daemon — including the fatal handler at the bottom of this file
+  // and every flushActivityLogSync() call — went nowhere at all. That is why
+  // a crash-looping daemon left an empty activity log next to a silent
+  // console. The terminal app's own src/cli/entrypoint.ts configures its
+  // logger the same way at the same point in startup.
+  configureActivityLogger(join(workingDir, '.goodvibes', 'logs'));
+  runDaemonConfigMigration(homeDirectory);
+  // `daemonTierPath` named explicitly (SDK 1.21.0) rather than left to
+  // ConfigManager's own `<homeDir>/.goodvibes/daemon/settings.json`
+  // derivation: `daemonHomeDirectory` is this process's own resolution of
+  // `--daemon-home`/`GOODVIBES_DAEMON_HOME`, and the two must agree so the
+  // daemon's config reads and writes the same file its identity state
+  // (operator-tokens.json, auth-users.json) already lives beside.
+  const config = new ConfigManager({
+    workingDir,
+    homeDir: homeDirectory,
+    surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT,
+    daemonTierPath: daemonConfigPathForHome(daemonHomeDirectory),
+  });
+  new GlobalNetworkTransportInstaller().install(config);
+
+  const overrideErrors = applyRuntimeConfigOverrides(config, cliFlags.configOverrides);
+  if (overrideErrors.length > 0) {
+    writeFatalLine(overrideErrors.join('\n'));
+    process.exit(2);
+  }
+  applyRuntimeFeatureFlagOverrides(config, {
+    enableFeatures: cliFlags.enableFeatures,
+    disableFeatures: cliFlags.disableFeatures,
+  });
+
+  // Apply remaining CLI flags before the provider registry is constructed.
+  // These are runtime-only overrides; they must not rewrite settings.json.
+  if (cliFlags.provider !== undefined || cliFlags.model !== undefined) {
+    const currentModel = config.get('provider.model');
+    const provider = cliFlags.provider ?? getProviderIdFromModel(currentModel);
+    const model = cliFlags.model ?? getModelIdFromProviderModel(currentModel);
+    const registryKey = formatProviderModel(provider, model);
+    applyRuntimeConfigValue(config, 'provider.model', registryKey);
+    logger.info('daemon: provider/model flags applied', { provider, model: registryKey });
+  }
+  // `--hostname`/`--port` name the address this process BINDS, and only `serve`
+  // binds anything. On `status`, `sessions`, `pair` and `update` the same
+  // `--port` names the daemon to CALL (see the remote-target convention), so
+  // writing it into this process's control-plane config would be answering a
+  // different question than the one asked. The catalog keeps the two apart by
+  // command; this keeps the write to the one command it belongs to.
+  if (cli.command === 'serve') {
+    const endpointOverrideErrors = applyRuntimeEndpointFlagOverrides(config, 'controlPlane', cliFlags);
+    if (endpointOverrideErrors.length > 0) {
+      writeFatalLine(endpointOverrideErrors.join('\n'));
+      process.exit(2);
+    }
+    if (cliFlags.port !== undefined) logger.info('daemon: --port flag applied', { port: cliFlags.port });
+    if (cliFlags.hostname !== undefined) {
+      process.env['GOODVIBES_DAEMON_HOST'] = cliFlags.hostname;
+      logger.info('daemon: --hostname flag applied', { hostname: cliFlags.hostname });
+    }
+  }
+
+  // The commands that talk to a daemon rather than being one, plus `config`,
+  // which talks to the settings files directly. All of them run BEFORE any
+  // runtime is composed: composing a second runtime graph on a machine that
+  // already has one is a second set of state, and every one of these commands
+  // exists precisely because a daemon is already there.
+  const remoteFlags = {
+    host: cliFlags.host,
+    port: cliFlags.port,
+    token: cliFlags.token,
+    json: cliFlags.json,
+  };
+  const remoteDeps = {
+    configManager: config,
+    daemonHomeDir: daemonHomeDirectory,
+    controlPlaneConfigDir: config.getControlPlaneConfigDir(),
+  };
+  const exitWith = (result: DaemonCommandResult): never => {
+    // Descriptor writes, not stream writes: each of these exits immediately
+    // afterwards, which is exactly the race a buffered console.log loses. See
+    // fatal-boot-report.ts.
+    for (const line of result.lines) {
+      if (result.exitCode === 0) writeExitingStdoutLine(line);
+      else writeFatalLine(line);
+    }
+    process.exit(result.exitCode);
+  };
+
+  if (cli.command === 'status') {
+    exitWith(await runStatusCommand({ ...remoteDeps, flags: remoteFlags }));
+  }
+  if (cli.command === 'update') {
+    exitWith(await runUpdateCommand({ ...remoteDeps, flags: { ...remoteFlags, check: cliFlags.check } }));
+  }
+  if (cli.command === 'sessions') {
+    exitWith(await runSessionsCommand({
+      ...remoteDeps,
+      flags: { ...remoteFlags, all: cliFlags.all },
+      args: cli.commandArgs,
+    }));
+  }
+  if (cli.command === 'pair') {
+    exitWith(await runPairCommand({
+      configManager: config,
+      daemonHomeDir: daemonHomeDirectory,
+      version: VERSION,
+      readToken: readOperatorTokenFile,
+      flags: { ...remoteFlags, yes: cliFlags.yes },
+    }));
+  }
+  if (cli.command === 'config') {
+    exitWith(runConfigCommand(cli.commandArgs, {
+      configManager: config,
+      json: cliFlags.json,
+      binary: 'goodvibes-daemon',
+    }));
+  }
+
+  // Service lifecycle: install / uninstall / start / stop / restart / status /
+  // migrate manage this host's service definition for the shared daemon. They
+  // run BEFORE the daemon boots — no runtime/services are constructed — and
+  // exit with the honest result code.
+  const serviceSubcommand = cli.command;
+  if (isDaemonServiceSubcommand(serviceSubcommand)) {
+    // The host/port baked into the unit's ExecStart (and displayed) come from
+    // the SAME hostMode-aware resolution the SDK bind path uses — never from
+    // the GOODVIBES_DAEMON_HOST env var, which nothing in the bind path reads
+    // (the --hostname flag already lands in config via
+    // applyRuntimeEndpointFlagOverrides above, so it is covered here).
+    const binding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+    if (!binding.recognized) {
+      // The SDK bind path has no default case for an unrecognized hostMode —
+      // a daemon launched with this config throws before binding. Say so
+      // instead of presenting the fallback values as a real binding.
+      console.warn(
+        `[goodvibes-daemon] warning: controlPlane.hostMode '${binding.hostMode}' is not a recognized mode ` +
+          "(local|network|custom) — the daemon will fail to start until it is corrected.",
+      );
+    }
+    const binaryPath = resolveInstalledDaemonBinary({ moduleUrl: import.meta.url });
+    const result = await runDaemonServiceCli({
+      subcommand: serviceSubcommand,
+      binaryPath,
+      homeDir: homeDirectory,
+      // Unit-file paths resolve from the LOGIN home, never the
+      // GOODVIBES_HOME-overridable tree home above — see
+      // BuildManagedDaemonServiceManagerParams.unitHomeDir's doc.
+      unitHomeDir: homedir(),
+      host: binding.host,
+      port: binding.port,
+      // migrate-service only: never auto-migrate — requires the same explicit
+      // consent as any other non-interactive destructive confirmation.
+      confirmMigration: cliFlags.yes,
+      // service-status only.
+      json: cliFlags.json,
+      // install-service/migrate-service refuse an explicit --hostname/--port
+      // rather than printing/probing a binding the installed unit will never
+      // actually have (it re-resolves from persisted settings at boot).
+      hostnameFlagProvided: cliFlags.hostname !== undefined,
+      portFlagProvided: cliFlags.port !== undefined,
+    });
+    // These print the unit path, the follow-up commands and the honest result,
+    // then exit immediately — exactly the race a stream write loses. Descriptor
+    // writes instead.
+    for (const line of result.lines) {
+      writeExitingStdoutLine(line);
+    }
+    process.exit(result.exitCode);
+  }
+
+  // Honest startup identity, printed for EVERY launch shape — including a bare
+  // (no-arg) systemd launch, and BEFORE any runtime construction so it still
+  // reaches the journal when a broken config makes the daemon throw during
+  // composition. It states the resolved version (never a placeholder) and the
+  // home/host/port the daemon will actually bind: the binding comes from the
+  // SAME hostMode-aware resolution the SDK bind path uses (resolveHostBinding:
+  // 'local' forces 127.0.0.1, 'network' forces 0.0.0.0, port 0/non-numeric
+  // falls back to the default) — never from controlPlane.host alone, and never
+  // from the GOODVIBES_DAEMON_HOST env var, which the bind path does not read.
+  const bannerBinding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+  // eslint-disable-next-line no-console
+  console.log(renderDaemonStartupBanner(VERSION, { homeDir: homeDirectory, host: bannerBinding.host, port: bannerBinding.port }));
+  if (!bannerBinding.recognized) {
+    // An unrecognized hostMode has NO binding the SDK can produce (its
+    // resolver has no default case and the daemon will throw below, before
+    // serving). Warn here so the journaled crash is explained.
+    console.warn(
+      `[goodvibes-daemon] warning: controlPlane.hostMode '${bannerBinding.hostMode}' is not a recognized mode ` +
+        "(local|network|custom) — the daemon cannot bind until it is corrected; the host/port above are fallback values, not a real binding.",
+    );
+  }
+
+  // Boot-time reconciliation. The banner above states the real bind; this
+  // compares it to the URL clients are actually handed. Those are produced by
+  // two different resolvers, and when they disagree the daemon is advertising an
+  // address it does not answer on — the state that produced two different click
+  // hosts from one daemon. The comparison is the SDK's own
+  // describeDerivedBindMismatch, which already knows the two cases that are NOT
+  // drift: a wildcard bind reported as 0.0.0.0 against a loopback dial target is
+  // a deliberate substitution, and a declared controlPlane.publicBaseUrl is
+  // supposed to differ from the bind. This entrypoint carried its own copy of
+  // that comparison while the published SDK predated the helper.
+  if (bannerBinding.recognized) {
+    const mismatch = describeDerivedBindMismatch(
+      { host: bannerBinding.host, port: bannerBinding.port },
+      readControlPlaneBinding((key) => config.get(key as ConfigKey)),
+    );
+    if (mismatch) {
+      console.warn(`[goodvibes-daemon] warning: ${mismatch}`);
+      logger.warn('daemon: control-plane base URL disagrees with the real bind', {
+        mismatch,
+        boundHost: bannerBinding.host,
+        boundPort: bannerBinding.port,
+      });
+    }
+  }
+
+  // Point the bus listener cap at runtime.eventBus.maxListeners before the
+  // first bus exists, so every bus this process builds later uses it.
+  configureRuntimeEventBusDefaults(runtimeEventBusOptionsFrom((key) => config.get(key)));
+  const runtimeBus = new RuntimeEventBus();
+  const runtimeStore = createRuntimeStore();
+  // Gate states derive from the domain settings keys; the bridge keeps live
+  // config changes flowing into the manager for the daemon's lifetime.
+  const featureFlags = createFeatureFlagManager();
+  featureFlags.loadFromConfig({ flags: deriveFeatureStates(config) });
+  bindFeatureSettingsBridge(config, featureFlags);
+  const runtimeServices = createRuntimeServices({
+    configManager: config,
+    featureFlags,
+    runtimeBus,
+    runtimeStore,
+    getConversationTitle: () => 'goodvibes daemon',
+    workingDir,
+    homeDirectory,
+    // Honour --daemon-home / GOODVIBES_DAEMON_HOME on the CREDENTIAL store, not
+    // just the identity directory. Without this a daemon told to run out of a
+    // temp tree still read the real home's daemon secrets, so "isolating" a
+    // test daemon left it holding the owner's live credentials.
+    daemonHomeDirectory,
+    // This daemon observes externally-launched coding-agent sessions on the
+    // host read-only (fleet visibility + steer; never counted, never
+    // stopped). Daemon-side only — the interactive process reads this snapshot
+    // rather than double-detecting. Mirrors the SDK daemon cli.
+    observeExternalAgents: true,
+    // Opt into the REAL host power seam (Linux logind: systemd-inhibit children
+    // + the dbus-monitor sleep-edge watcher) so this daemon holds live
+    // keep-awake/idle-inhibit. SDK 1.9.0's runtime-services factory defaults to
+    // the non-spawning unavailable seam; only daemon compositions opt in. Mirrors
+    // the SDK daemon cli's createHostPowerSeam() (sdk commit 3a5ea26d).
+    powerSeam: createHostPowerSeam(),
+    // The wake-word model ships with the installation, and this is the retry: at
+    // every daemon start, sweep the managed wake tree and fetch whatever the
+    // install could not (an offline install, a killed download, a changed pin).
+    // It never blocks startup and never fails it — see the SDK's
+    // voice/wake/install-provision.ts. The webui reads the model bytes from THIS
+    // process, so a provisioned daemon is what makes the browser path work too.
+    provisionWakeModelsAtBoot: true,
+  });
+
+  // Load persisted providers from disk so the provider registry is pre-populated
+  // at this daemon's startup (same machinery the TUI uses after /scan).
+  const discoveryRoots = { homeDirectory, surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT };
+  const persistedProviders = loadPersistedProviders(discoveryRoots);
+  if (persistedProviders.length > 0) {
+    runtimeServices.providerRegistry.registerDiscoveredProviders(persistedProviders);
+    logger.info('daemon: loaded persisted providers', { count: persistedProviders.length });
+  }
+
+  // Run a background LAN scan (non-blocking). Discovered servers are registered
+  // and persisted so subsequent daemon restarts benefit from the warm cache.
+  void scan().then((result) => {
+    if (result.servers.length > 0) {
+      runtimeServices.providerRegistry.registerDiscoveredProviders(result.servers);
+      persistProviders(discoveryRoots, result.servers);
+      logger.info('daemon: LAN scan complete', { found: result.servers.length });
+    } else {
+      logger.info('daemon: LAN scan found no servers');
+    }
+  }).catch((err: unknown) => {
+    logger.warn('daemon: LAN scan failed', { error: summarizeError(err) });
+  });
+
+  const userAuth = runtimeServices.localUserAuthManager;
+  const daemon = new DaemonServer({
+    runtimeBus,
+    userAuth,
+    runtimeServices,
+    serveFactory: createSafeHostServeFactory('Standalone daemon'),
+    // Hand the facade this binary's real version + exec path so its self-update
+    // lifecycle compares the HOST's version (not the sdk package's). Resolves to
+    // undefined for a non-binary install, so a dev run stays host-managed and
+    // never swaps the interpreter. See lifecycle.ts.
+    updateArtifact: resolveDaemonUpdateArtifact({ version: VERSION }),
+    // A daemon running out of an overridden home must never adopt the machine's
+    // service unit. One did: started from a scratchpad with --daemon-home, it
+    // found the unit not running, wrote its own scratchpad ExecStart into
+    // ~/.config/systemd/user/goodvibes.service and exited, and systemd then
+    // supervised the throwaway as the machine's daemon for five hours.
+    hasOverriddenHome,
+    // The SAME coordinator this repository's inbox poller registered with (see
+    // runtime/cluster-composition.ts). The facade must reuse it rather than
+    // compose its own: two coordinators in one process are two nodes in the
+    // election, and whichever lost would silence consumers the other owns.
+    clusterCoordinator: runtimeServices.clusterCoordinator,
+    // The `cluster` verbs, served on /api/cluster/*. The CLI subcommands, the
+    // TUI's /cluster command and any web UI all call these, so a command run
+    // against a REMOTE daemon behaves exactly like one run on that machine.
+    clusterGroupVerbs: runtimeServices.clusterGroup.verbs,
+    // Daemon-hosted sessions. Stating this is what turns `sessions.hosted.*`
+    // on, and what it states is where a hosted run's asks are gated — this
+    // daemon's per-workspace trust decision. See
+    // runtime/hosted-session-composition.ts.
+    hostedSessions: createHostedSessionOptions(runtimeServices),
+  });
+  const listener = new HttpListener({
+    hookDispatcher: runtimeServices.hookDispatcher,
+    userAuth,
+    configManager: config,
+    serveFactory: createSafeHostServeFactory('Standalone HTTP listener'),
+  });
+  const { daemonToken, httpToken } = readDaemonCliTokens(process.env);
+
+  // If no explicit daemon token is set, use the companion token so mobile apps
+  // can connect.
+  //
+  // The record is named 'tui' and stays named 'tui'. It is the SHARED loopback
+  // token: the terminal app, the agent and the web app all read this exact
+  // record out of operator-tokens.json to talk to this daemon. Renaming it to
+  // match the daemon's new product name would mint a second token beside the one
+  // every installed client is already holding, and each of them would start
+  // getting 401s from a daemon that is running perfectly. The name is a key in a
+  // file, not a description of who owns it.
+  const daemonHomeDir = daemonHomeDirectory;
+  const companionTokenRecord = getOrCreateCompanionToken('tui', { daemonHomeDir });
+  // Cleanup: remove stale pre-0.21.28 workspace-scoped operator token files
+  // left behind by very old installs, so only the canonical
+  // <daemonHomeDir>/operator-tokens.json survives.
+  const prune = pruneStaleOperatorTokens({
+    daemonHomeDir,
+    candidatePaths: operations.workspaceOperatorTokenCandidates(workingDir, GOODVIBES_DAEMON_SURFACE_ROOT),
+  });
+  if (prune.prunedPaths.length > 0) {
+    logger.info('daemon: pruned stale operator-token files', { count: prune.prunedPaths.length, paths: prune.prunedPaths });
+  }
+  if (prune.failedPaths.length > 0) {
+    logger.warn('daemon: failed to prune stale operator-token files (permission/race)', { count: prune.failedPaths.length, paths: prune.failedPaths });
+  }
+  const effectiveDaemonToken = daemonToken ?? companionTokenRecord.token;
+  const effectiveHttpToken = httpToken ?? effectiveDaemonToken;
+
+  daemon.enable({ daemon: true }, effectiveDaemonToken);
+  listener.enable({ httpListener: true }, effectiveHttpToken);
+
+  // Before the daemon: the group layer owns the socket the leader election
+  // coordinates over, and it announces this machine's return to the group so a
+  // box that has been off for months re-keys itself with no operator action.
+  await runtimeServices.startCluster();
+
+  // Grants and captures from paired phones outlive a restart, so the recovery
+  // sweep runs before this daemon serves its first request and the periodic one
+  // keeps a long-running daemon from going days without a sweep. The stop is
+  // registered with the disposal scope, so shutdown clears the timer.
+  startDeviceHousekeeping(runtimeServices.devicePosture);
+
+  await Promise.all([
+    daemon.start(),
+    config.get('danger.httpListener') ? listener.start() : Promise.resolve(),
+  ]);
+
+  // The boot steps the facade does not know about, because they are this
+  // product's rather than the platform's: the legacy memory fold, provider
+  // watching, and the notifier/integration attachments. They run AFTER
+  // daemon.start(), because the fold has to follow the facade's memoryStore
+  // init(), and none of them may keep the daemon from serving — see
+  // runtime/boot-tasks.ts.
+  await runDaemonBootTasks(runtimeServices);
+
+  // The DaemonServer facade owns the hourly self-update loop now (fed this
+  // binary's version + exec path via updateArtifact above); it checks hourly,
+  // swaps only at an idle moment, keeps the outgoing binary at `<path>.previous`,
+  // and stops with the daemon. No separate host loop.
+
+  const abortController = new AbortController();
+
+  const shutdown = async (): Promise<void> => {
+    abortController.abort();
+    const SHUTDOWN_DEADLINE_MS = 15_000;
+    const timeout = new Promise<'timeout'>((resolve) =>
+      setTimeout(() => resolve('timeout'), SHUTDOWN_DEADLINE_MS)
+    );
+    // daemon.stop() drives the ordered inbound teardown: it stops every gated
+    // consumer and only then broadcasts the resignation, so another node on
+    // this network takes over in about a second instead of waiting out the
+    // crash timeout.
+    //
+    // This process built the runtime graph and handed it to DaemonServer, so by
+    // the SDK's ownership rule the facade leaves it alone — nothing else stops
+    // these pollers. Without dispose() the config watch, fleet tick, memory
+    // governor, watcher registry and six more kept ticking until process exit.
+    // The handler surfaces (inbox store + its poll timers, catalog handlers) are
+    // the FIRST thing dispose() unwinds — they are on the disposal owner list
+    // now rather than sequenced by hand here, which is what makes every other
+    // shutdown path stop them too instead of only this one.
+    const stop = Promise.allSettled([listener.stop(), daemon.stop()])
+      .then(() => { runtimeServices.dispose(); })
+      .then(() => 'done' as const);
+    const result = await Promise.race([stop, timeout]);
+    if (result === 'timeout') {
+      logger.warn('shutdown deadline exceeded — forcing exit');
+      // A forced exit is exactly the case where the log matters most and is
+      // least likely to have drained on its own.
+      flushActivityLogSync();
+      process.exit(1);
+    }
+    flushActivityLogSync();
+    process.exit(0);
+  };
+
+  let shutdownInFlight = false;
+  const handleSignal = (): void => {
+    if (shutdownInFlight) return;
+    shutdownInFlight = true;
+    void shutdown();
+  };
+
+  process.on('SIGINT', handleSignal);
+  process.on('SIGTERM', handleSignal);
+
+  logger.info('goodvibes daemon host started', {
+    daemon: resolveDaemonEnabled(config),
+    httpListener: config.get('danger.httpListener'),
+  });
+
+  // Cheap unattended reconcile: if this (canonical) daemon unit is confirmed
+  // serving AND a redundant installer-managed goodvibes-daemon.service (the
+  // retired unit name) sits enabled-but-NOT-running beside it — the exact
+  // production-incident state — auto-disable and remove it, printing a
+  // receipt. A RUNNING legacy daemon, a hand-written unit, or an unanswered
+  // configured endpoint all refuse with a notice instead. Best-effort: never
+  // let this block or crash daemon boot (per-call systemctl timeouts plus one
+  // cumulative pass deadline). The unit search root is the LOGIN user's home
+  // (where systemd user units live), never the daemon data home
+  // (GOODVIBES_DAEMON_HOME); the tracked name honors service.serviceName. The
+  // endpoint requirement uses the CLIENT view of the config — a fresh read of
+  // settings.json with none of this process's runtime flag overrides — because
+  // that is what clients resolve when they look for the daemon.
+  try {
+    runDaemonConfigMigration(homeDirectory);
+    const clientViewConfig = new ConfigManager({
+      workingDir,
+      homeDir: homeDirectory,
+      surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT,
+      daemonTierPath: daemonConfigPathForHome(daemonHomeDirectory),
+    });
+    const clientEndpoint = resolveRuntimeEndpointBinding(clientViewConfig, 'controlPlane');
+    const reconcile = await reconcileRedundantLegacyUnit({
+      homeDir: homedir(),
+      trackedServiceName: resolveConfiguredServiceName(clientViewConfig),
+      configuredEndpoint: { host: clientEndpoint.host, port: clientEndpoint.port },
+    });
+    if (reconcile.action !== 'noop') {
+      for (const line of reconcile.lines) {
+        // eslint-disable-next-line no-console
+        console.log(line);
+      }
+    }
+    if (reconcile.reason !== 'no-legacy-unit') {
+      // Breadcrumb for EVERY outcome where a legacy unit file exists —
+      // including guard refusals — so a persisting two-unit state is never
+      // silent about why nothing was reconciled.
+      logger.info('daemon: legacy-unit reconcile', { action: reconcile.action, reason: reconcile.reason });
+    }
+  } catch (error) {
+    logger.warn('daemon: legacy-unit reconcile failed (non-fatal)', { error: summarizeError(error) });
+  }
+
+  // Print a device-pairing QR to stdout. The QR encodes the canonical
+  // `#pair=<token>` deep link the web app consumes — a camera scan opens it
+  // already signed in. No raw JSON connection blob is printed. This is also the
+  // one place web.publicBaseUrl is frozen from the stable-name resolution (never
+  // clobbering a user-set value), so the printed origin survives a DHCP change.
+  // The daemon's shared companion token rides as the pairing token; a device can
+  // later migrate to its own per-device token from /settings → security → devices.
+  const webOrigin = ensurePublicBaseUrl(config);
+  const offers = availablePairingOffers({
+    relayEnabled: config.get('relay.enabled') === true,
+    stepUpAvailable: true,
+  });
+  // Rendered by core/pairing-banner.ts, which `goodvibes-daemon pair` also
+  // calls — so the block printed here and the one printed on demand are the
+  // same block, from the same token, and cannot drift.
+  const banner = renderPairingBanner({
+    version: VERSION,
+    origin: webOrigin.origin,
+    token: companionTokenRecord.token,
+    offers,
+  });
+  // eslint-disable-next-line no-console
+  console.log(banner.lines.join('\n'));
+  // eslint-disable-next-line no-console
+  console.log('(print this again at any time: goodvibes-daemon pair)');
+}
+
+void main().catch((error) => {
+  // A daemon that dies during startup must leave the reason where an operator
+  // will actually find it: on the file descriptor the service journal is
+  // attached to, written synchronously, BEFORE the activity log is attempted.
+  //
+  // Doing it the other way round is what shipped mute. This handler used to
+  // call logger.error and flushActivityLogSync and nothing else, and the
+  // logger had no destination this early in boot — so the released 1.27.0
+  // binary crash-looped 77 times with exit 1, zero bytes on stdout, zero bytes
+  // on stderr and an empty activity log. See fatal-boot-report.ts.
+  reportFatalBootFailure(error);
+  process.exit(1);
+});