bloby-bot 0.66.1 → 0.68.0

package/bin/cli.js

@@ -1,6 +1,29 @@
 #!/usr/bin/env node
 
-import { spawn, execSync, spawnSync } from 'child_process';
+// ─────────────────────────────────────────────────────────────────────────────
+// Bloby CLI — single entry point for the bloby command.
+//
+// Design rules (load-bearing — do not break):
+//  - ZERO npm deps at top level. This file must run even when ~/.bloby's
+//    node_modules is broken, because it IS the recovery tool (self-heal below).
+//  - Every command daemonizes and returns the terminal. The only foreground
+//    paths are `start --foreground` (debug) and platforms with no daemon
+//    support (Windows, containers without systemd) — incl. `init --hosted`.
+//  - The supervisor writes ~/.bloby/supervisor.json at boot (pid/startedAt/
+//    version/port). That pidfile — not launchctl/systemctl alone — is the
+//    source of truth for "is Bloby running", so status/logs can never show a
+//    process that isn't alive anymore, regardless of how it was launched.
+//  - Contracts preserved for external callers:
+//      supervisor self-update: `cli.js update` + BLOBY_SELF_UPDATE=1 → exit 0
+//        on success-or-already-latest, never touches the daemon, headless-safe.
+//      supervisor relaunch:    `cli.js daemon restart` detached, no TTY.
+//      hosted provisioning:    `cli.js init --hosted` → __HOSTED_READY__=<json>.
+//      foreground boot parses supervisor stdout markers __READY__,
+//        __TUNNEL_URL__=, __RELAY_URL__=, __VITE_WARM__, __TUNNEL_FAILED__.
+//      env: BLOBY_NODE_PATH, BLOBY_REAL_HOME, SUDO_USER, BLOBY_SELF_UPDATE.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { spawn, spawnSync, execSync, execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -10,12 +33,35 @@ import { fileURLToPath, pathToFileURL } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const REPO_ROOT = path.resolve(__dirname, '..');
-const DATA_DIR = path.join(process.env.BLOBY_REAL_HOME || os.homedir(), '.bloby');
+
+// Resolve the real user's home even when invoked as `sudo bloby ...` directly —
+// otherwise DATA_DIR silently becomes /root/.bloby and state forks.
+function resolveRealHome() {
+  if (process.env.BLOBY_REAL_HOME) return process.env.BLOBY_REAL_HOME;
+  if (process.getuid?.() === 0 && process.env.SUDO_USER) {
+    if (os.platform() === 'darwin') {
+      // getent doesn't exist on macOS — dscl is the equivalent.
+      try {
+        const out = execFileSync('dscl', ['.', '-read', `/Users/${process.env.SUDO_USER}`, 'NFSHomeDirectory'], { encoding: 'utf-8' });
+        const home = out.split(':').pop()?.trim();
+        if (home) return home;
+      } catch {}
+      return `/Users/${process.env.SUDO_USER}`;
+    }
+    try {
+      return execFileSync('getent', ['passwd', process.env.SUDO_USER], { encoding: 'utf-8' }).split(':')[5].trim();
+    } catch {}
+  }
+  return os.homedir();
+}
+
+const DATA_DIR = path.join(resolveRealHome(), '.bloby');
 const IS_DEV = fs.existsSync(path.join(REPO_ROOT, '.git'));
 const ROOT = IS_DEV ? REPO_ROOT : DATA_DIR;
 const CONFIG_PATH = path.join(DATA_DIR, 'config.json');
 const BIN_DIR = path.join(DATA_DIR, 'bin');
 const CF_PATH = path.join(BIN_DIR, 'cloudflared');
+const RUNTIME_PATH = path.join(DATA_DIR, 'supervisor.json');
 
 // claude-agent-sdk 0.3.x moved @anthropic-ai/sdk + @modelcontextprotocol/sdk to
 // peerDependencies. Upgrading an existing ~/.bloby in place (the old 0.2.x tree had
@@ -67,18 +113,571 @@ if (!IS_DEV) {
 }
 
 const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
-const args = process.argv.slice(2);
-const command = args[0];
-const subcommand = args[1];
-const flags = new Set(args.filter(a => a.startsWith('--')));
+
+// ── Argv parsing (strict — see router at the bottom) ──
+
+const argv = process.argv.slice(2);
+// Global flags can appear anywhere (legacy callers do `bloby --hosted`).
+// x402 owns its own flags, so everything after `x402` passes through verbatim.
+const x402Index = argv.indexOf('x402');
+const globalArgs = x402Index === -1 ? argv : argv.slice(0, x402Index + 1);
+const flags = new Set(globalArgs.filter(a => a.startsWith('-')));
 const HOSTED = flags.has('--hosted');
+const FOREGROUND = flags.has('--foreground');
+const FOLLOW = flags.has('-f') || flags.has('--follow');
+const positional = globalArgs.filter(a => !a.startsWith('-'));
+const command = positional[0];
+const subcommand = positional[1];
+
+// Strict parsing covers flags too — a typo like --forground must not silently
+// fall through to a different behavior (x402's own flags pass through verbatim).
+const KNOWN_FLAGS = new Set(['--hosted', '--foreground', '-f', '--follow', '-n', '--lines', '-h', '--help', '-v', '--version']);
+for (const f of flags) {
+  const name = f.includes('=') ? f.slice(0, f.indexOf('=')) : f;
+  if (!KNOWN_FLAGS.has(name)) {
+    console.error(`\n  ✗  Unknown flag: ${f}\n     Run bloby help for usage.\n`);
+    process.exit(2);
+  }
+}
+
+function flagValue(name) {
+  for (let i = 0; i < globalArgs.length; i++) {
+    const a = globalArgs[i];
+    if (a === name) return globalArgs[i + 1] ?? null;
+    if (a.startsWith(name + '=')) return a.slice(name.length + 1);
+  }
+  return null;
+}
+
+// ── UI kit ──
+// Style contract: identical to scripts/install.sh — 2-space indent, '  <glyph>  text'
+// rhythm, BLUE for success/commands, deep-blue PINK only for ready-lines and '>',
+// '!' YELLOW for warnings, 29-char DIM dividers, sequential step lines (no
+// full-screen repaints). Colors gate on TTY + NO_COLOR so pipes stay clean.
+
+const FORCE_COLOR = process.env.FORCE_COLOR;
+const useColor = FORCE_COLOR && FORCE_COLOR !== '0'
+  ? true
+  : (!!process.stdout.isTTY && !('NO_COLOR' in process.env) && process.env.TERM !== 'dumb');
+const isTTY = !!process.stdout.isTTY;
+
+// Animations + cursor control need a real terminal — TERM=dumb gets plain lines.
+const fancyTTY = isTTY && process.env.TERM !== 'dumb';
+
+const A = (s) => (useColor ? s : '');
+const c = {
+  reset: A('\x1b[0m'),
+  dim: A('\x1b[2m'),
+  bold: A('\x1b[1m'),
+  green: A('\x1b[32m'),
+  cyan: A('\x1b[36m'),
+  yellow: A('\x1b[33m'),
+  red: A('\x1b[31m'),
+  white: A('\x1b[97m'),
+  blue: A('\x1b[38;2;0;173;254m'),
+  pink: A('\x1b[38;2;1;88;251m'),
+  g1: A('\x1b[38;2;0;173;254m'),
+  g2: A('\x1b[38;2;0;159;254m'),
+  g3: A('\x1b[38;2;0;145;253m'),
+  g4: A('\x1b[38;2;1;131;253m'),
+  g5: A('\x1b[38;2;1;116;252m'),
+  g6: A('\x1b[38;2;1;102;251m'),
+  g7: A('\x1b[38;2;1;88;251m'),
+};
+
+const GLYPH = {
+  ok: `${c.blue}✔${c.reset}`,
+  err: `${c.red}✗${c.reset}`,
+  warn: `${c.yellow}!${c.reset}`,
+  dl: `${c.blue}↓${c.reset}`,
+  next: `${c.pink}>${c.reset}`,
+};
+const DIVIDER = `  ${c.dim}${'─'.repeat(29)}${c.reset}`;
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const BAR_WIDTH = 30;
+
+function link(url) {
+  return isTTY && useColor ? `\x1b]8;;${url}\x07${url}\x1b]8;;\x07` : url;
+}
+
+function stripAnsi(s) {
+  // SGR colors + OSC-8 hyperlinks — needed to measure visible width for boxes.
+  return s.replace(/\x1b\[[0-9;]*m/g, '').replace(/\x1b\]8;;.*?(\x07|\x1b\\)/g, '');
+}
+
+// Morphy gradient #00ADFE → #0158FB across the progress bar (matches the logo).
+function gradientChar(i, total) {
+  if (!useColor) return '';
+  const t = total > 1 ? i / (total - 1) : 0;
+  const r = Math.round(0 + t * 1);
+  const g = Math.round(173 + t * (88 - 173));
+  const b = Math.round(254 + t * (251 - 254));
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+function progressBar(ratio, width = BAR_WIDTH) {
+  const filled = Math.round(Math.max(0, Math.min(1, ratio)) * width);
+  let bar = '';
+  for (let i = 0; i < filled; i++) bar += `${gradientChar(i, width)}█`;
+  bar += `${c.reset}${c.dim}${'░'.repeat(width - filled)}${c.reset}`;
+  return bar;
+}
+
+/** The final state of a command ("Bloby is running", "Bloby stopped") gets a box —
+ *  it's the one thing the user came for, so it must be unmissable. Pipes get the
+ *  content as plain lines. */
+function resultBox(lines) {
+  if (!isTTY) {
+    for (const l of lines) {
+      const plain = stripAnsi(l);
+      console.log(plain.trim() ? `  ${l}` : '');
+    }
+    return;
+  }
+  const width = Math.max(...lines.map(l => stripAnsi(l).length)) + 4;
+  const B = c.blue;
+  console.log('');
+  console.log(`  ${B}╭${'─'.repeat(width)}╮${c.reset}`);
+  for (const l of lines) {
+    const pad = width - 2 - stripAnsi(l).length;
+    console.log(`  ${B}│${c.reset} ${l}${' '.repeat(Math.max(0, pad))} ${B}│${c.reset}`);
+  }
+  console.log(`  ${B}╰${'─'.repeat(width)}╯${c.reset}`);
+}
+
+// Single terminal-cleanup path: restore cursor + raw mode, stop any spinner.
+// Registered once; every exit route (normal, SIGINT, SIGTERM, crash) goes through it.
+let activeSpinner = null;
+let foregroundChild = null; // set by bootServer — the global handlers must kill it before exiting
+function restoreTerminal() {
+  if (activeSpinner) { try { activeSpinner.stopRaw(); } catch {} activeSpinner = null; }
+  if (fancyTTY) process.stdout.write('\x1b[?25h');
+  if (process.stdin.isTTY) { try { process.stdin.setRawMode(false); } catch {} }
+}
+process.on('exit', restoreTerminal);
+process.on('SIGINT', () => { restoreTerminal(); try { foregroundChild?.kill('SIGINT'); } catch {} process.exit(130); });
+process.on('SIGTERM', () => { restoreTerminal(); try { foregroundChild?.kill('SIGTERM'); } catch {} process.exit(143); });
+process.on('uncaughtException', (err) => {
+  restoreTerminal();
+  console.error(`\n  ${GLYPH.err}  ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+  restoreTerminal();
+  console.error(`\n  ${GLYPH.err}  ${reason && reason.message ? reason.message : reason}\n`);
+  process.exit(1);
+});
+
+/** One-line spinner. On a TTY it animates in place; on pipes/logs it prints plain
+ *  sequential lines so headless callers (self-update → update.log) get clean text. */
+class Spinner {
+  constructor() { this.text = ''; this.timer = null; this.frame = 0; this.live = false; }
+  start(text) {
+    this.text = text;
+    if (fancyTTY) {
+      activeSpinner = this;
+      this.live = true;
+      process.stdout.write('\x1b[?25l');
+      this.timer = setInterval(() => {
+        this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+        this.render();
+      }, 80);
+      this.render();
+    } else {
+      console.log(`  …  ${text}`);
+    }
+    return this;
+  }
+  render() {
+    if (!this.live) return;
+    process.stdout.write(`\r\x1b[2K  ${c.pink}${SPINNER_FRAMES[this.frame]}${c.reset}  ${this.text}`);
+  }
+  update(text) {
+    this.text = text;
+    if (this.live) this.render();
+    else console.log(`  …  ${text}`);
+    return this;
+  }
+  stopRaw() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    if (this.live) {
+      process.stdout.write('\r\x1b[2K');
+      process.stdout.write('\x1b[?25h');
+      this.live = false;
+    }
+    if (activeSpinner === this) activeSpinner = null;
+  }
+  /** Pause the animation (e.g. while sudo prompts on the same terminal), then resume(). */
+  pause() { const t = this.text; this.stopRaw(); this.text = t; return this; }
+  resume() { if (fancyTTY && !this.live) this.start(this.text); return this; }
+  succeed(text) { this.stopRaw(); console.log(`  ${GLYPH.ok}  ${text ?? this.text}`); return this; }
+  fail(text)    { this.stopRaw(); console.log(`  ${GLYPH.err}  ${text ?? this.text}`); return this; }
+  warn(text)    { this.stopRaw(); console.log(`  ${GLYPH.warn}  ${text ?? this.text}`); return this; }
+  info(text)    { this.stopRaw(); console.log(`  ${c.dim}${text ?? this.text}${c.reset}`); return this; }
+}
+
+/** Multi-step progress display for start/restart/update — step list + gradient
+ *  progress bar, repainted in place (the old "stepper", rebuilt on safe footing):
+ *  TTY-gated (plain sequential lines on pipes, so update.log stays readable),
+ *  a real fail() state instead of an all-green finish, pause()/resume() so a
+ *  sudo password prompt isn't erased by the repaint, and no stdin raw-mode grabs.
+ *  Exposes the same update/pause/resume/stopRaw surface as Spinner so
+ *  runPrivileged/ensureCloudflared work with either. */
+class Steps {
+  constructor(titles) {
+    this.titles = [...titles];
+    this.current = 0;
+    this.frame = 0;
+    this.timer = null;
+    this.notes = [];
+    this._lines = 0;
+    this.live = false;
+    this.done = false;
+    this._failed = false;
+    this._printedNotes = new Set();
+  }
+  start() {
+    console.log('');
+    if (fancyTTY) {
+      activeSpinner = this;
+      this.live = true;
+      process.stdout.write('\x1b[?25l');
+      this.timer = setInterval(() => {
+        this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+        this.render();
+      }, 80);
+      this.render();
+    } else if (this.titles.length) {
+      console.log(`  …  ${this.titles[0]}`);
+    }
+    return this;
+  }
+  render() {
+    if (!this.live) return;
+    let out = '';
+    if (this._lines > 0) out += `\x1b[${this._lines}A`;
+    const W = (s = '') => { out += `\x1b[2K${s}\n`; };
+    for (let i = 0; i < this.titles.length; i++) {
+      if (i < this.current) W(`  ${GLYPH.ok}  ${this.titles[i]}`);
+      else if (i === this.current && this._failed) W(`  ${GLYPH.err}  ${this.titles[i]}`);
+      else if (i === this.current && !this.done) W(`  ${c.pink}${SPINNER_FRAMES[this.frame]}${c.reset}  ${this.titles[i]}${c.dim}...${c.reset}`);
+      else W(`  ${c.dim}○  ${this.titles[i]}${c.reset}`);
+    }
+    const ratio = this.current / this.titles.length;
+    W();
+    const label = ratio >= 1 ? `${c.pink}Done${c.reset}` : `${c.dim}${Math.round(ratio * 100)}%${c.reset}`;
+    W(`  ${progressBar(ratio)}  ${label}`);
+    let count = this.titles.length + 2;
+    if (this.notes.length) {
+      W();
+      for (const n of this.notes) W(n);
+      count += 1 + this.notes.length;
+    }
+    if (count < this._lines) {
+      const extra = this._lines - count;
+      for (let i = 0; i < extra; i++) out += '\x1b[2K\n';
+      out += `\x1b[${extra}A`;
+    }
+    process.stdout.write(out);
+    this._lines = count;
+  }
+  advance() {
+    if (this.current >= this.titles.length) return this;
+    if (!this.live) {
+      console.log(`  ${GLYPH.ok}  ${this.titles[this.current]}`);
+      this.current++;
+      if (this.current < this.titles.length) console.log(`  …  ${this.titles[this.current]}`);
+      return this;
+    }
+    this.current++;
+    this.render();
+    return this;
+  }
+  setNote(lines) {
+    const arr = lines || [];
+    if (!this.live) {
+      for (const n of arr) {
+        const key = stripAnsi(n);
+        if (!this._printedNotes.has(key)) { this._printedNotes.add(key); console.log(n); }
+      }
+      this.notes = arr;
+      return this;
+    }
+    this.notes = arr;
+    this.render();
+    return this;
+  }
+  /** Spinner-compat: transient sub-status (cloudflared download, sudo notice). */
+  update(text) { return this.setNote(text ? [`  ${c.dim}${text}${c.reset}`] : []); }
+  pause() {
+    if (this.live) { this._paused = true; this._stop(); }
+    return this;
+  }
+  resume() {
+    if (this._paused && fancyTTY && !this.done) {
+      this._paused = false;
+      this.live = true;
+      activeSpinner = this;
+      process.stdout.write('\x1b[?25l');
+      this._lines = 0; // repaint fresh below whatever the pause printed
+      this.timer = setInterval(() => {
+        this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+        this.render();
+      }, 80);
+      this.render();
+    }
+    return this;
+  }
+  _stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    if (this.live) {
+      process.stdout.write('\x1b[?25h');
+      this.live = false;
+    }
+    if (activeSpinner === this) activeSpinner = null;
+  }
+  stopRaw() { this._stop(); }
+  finish() {
+    this.notes = [];
+    if (this.live) {
+      this.current = this.titles.length;
+      this.done = true;
+      this.render();
+      // render() guards on live, so flip done before the final paint above, then stop.
+      this._stop();
+    } else {
+      while (this.current < this.titles.length) {
+        console.log(`  ${GLYPH.ok}  ${this.titles[this.current]}`);
+        this.current++;
+      }
+      this.done = true;
+    }
+    return this;
+  }
+  fail(message) {
+    this.notes = [];
+    this._failed = true;
+    if (this.live) {
+      this.render();
+      this._stop();
+    } else if (this.current < this.titles.length) {
+      console.log(`  ${GLYPH.err}  ${this.titles[this.current]}`);
+    }
+    this.done = true;
+    if (message) console.log(`\n  ${GLYPH.err}  ${message}`);
+    return this;
+  }
+}
+
+function banner() {
+  if (HOSTED) return;
+  console.log(`
+  ${c.g1}${c.bold}                              █▄         ${c.reset}
+  ${c.g2}${c.bold}    ▄              ▄          ██         ${c.reset}
+  ${c.g3}${c.bold}    ███▄███▄ ▄███▄ ████▄████▄ ████▄ ██ ██${c.reset}
+  ${c.g4}${c.bold}    ██ ██ ██ ██ ██ ██   ██ ██ ██ ██ ██▄██${c.reset}
+  ${c.g5}${c.bold}   ▄██ ██ ▀█▄▀███▀▄█▀  ▄████▀▄██ ██▄▄▀██▀${c.reset}
+  ${c.g6}${c.bold}                        ██            ██ ${c.reset}
+  ${c.g7}${c.bold}                        ▀           ▀▀▀  ${c.reset}
+  ${c.dim}v${pkg.version} · Self-hosted, self-evolving AI agent${c.reset}`);
+}
+
+const CORE_COMMANDS = [
+  ['start', 'Start Bloby (runs in the background)'],
+  ['stop', 'Stop Bloby'],
+  ['restart', 'Restart Bloby'],
+  ['status', 'Status, URLs and health'],
+  ['logs', 'Recent logs (-f to follow)'],
+  ['update', 'Update to the latest version'],
+  ['help', 'All commands'],
+];
+
+/** Printed after every command (TTY only) — the user asked for the command list
+ *  to always be visible when a command finishes. */
+function commandsFooter() {
+  if (!isTTY || HOSTED) return;
+  console.log('');
+  console.log(DIVIDER);
+  console.log(`  ${c.bold}Commands:${c.reset}\n`);
+  for (const [cmd, desc] of CORE_COMMANDS) {
+    console.log(`    ${c.blue}${('bloby ' + cmd).padEnd(16)}${c.reset}${desc}`);
+  }
+  console.log('');
+}
+
+function printHelp() {
+  banner();
+  console.log(`
+  ${c.bold}Usage:${c.reset} bloby <command>
+
+  ${c.bold}Core${c.reset}
+    ${c.blue}${'init'.padEnd(18)}${c.reset}First-time setup (config, wallet, tunnel)
+    ${c.blue}${'start'.padEnd(18)}${c.reset}Start Bloby in the background
+    ${c.blue}${'stop'.padEnd(18)}${c.reset}Stop Bloby
+    ${c.blue}${'restart'.padEnd(18)}${c.reset}Restart Bloby (same as stop + start)
+    ${c.blue}${'status'.padEnd(18)}${c.reset}Status, URLs and health
+    ${c.blue}${'logs'.padEnd(18)}${c.reset}Show recent logs (${c.dim}-f${c.reset} follow, ${c.dim}-n <num>${c.reset} lines)
+    ${c.blue}${'update'.padEnd(18)}${c.reset}Update to the latest version
+
+  ${c.bold}Advanced${c.reset}
+    ${c.blue}${'tunnel'.padEnd(18)}${c.reset}Tunnel config (setup, status, reset)
+    ${c.blue}${'daemon <action>'.padEnd(18)}${c.reset}install · start · stop · restart · status · logs · uninstall
+    ${c.blue}${'password-reset'.padEnd(18)}${c.reset}Reset the dashboard password
+    ${c.blue}${'x402 <url>'.padEnd(18)}${c.reset}Pay an x402-protected endpoint (USDC on Base)
+    ${c.blue}${'version'.padEnd(18)}${c.reset}Print the installed version
+
+  ${c.bold}Flags${c.reset}
+    ${c.dim}start --foreground${c.reset}   Run attached to this terminal (debugging)
+`);
+}
+
+// Zero-dep Levenshtein for "did you mean" (two-row DP).
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+function suggestCommand(input) {
+  const candidates = ['init', 'start', 'stop', 'restart', 'status', 'logs', 'update', 'daemon', 'tunnel', 'password-reset', 'x402', 'help', 'version'];
+  const lower = input.toLowerCase();
+  const maxDist = lower.length <= 4 ? 1 : 2;
+  let best = null;
+  let bestDist = Infinity;
+  for (const cand of candidates) {
+    const d = levenshtein(lower, cand);
+    if (d < bestDist) { bestDist = d; best = cand; }
+  }
+  return bestDist <= maxDist ? best : null;
+}
+
+function unknownCommand(input) {
+  console.log(`\n  ${GLYPH.err}  Unknown command: ${c.bold}${input}${c.reset}`);
+  const suggestion = suggestCommand(input);
+  if (suggestion) {
+    console.log(`     Did you mean ${c.blue}bloby ${suggestion}${c.reset}?`);
+  }
+  commandsFooter();
+  process.exit(2);
+}
+
+// ── Config helpers ──
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); } catch { return null; }
+}
+
+function tunnelModeOf(config) {
+  return config?.tunnel?.mode ?? (config?.tunnel?.enabled === false ? 'off' : 'quick');
+}
+
+function writeVersionFile(version) {
+  try { fs.writeFileSync(path.join(DATA_DIR, 'VERSION'), version); } catch {}
+}
+
+// ── Process / pidfile helpers (the single source of truth for "is Bloby running") ──
+
+function procAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function procCommand(pid) {
+  if (PLATFORM === 'win32') return '';
+  try {
+    return execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf-8' }).trim();
+  } catch { return ''; }
+}
+
+/** Match only THIS install's supervisor — other agents on the same machine may
+ *  run an identical supervisor/index.ts layout from their own directories, and
+ *  a generic match would make `bloby stop` kill them. */
+function isSupervisorCommand(cmd) {
+  if (!/supervisor[\\/]index\.ts/.test(cmd)) return false;
+  const ours = [
+    path.join(ROOT, 'supervisor'),
+    path.join(DATA_DIR, 'supervisor'),
+    path.join(REPO_ROOT, 'supervisor'),
+  ];
+  // Anchor at a path boundary so a sibling dir that merely starts with our path can't match.
+  return ours.some(p => cmd.includes(p + path.sep));
+}
+
+/** Read ~/.bloby/supervisor.json (written by the supervisor at boot) and validate the
+ *  pid is alive AND still a supervisor process (defends against PID reuse). */
+function readRuntime() {
+  try {
+    const data = JSON.parse(fs.readFileSync(RUNTIME_PATH, 'utf-8'));
+    if (!data || !data.pid) return null;
+    if (!procAlive(data.pid)) return null;
+    // Defend against PID reuse — but only when we can actually inspect the
+    // command line (win32 / locked-down ps return '': trust liveness alone).
+    const cmd = procCommand(data.pid);
+    if (cmd && !isSupervisorCommand(cmd)) return null;
+    return data;
+  } catch { return null; }
+}
+
+/** Find every live supervisor process (daemon, foreground, orphans) by scanning ps.
+ *  This is what lets stop/restart consolidate duplicate instances. */
+function scanSupervisors() {
+  if (PLATFORM === 'win32') return [];
+  try {
+    const out = execFileSync('ps', ['ax', '-o', 'pid=,command='], { encoding: 'utf-8' });
+    return out.split('\n')
+      .map(l => l.trim())
+      .filter(Boolean)
+      .map(l => {
+        const sp = l.indexOf(' ');
+        return { pid: Number(l.slice(0, sp)), command: l.slice(sp + 1).trim() };
+      })
+      .filter(p => p.pid !== process.pid && isSupervisorCommand(p.command));
+  } catch { return []; }
+}
+
+function formatUptime(ms) {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+function formatAgo(ms) {
+  return formatUptime(ms) + ' ago';
+}
+
+/** > 0 when a is newer than b. Plain x.y.z comparison — good enough for npm dist-tags. */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
 
-// ── Terminal safety: always restore cursor on exit ──
-process.on('exit', () => process.stdout.write('\x1b[?25h'));
-process.on('SIGINT', () => { process.stdout.write('\x1b[?25h'); process.exit(0); });
-process.on('SIGTERM', () => { process.stdout.write('\x1b[?25h'); process.exit(0); });
+async function fetchHealth(port, timeoutMs = 2500) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health?_cb=${Date.now()}`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    return await res.json().catch(() => ({}));
+  } catch { return null; }
+}
 
-// ── Daemon constants & helpers ──
+// ── Platform daemon adapters ──
 
 const PLATFORM = os.platform();
 
@@ -87,19 +686,30 @@ const SERVICE_NAME = 'bloby';
 const SERVICE_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
 
 function needsSudo() {
-  return process.getuid() !== 0;
+  return process.getuid?.() !== 0;
 }
 
-function sudoReExec() {
-  const nodePath = process.env.BLOBY_NODE_PATH || process.execPath;
-  const realHome = getRealHome();
-  const args = process.argv.slice(1);
-  const result = spawnSync('sudo', [
-    `BLOBY_NODE_PATH=${nodePath}`,
-    `BLOBY_REAL_HOME=${realHome}`,
-    nodePath, ...args,
-  ], { stdio: 'inherit' });
-  process.exit(result.status ?? 1);
+/** Run one privileged command (systemctl, cp into /etc) without re-execing the
+ *  whole CLI: root runs it directly; otherwise try passwordless `sudo -n` first,
+ *  fall back to an interactive prompt on a TTY (pausing any spinner), and fail
+ *  fast with the exact manual command when headless. This is what lets the
+ *  supervisor's detached relaunch and `bloby update` work on Linux at all —
+ *  the old whole-CLI sudo re-exec hung headless and re-ran update as root. */
+function runPrivileged(cmdArgs, { spinner } = {}) {
+  if (!needsSudo()) {
+    const r = spawnSync(cmdArgs[0], cmdArgs.slice(1), { stdio: 'pipe', encoding: 'utf-8' });
+    return { ok: r.status === 0, error: (r.stderr || '').trim() || (r.status !== 0 ? `${cmdArgs.join(' ')} failed (exit ${r.status})` : null) };
+  }
+  let r = spawnSync('sudo', ['-n', ...cmdArgs], { stdio: 'pipe', encoding: 'utf-8' });
+  if (r.status === 0) return { ok: true, error: null };
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    if (spinner) spinner.pause();
+    console.log(`  ${c.dim}sudo is required — you may be asked for your password.${c.reset}`);
+    r = spawnSync('sudo', cmdArgs, { stdio: 'inherit' });
+    if (spinner) spinner.resume();
+    return { ok: r.status === 0, error: r.status === 0 ? null : `sudo ${cmdArgs.join(' ')} failed (exit ${r.status})` };
+  }
+  return { ok: false, error: `needs sudo and there is no terminal to ask for a password — run: sudo ${cmdArgs.join(' ')}` };
 }
 
 function getRealUser() {
@@ -107,25 +717,7 @@ function getRealUser() {
 }
 
 function getRealHome() {
-  if (process.env.BLOBY_REAL_HOME) return process.env.BLOBY_REAL_HOME;
-  try {
-    return execSync(`getent passwd ${getRealUser()}`, { encoding: 'utf-8' }).split(':')[5];
-  } catch {
-    return os.homedir();
-  }
-}
-
-function isServiceInstalled() {
-  return fs.existsSync(SERVICE_PATH);
-}
-
-function isServiceActive() {
-  try {
-    execSync(`systemctl is-active ${SERVICE_NAME}`, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
+  return resolveRealHome();
 }
 
 function generateUnitFile({ user, home, nodePath, dataDir }) {
@@ -155,32 +747,74 @@ WantedBy=multi-user.target
 `;
 }
 
+function systemdShow() {
+  try {
+    const out = execFileSync('systemctl', ['show', SERVICE_NAME, '-p', 'MainPID', '-p', 'ActiveState', '-p', 'LoadState'], { encoding: 'utf-8' });
+    const get = (key) => (out.match(new RegExp(`^${key}=(.*)$`, 'm')) || [])[1] || '';
+    return { mainPid: Number(get('MainPID')) || 0, activeState: get('ActiveState'), loadState: get('LoadState') };
+  } catch {
+    return { mainPid: 0, activeState: 'unknown', loadState: 'unknown' };
+  }
+}
+
 // --- launchd (macOS) ---
+// Modern launchctl only (bootstrap/bootout/kickstart/print with explicit domain
+// targets). The legacy load/unload/list subcommands ALWAYS exit 0 and resolve the
+// domain from the caller's context — which is how SSH/tmux/detached invocations
+// used to boot duplicate instances and strand stale logs. Exit codes from the
+// modern verbs are real: 3=not loaded, 36/37=op (already) in progress,
+// 113=service not found, 119=disabled (Login Items toggle), 125=bad domain.
 const LAUNCHD_LABEL = 'com.bloby.bot';
 const LAUNCHD_PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
 const LAUNCHD_LOG_DIR = path.join(os.homedir(), 'Library', 'Logs', 'bloby');
+const LAUNCHD_LOG = path.join(LAUNCHD_LOG_DIR, 'bloby.log');
+
+let _launchdDomain = null;
+function launchdDomain() {
+  if (_launchdDomain) return _launchdDomain;
+  const uid = process.getuid?.() ?? 501;
+  // gui/$UID exists when the user has a console (Aqua) session; user/$UID always
+  // exists. Probe once — explicit targets behave identically from GUI terminals,
+  // SSH, tmux, and detached children.
+  const probe = spawnSync('launchctl', ['print', `gui/${uid}`], { stdio: 'ignore' });
+  _launchdDomain = probe.status === 0 ? `gui/${uid}` : `user/${uid}`;
+  return _launchdDomain;
+}
 
-function isLaunchdInstalled() {
-  return fs.existsSync(LAUNCHD_PLIST_PATH);
+function launchctl(args) {
+  const res = spawnSync('launchctl', args, { encoding: 'utf-8' });
+  return { status: res.status ?? 1, stdout: res.stdout || '', stderr: res.stderr || '' };
 }
 
-function isLaunchdActive() {
-  try {
-    const out = execSync(`launchctl list ${LAUNCHD_LABEL} 2>/dev/null`, { encoding: 'utf-8' });
-    // launchctl list <label> succeeds if the job is loaded; check PID field
-    const pidLine = out.split('\n').find(l => l.includes('PID'));
-    if (pidLine) {
-      const pid = pidLine.split('=')[1]?.trim();
-      return pid && pid !== '0' && pid !== '-';
-    }
-    // Fallback: if the command succeeded, it's loaded. Check if the process is running.
-    const lines = out.trim().split('\n');
-    // First line of `launchctl list <label>` output: "PID\tStatus\tLabel" header or direct values
-    // The format is: { "PID" = <pid>; "Status" = <code>; ... }
-    return !out.includes('"PID" = 0;');
-  } catch {
-    return false;
-  }
+/** Job state via `launchctl print <domain>/<label>`. Exit 113 = not loaded.
+ *  Output is "not API" per the man page, so parse minimally and defensively.
+ *  loaded is three-state: true / false / 'unknown' (launchctl itself failed) —
+ *  callers must NOT treat 'unknown' as "safe to assume stopped" (log rotation
+ *  and bootout decisions depend on it). Probes both gui/ and user/ domains: a
+ *  job bootstrapped over SSH pre-login lands in user/$UID while a console
+ *  session resolves gui/$UID, and targeting the wrong one strands it. */
+function launchdJobIn(domain) {
+  const res = launchctl(['print', `${domain}/${LAUNCHD_LABEL}`]);
+  if (res.status === 113) return { loaded: false, pid: null, state: 'not-loaded', domain };
+  if (res.status !== 0) return { loaded: 'unknown', pid: null, state: `error-${res.status}`, domain };
+  const pidMatch = res.stdout.match(/^\s*pid = (\d+)\s*$/m);
+  const stateMatch = res.stdout.match(/^\s*state = (.+?)\s*$/m);
+  return {
+    loaded: true,
+    pid: pidMatch ? Number(pidMatch[1]) : null,
+    state: stateMatch ? stateMatch[1] : 'unknown',
+    domain,
+  };
+}
+
+function launchdJob() {
+  const uid = process.getuid?.() ?? 501;
+  const primary = launchdJobIn(launchdDomain());
+  if (primary.loaded === true) return primary;
+  const alt = launchdDomain() === `gui/${uid}` ? `user/${uid}` : `gui/${uid}`;
+  const secondary = launchdJobIn(alt);
+  if (secondary.loaded === true) return secondary;
+  return primary; // both not-loaded/unknown — report the preferred domain's view
 }
 
 function generateLaunchdPlist({ nodePath, dataDir }) {
@@ -222,9 +856,9 @@ function generateLaunchdPlist({ nodePath, dataDir }) {
   <key>ThrottleInterval</key>
   <integer>5</integer>
   <key>StandardOutPath</key>
-  <string>${LAUNCHD_LOG_DIR}/bloby.log</string>
+  <string>${LAUNCHD_LOG}</string>
   <key>StandardErrorPath</key>
-  <string>${LAUNCHD_LOG_DIR}/bloby.log</string>
+  <string>${LAUNCHD_LOG}</string>
   <key>ProcessType</key>
   <string>Standard</string>
 </dict>
@@ -232,10 +866,23 @@ function generateLaunchdPlist({ nodePath, dataDir }) {
 `;
 }
 
-// --- Platform-agnostic daemon helpers ---
+/** Rotate the launchd log when big. Only safe while the job is stopped — launchd
+ *  holds an O_APPEND fd to the old inode for the job's whole life, so renaming a
+ *  live file is exactly what produces "stale logs". Callers must guarantee the
+ *  job is not running. */
+function rotateLaunchdLogIfBig() {
+  try {
+    const st = fs.statSync(LAUNCHD_LOG);
+    if (st.size > 5 * 1024 * 1024) {
+      fs.renameSync(LAUNCHD_LOG, LAUNCHD_LOG + '.1');
+    }
+  } catch {}
+}
+
+// --- Platform-agnostic daemon facade ---
 
 function hasDaemonSupport() {
-  if (PLATFORM === 'darwin') return true; // launchd is always available on macOS
+  if (PLATFORM === 'darwin') return true;
   if (PLATFORM === 'linux') {
     try { execSync('systemctl --version', { stdio: 'ignore' }); return true; } catch { return false; }
   }
@@ -243,633 +890,889 @@ function hasDaemonSupport() {
 }
 
 function isDaemonInstalled() {
-  if (PLATFORM === 'darwin') return isLaunchdInstalled();
-  if (PLATFORM === 'linux') return isServiceInstalled();
+  if (PLATFORM === 'darwin') return fs.existsSync(LAUNCHD_PLIST_PATH);
+  if (PLATFORM === 'linux') return fs.existsSync(SERVICE_PATH);
   return false;
 }
 
-function isDaemonActive() {
-  if (PLATFORM === 'darwin') return isLaunchdActive();
-  if (PLATFORM === 'linux') return isServiceActive();
-  return false;
+/** Daemon-managed supervisor PID (launchd/systemd view), or null. */
+function daemonPid() {
+  if (PLATFORM === 'darwin') {
+    const job = launchdJob();
+    return job.loaded === true && job.pid && procAlive(job.pid) ? job.pid : null;
+  }
+  if (PLATFORM === 'linux') {
+    const show = systemdShow();
+    return show.activeState === 'active' && show.mainPid ? show.mainPid : null;
+  }
+  return null;
 }
 
-function killAndWait(child, timeout = 10_000) {
-  return new Promise((resolve) => {
-    child.removeAllListeners('exit');
-    child.on('exit', () => resolve());
-    child.kill('SIGTERM');
-    // Force kill after timeout if SIGTERM doesn't work
-    setTimeout(() => {
-      try { child.kill('SIGKILL'); } catch {}
-      setTimeout(resolve, 500);
-    }, timeout);
-  });
+function isDaemonActive() {
+  return daemonPid() !== null;
 }
 
-// ── UI helpers ──
+/** Write the service definition (idempotent; refreshes node path / data dir drift).
+ *  Returns { ok, error }. */
+function installServiceFiles({ spinner } = {}) {
+  const nodePath = process.env.BLOBY_NODE_PATH || process.execPath;
+  if (PLATFORM === 'darwin') {
+    const dataDir = ROOT; // repo in dev, ~/.bloby in production
+    fs.mkdirSync(path.dirname(LAUNCHD_PLIST_PATH), { recursive: true });
+    fs.writeFileSync(LAUNCHD_PLIST_PATH, generateLaunchdPlist({ nodePath, dataDir }));
+    fs.chmodSync(LAUNCHD_PLIST_PATH, 0o644); // launchd refuses group/world-writable plists (error 122)
+    return { ok: true };
+  }
+  if (PLATFORM === 'linux') {
+    const user = getRealUser();
+    const home = getRealHome();
+    const dataDir = path.join(home, '.bloby');
+    const unit = generateUnitFile({ user, home, nodePath, dataDir });
+    // Skip the privileged write when the installed unit is already identical —
+    // a plain `bloby start` on an installed system then needs no sudo at all
+    // beyond `systemctl start`.
+    let current = null;
+    try { current = fs.readFileSync(SERVICE_PATH, 'utf-8'); } catch {}
+    if (current !== unit) {
+      const tmp = path.join(os.tmpdir(), `bloby-unit-${process.pid}.service`);
+      fs.writeFileSync(tmp, unit);
+      const cp = runPrivileged(['cp', tmp, SERVICE_PATH], { spinner });
+      fs.rmSync(tmp, { force: true });
+      if (!cp.ok) return cp;
+      const reload = runPrivileged(['systemctl', 'daemon-reload'], { spinner });
+      if (!reload.ok) return reload;
+      const enable = runPrivileged(['systemctl', 'enable', SERVICE_NAME], { spinner });
+      if (!enable.ok) return enable;
+    }
+    return { ok: true };
+  }
+  return { ok: false, error: 'No daemon support on this platform.' };
+}
 
-const c = {
-  reset: '\x1b[0m',
-  dim: '\x1b[2m',
-  bold: '\x1b[1m',
-  green: '\x1b[32m',
-  cyan: '\x1b[36m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  white: '\x1b[97m',
-  blue: '\x1b[38;2;0;173;254m',
-  pink: '\x1b[38;2;1;88;251m',
-  g1: '\x1b[38;2;0;173;254m',
-  g2: '\x1b[38;2;0;159;254m',
-  g3: '\x1b[38;2;0;145;253m',
-  g4: '\x1b[38;2;1;131;253m',
-  g5: '\x1b[38;2;1;116;252m',
-  g6: '\x1b[38;2;1;102;251m',
-  g7: '\x1b[38;2;1;88;251m',
-};
+/** Start the daemon. Returns { ok, error }. Never throws. */
+function startDaemonService({ spinner } = {}) {
+  if (PLATFORM === 'darwin') {
+    const job = launchdJob();
+    if (job.loaded === true && job.pid && procAlive(job.pid)) return { ok: true };
+    if (job.loaded === false) rotateLaunchdLogIfBig(); // only certain-stopped — rotating a live log strands tails
+    if (job.loaded === true) {
+      // Loaded but not running (crash-throttled "spawn scheduled" etc.) — kickstart in ITS domain.
+      const res = launchctl(['kickstart', '-k', `${job.domain}/${LAUNCHD_LABEL}`]);
+      if (res.status === 0) return { ok: true };
+      return { ok: false, error: launchdError(res) };
+    }
+    let res = launchctl(['bootstrap', launchdDomain(), LAUNCHD_PLIST_PATH]);
+    if (res.status === 0 || res.status === 37) return { ok: true }; // 37 = already bootstrapped
+    if (res.status === 5) {
+      // 5 is a catch-all on some macOS builds (often an already-bootstrapped race) —
+      // re-query before assuming anything.
+      if (launchdJob().loaded === true) return { ok: true };
+      return { ok: false, error: launchdError(res) };
+    }
+    if (res.status === 119) {
+      // Disabled — likely toggled off in System Settings > Login Items (macOS 13+ BTM)
+      // or a stale disable override. Try to re-enable once, then retry.
+      launchctl(['enable', `user/${process.getuid?.() ?? 501}/${LAUNCHD_LABEL}`]);
+      res = launchctl(['bootstrap', launchdDomain(), LAUNCHD_PLIST_PATH]);
+      if (res.status === 0 || res.status === 37) return { ok: true };
+      return {
+        ok: false,
+        error: `Bloby is disabled in System Settings → General → Login Items & Extensions. Enable it there, then run ${c.blue}bloby start${c.reset} again.`,
+      };
+    }
+    return { ok: false, error: launchdError(res) };
+  }
+  if (PLATFORM === 'linux') {
+    return runPrivileged(['systemctl', 'start', SERVICE_NAME], { spinner });
+  }
+  return { ok: false, error: 'No daemon support on this platform.' };
+}
 
-const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const BAR_WIDTH = 30;
+/** Stop the daemon. Returns { ok, error }. Waits for the job to actually unload. */
+async function stopDaemonService({ spinner } = {}) {
+  if (PLATFORM === 'darwin') {
+    const job = launchdJob();
+    if (job.loaded === false) return { ok: true };
+    if (job.loaded === 'unknown') {
+      return { ok: false, error: `launchctl could not be queried (${job.state}) — not safe to assume Bloby is stopped.` };
+    }
+    const res = launchctl(['bootout', `${job.domain}/${LAUNCHD_LABEL}`]);
+    // 3 = no such process (already gone), 36 = termination in flight — poll below.
+    if (res.status !== 0 && res.status !== 3 && res.status !== 36) {
+      return { ok: false, error: launchdError(res) };
+    }
+    for (let i = 0; i < 40; i++) { // ≤20s for graceful supervisor shutdown
+      if (launchdJob().loaded === false) return { ok: true };
+      await new Promise(r => setTimeout(r, 500));
+    }
+    return { ok: false, error: 'Daemon did not stop within 20s.' };
+  }
+  if (PLATFORM === 'linux') {
+    const res = runPrivileged(['systemctl', 'stop', SERVICE_NAME], { spinner });
+    if (!res.ok) {
+      // "Unit not loaded/found" means there is nothing to stop — success, so the
+      // caller still runs the stray-process sweep (macOS behaves the same way).
+      const show = systemdShow();
+      if (show.loadState !== 'loaded' || /not loaded|could not be found|not-found/i.test(res.error || '')) {
+        return { ok: true };
+      }
+    }
+    return res;
+  }
+  return { ok: true };
+}
 
-function gradientChar(i, total) {
-  const t = total > 1 ? i / (total - 1) : 0;
-  const r = Math.round(0 + t * (1 - 0));
-  const g = Math.round(173 + t * (88 - 173));
-  const b = Math.round(254 + t * (251 - 254));
-  return `\x1b[38;2;${r};${g};${b}m`;
+function launchdError(res) {
+  const msg = (res.stderr || res.stdout).trim().split('\n').pop() || '';
+  let described = '';
+  try { described = execFileSync('launchctl', ['error', String(res.status)], { encoding: 'utf-8' }).trim(); } catch {}
+  return msg || described || `launchctl failed (exit ${res.status})`;
 }
 
-function progressBar(ratio, width = BAR_WIDTH) {
-  const filled = Math.round(ratio * width);
-  const empty = width - filled;
-  let bar = '';
-  for (let i = 0; i < filled; i++) bar += `${gradientChar(i, width)}█`;
-  bar += `${c.dim}${'░'.repeat(empty)}${c.reset}`;
-  return bar;
+/** SIGTERM (then SIGKILL) every supervisor process not owned by the daemon —
+ *  forecloses the duplicate-instance / stale-log class for good. */
+async function killStraySupervisors({ exceptPid = null } = {}) {
+  let strays = scanSupervisors().filter(p => p.pid !== exceptPid);
+  if (strays.length === 0) return 0;
+  for (const p of strays) { try { process.kill(p.pid, 'SIGTERM'); } catch {} }
+  for (let i = 0; i < 16; i++) { // ≤8s graceful
+    strays = strays.filter(p => procAlive(p.pid));
+    if (strays.length === 0) return 0;
+    await new Promise(r => setTimeout(r, 500));
+  }
+  for (const p of strays) { try { process.kill(p.pid, 'SIGKILL'); } catch {} }
+  return strays.length;
 }
 
-function link(url) {
-  return `\x1b]8;;${url}\x07${url}\x1b]8;;\x07`;
+// ── Readiness wait ──
+// Drives the Steps display through: server up (/api/health + pidfile) →
+// tunnel connected (config.tunnelUrl writeback / __TUNNEL_URL__) → connection
+// verified (__READY__, which the supervisor emits only AFTER registering the
+// tunnel with the relay — that's the moment the user's real URL actually works,
+// and it's the signal the old battle-tested stepper waited for).
+// Markers are read from the launchd log via byte offset on macOS (rotation only
+// ever happens while the job is stopped, so the offset is stable) and from
+// journalctl --since on Linux (best-effort: falls back to health+tunnel when
+// the journal isn't readable).
+
+function formatJournalTime(date) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${p(date.getMonth() + 1)}-${p(date.getDate())} ${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}`;
 }
 
-function chooseTunnelMode() {
-  return new Promise((resolve) => {
-    const options = [
-      {
-        label: 'Quick Tunnel',
-        mode: 'quick',
-        tag: 'Easy and Fast',
-        tagColor: c.green,
-        desc: [
-          'Random CloudFlare tunnel URL on every start/update',
-          `Optional: Use Bloby Relay Server and access your bot at ${c.reset}${c.pink}open.bloby.bot/YOURBOT${c.reset}${c.dim} (Free)`,
-          `Or use a premium handle like ${c.reset}${c.pink}bloby.bot/YOURBOT${c.reset}${c.dim} ($5 one-time fee)`,
-        ],
-      },
-      {
-        label: 'Named Tunnel',
-        mode: 'named',
-        tag: 'Advanced',
-        tagColor: c.yellow,
-        desc: [
-          'Persistent URL with your own domain',
-          'Requires a CloudFlare account + domain',
-          `Use a subdomain like ${c.reset}${c.white}bot.YOURDOMAIN.COM${c.reset}${c.dim} or the root domain`,
-        ],
-      },
-      {
-        label: 'Private Network',
-        mode: 'off',
-        tag: 'Secure',
-        tagColor: c.cyan,
-        desc: [
-          'No public URL — access via local network or VPN only',
-          `Use with ${c.reset}${c.white}Tailscale${c.reset}${c.dim}, WireGuard, or any private network`,
-          `Your bot stays invisible to the internet`,
-        ],
-      },
-    ];
-
-    let selected = 0;
-    let lineCount = 0;
+async function waitForReady({ sinceMs, oldTunnelUrl, tunnelMode, ui, logOffset = 0, timeoutMs = 150_000 }) {
+  const U = ui ?? { advance() {}, setNote() {}, update() {} };
+  const config = readConfig() || {};
+  const port = config.port || 7400;
+  const relayUrl = config.relay?.url || null;
+  const wantTunnel = tunnelMode !== 'off';
 
-    function writeLine(text = '') {
-      process.stdout.write(`\x1b[2K${text}\n`);
-      lineCount++;
+  let healthy = false;
+  let tunnelUrl = null;
+  let ready = false;        // __READY__ seen — relay registration verified
+  let verified = false;     // ready, or best-effort fallback when markers unavailable
+  let tunnelFailed = false;
+  let offset = logOffset;
+  let sawDaemonOutput = false;
+  let tunnelAt = 0;
+  let phase = 'server';     // server → tunnel → verify → done
+
+  const deadline = Date.now() + timeoutMs;
+  // If no tunnel URL appears at all within this window while healthy, stop
+  // holding the terminal (a slow tunnel is reported, not waited on forever).
+  const tunnelDeadline = Date.now() + (timeoutMs > 150_000 ? timeoutMs : Math.min(timeoutMs, 90_000));
+  const sinceDate = new Date(sinceMs - 2000);
+
+  const readNewDaemonOutput = () => {
+    if (PLATFORM === 'darwin') {
+      try {
+        const size = fs.statSync(LAUNCHD_LOG).size;
+        if (size < offset) offset = 0; // file replaced/truncated underneath us
+        if (size > offset) {
+          const fd = fs.openSync(LAUNCHD_LOG, 'r');
+          const buf = Buffer.alloc(size - offset);
+          fs.readSync(fd, buf, 0, buf.length, offset);
+          fs.closeSync(fd);
+          offset = size;
+          return buf.toString('utf-8');
+        }
+      } catch {}
+      return '';
     }
-
-    function render() {
-      // Move cursor up to overwrite previous render
-      if (lineCount > 0) {
-        process.stdout.write(`\x1b[${lineCount}A`);
+    if (PLATFORM === 'linux') {
+      try {
+        const r = spawnSync('journalctl', ['-u', SERVICE_NAME, '--since', formatJournalTime(sinceDate), '-o', 'cat', '-q', '--no-pager'], { encoding: 'utf-8' });
+        return r.stdout || '';
+      } catch { return ''; }
+    }
+    return '';
+  };
+
+  while (Date.now() < deadline) {
+    if (!healthy) {
+      const health = await fetchHealth(port, 2000);
+      if (health) {
+        healthy = true;
+        if (phase === 'server') {
+          U.advance();
+          phase = wantTunnel ? 'tunnel' : 'done';
+        }
       }
-      lineCount = 0;
-
-      writeLine(`  ${c.bold}${c.white}How do you want to connect your bot?${c.reset}`);
-      writeLine();
-
-      for (let i = 0; i < options.length; i++) {
-        const opt = options[i];
-        const isSelected = i === selected;
-        const bullet = isSelected ? `${c.pink}❯` : `${c.dim} `;
-        const label = isSelected ? `${c.bold}${c.white}${opt.label}` : `${c.dim}${opt.label}`;
-        const tag = `${opt.tagColor}[${opt.tag}]${c.reset}`;
+    }
 
-        writeLine(`  ${bullet} ${label}${c.reset}  ${tag}`);
-        for (const line of opt.desc) {
-          writeLine(`      ${c.dim}${line}${c.reset}`);
+    const text = readNewDaemonOutput();
+    if (text) sawDaemonOutput = true;
+    if (text.includes('__TUNNEL_FAILED__')) tunnelFailed = true;
+    if (text.includes('__READY__')) { ready = true; verified = true; }
+    if (wantTunnel && !tunnelUrl) {
+      const m = text.match(/__TUNNEL_URL__=(\S+)/);
+      if (m) tunnelUrl = m[1];
+      if (!tunnelUrl) {
+        const cfg = readConfig();
+        // Named tunnels keep a stable URL, so "changed since last run" never
+        // fires — accept the supervisor's writeback once it is healthy.
+        if (cfg?.tunnelUrl && (cfg.tunnelUrl !== oldTunnelUrl || (tunnelMode === 'named' && healthy))) {
+          tunnelUrl = cfg.tunnelUrl;
         }
-        if (i < options.length - 1) writeLine();
       }
     }
 
-    process.stdout.write('\x1b[?25l'); // Hide cursor
-    render();
-
-    // Enable raw mode for arrow key input
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding('utf-8');
+    if (phase === 'tunnel' && tunnelUrl) {
+      U.advance();
+      phase = 'verify';
+      tunnelAt = Date.now();
+      if (relayUrl) {
+        U.setNote([
+          `  ${c.dim}Waiting for ${c.reset}${c.white}${relayUrl.replace('https://', '')}${c.reset}${c.dim} to become reachable (can take up to 2 min)${c.reset}`,
+          `  ${c.dim}In the meanwhile you can access:${c.reset} ${c.blue}${link(tunnelUrl)}${c.reset}`,
+        ]);
+      } else if (tunnelMode === 'named') {
+        U.setNote([`  ${c.dim}Verifying ${c.reset}${c.white}${tunnelUrl.replace('https://', '')}${c.reset}${c.dim}...${c.reset}`]);
+      }
+    }
 
-    const onKey = (key) => {
-      if (key === '\x1b[A' || key === 'k') { // Up
-        selected = (selected - 1 + options.length) % options.length;
-        render();
-      } else if (key === '\x1b[B' || key === 'j') { // Down
-        selected = (selected + 1) % options.length;
-        render();
-      } else if (key === '\r' || key === '\n') { // Enter
-        process.stdout.write('\x1b[?25h'); // Show cursor
-        process.stdin.setRawMode(false);
-        process.stdin.pause();
-        process.stdin.removeListener('data', onKey);
-        resolve(options[selected].mode);
-      } else if (key === '\x03') { // Ctrl+C
-        process.stdout.write('\x1b[?25h\n');
-        process.exit(0);
+    if (phase === 'verify') {
+      if (ready) {
+        U.setNote([]);
+        U.advance();
+        phase = 'done';
+      } else if (PLATFORM === 'linux' && !sawDaemonOutput && healthy && tunnelUrl && Date.now() - tunnelAt > 10_000) {
+        // Journal not readable for this user — can't see __READY__. Healthy +
+        // tunnel up is the best signal available (matches the old Linux path).
+        verified = true;
+        U.setNote([]);
+        U.advance();
+        phase = 'done';
       }
-    };
+    }
 
-    process.stdin.on('data', onKey);
-  });
-}
+    if (phase === 'done') break;
+    if (healthy && tunnelFailed) break;
+    if (healthy && wantTunnel && !tunnelUrl && Date.now() > tunnelDeadline) break;
+    await new Promise(r => setTimeout(r, 1000));
+  }
 
-async function runNamedTunnelSetup() {
-  // Ensure cloudflared is installed
-  console.log(`\n  ${c.blue}⠋${c.reset}  Checking cloudflared...`);
-  await installCloudflared();
-  console.log(`  ${c.blue}✔${c.reset}  cloudflared ready\n`);
+  // Re-read for any relay URL the supervisor registered during startup.
+  const cfg = readConfig() || {};
+  return {
+    healthy,
+    tunnelUrl,
+    relayUrl: cfg.relay?.url || relayUrl,
+    ready: verified,
+    tunnelFailed,
+    runtime: readRuntime(),
+    sinceMs,
+  };
+}
 
-  // Login to Cloudflare
-  console.log(`  ${c.bold}${c.white}Step 1:${c.reset} Log in to Cloudflare\n`);
-  console.log(`  ${c.dim}This will open a browser window. Authorize the domain you want to use.${c.reset}\n`);
-  try {
-    spawnSync('cloudflared', ['tunnel', 'login'], { stdio: 'inherit' });
-  } catch {
-    if (fs.existsSync(CF_PATH)) {
-      spawnSync(CF_PATH, ['tunnel', 'login'], { stdio: 'inherit' });
-    } else {
-      console.log(`\n  ${c.red}✗${c.reset}  cloudflared login failed.\n`);
-      process.exit(1);
+function getNetworkUrls(port) {
+  const urls = [];
+  const nets = os.networkInterfaces();
+  for (const addrs of Object.values(nets)) {
+    for (const addr of addrs || []) {
+      if (addr.family !== 'IPv4' || addr.internal) continue;
+      const ip = addr.address;
+      // Tailscale uses 100.64.0.0/10 (CGNAT range)
+      if (ip.startsWith('100.')) {
+        urls.push({ type: 'tailscale', url: `http://${ip}:${port}` });
+      } else if (ip.startsWith('192.168.') || ip.startsWith('10.') || ip.match(/^172\.(1[6-9]|2\d|3[01])\./)) {
+        urls.push({ type: 'lan', url: `http://${ip}:${port}` });
+      }
     }
   }
-  console.log('');
-
-  // Ask for tunnel name
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const askQ = (q) => new Promise((r) => rl.question(q, (a) => r(a.trim())));
-
-  const tunnelName = (await askQ(`  ${c.bold}Tunnel name${c.reset} ${c.dim}(default: bloby)${c.reset}: `)) || 'bloby';
+  return urls;
+}
 
-  // Create tunnel
-  console.log(`\n  ${c.blue}⠋${c.reset}  Creating tunnel "${tunnelName}"...`);
-  let createOutput;
-  try {
-    createOutput = execSync(`cloudflared tunnel create ${tunnelName}`, { encoding: 'utf-8' });
-  } catch {
-    try {
-      createOutput = execSync(`${CF_PATH} tunnel create ${tunnelName}`, { encoding: 'utf-8' });
-    } catch {
-      console.log(`\n  ${c.red}✗${c.reset}  Failed to create tunnel. It may already exist.`);
-      console.log(`  ${c.dim}Try: cloudflared tunnel list${c.reset}\n`);
-      process.exit(1);
+function printReadyBlock({ healthy, ready, tunnelFailed, tunnelUrl, relayUrl, port, tunnelMode }) {
+  // The user's real URL is the relay handle (or named domain) — nobody types the
+  // random trycloudflare address. Lead with it, inside the result box.
+  const primary = relayUrl
+    || (tunnelMode === 'named' && tunnelUrl ? tunnelUrl : null)
+    || (tunnelMode === 'off' ? `http://localhost:${port}` : tunnelUrl);
+
+  if (healthy) {
+    const boxLines = [` ${c.pink}${c.bold}✔  Bloby is running${c.reset}`];
+    if (primary) {
+      boxLines.push('');
+      boxLines.push(`    ${c.pink}${c.bold}${link(primary)}${c.reset}`);
     }
+    resultBox(boxLines);
+  } else {
+    resultBox([` ${GLYPH.warn}  ${c.bold}Bloby is starting${c.reset} ${c.dim}— not healthy yet. Check ${c.reset}${c.blue}bloby status${c.reset}${c.dim} in a moment.${c.reset}`]);
   }
 
-  const uuidMatch = createOutput.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
-  if (!uuidMatch) {
-    console.log(`\n  ${c.red}✗${c.reset}  Could not parse tunnel UUID from output.`);
-    console.log(`  ${c.dim}${createOutput}${c.reset}\n`);
-    process.exit(1);
+  console.log('');
+  console.log(`  ${c.dim}${'Local'.padEnd(9)}${c.reset}${c.blue}${link(`http://localhost:${port}`)}${c.reset}`);
+  if (tunnelMode === 'off') {
+    for (const u of getNetworkUrls(port)) {
+      console.log(`  ${c.dim}${(u.type === 'tailscale' ? 'Tailscale' : 'LAN').padEnd(9)}${c.reset}${c.cyan}${link(u.url)}${c.reset}`);
+    }
+  }
+  if (tunnelUrl) {
+    console.log(`  ${c.dim}${'Tunnel'.padEnd(9)}${c.reset}${c.blue}${link(tunnelUrl)}${c.reset}`);
+  }
+  if (relayUrl && relayUrl !== primary) {
+    console.log(`  ${c.dim}${'Relay'.padEnd(9)}${c.reset}${c.pink}${link(relayUrl)}${c.reset}`);
   }
-  const tunnelUuid = uuidMatch[1];
-  console.log(`  ${c.blue}✔${c.reset}  Tunnel created: ${c.dim}${tunnelUuid}${c.reset}\n`);
-
-  // Ask for domain
-  const domain = await askQ(`  ${c.bold}Your domain${c.reset} ${c.dim}(e.g. bot.mydomain.com)${c.reset}: `);
-  rl.close();
 
-  if (!domain) {
-    console.log(`\n  ${c.red}✗${c.reset}  Domain is required for named tunnels.\n`);
-    process.exit(1);
+  if (tunnelFailed && tunnelMode !== 'off') {
+    console.log(`\n  ${GLYPH.warn}  ${c.bold}Tunnel failed to connect.${c.reset}`);
+    console.log(`     ${c.dim}CloudFlare quick tunnels are rate-limited — this usually resolves itself in a few minutes.${c.reset}`);
+    console.log(`     ${c.dim}Your dashboard still works locally (above). Retry with ${c.reset}${c.blue}bloby restart${c.reset}${c.dim}.${c.reset}`);
+  } else if (healthy && tunnelMode !== 'off' && !tunnelUrl) {
+    console.log(`\n  ${GLYPH.warn}  ${c.dim}Tunnel still connecting — check ${c.reset}${c.blue}bloby status${c.reset}${c.dim} shortly.${c.reset}`);
+  } else if (healthy && tunnelMode !== 'off' && tunnelUrl && !ready) {
+    console.log(`\n  ${GLYPH.warn}  ${c.dim}Could not confirm the relay link yet — check ${c.reset}${c.blue}bloby status${c.reset}${c.dim} in a minute.${c.reset}`);
   }
+}
 
-  // Generate cloudflared config
-  const config = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : {};
-  const port = config.port || 7400;
-  const cfHome = path.join(os.homedir(), '.cloudflared');
-  const cfConfigPath = path.join(DATA_DIR, 'cloudflared-config.yml');
+// ── Cloudflared install (shared by init/start/tunnel) ──
 
-  const yamlContent = `tunnel: ${tunnelUuid}
-credentials-file: ${path.join(cfHome, `${tunnelUuid}.json`)}
-ingress:
-  - service: http://localhost:${port}
-`;
-  fs.mkdirSync(DATA_DIR, { recursive: true });
-  fs.writeFileSync(cfConfigPath, yamlContent);
-  console.log(`\n  ${c.blue}✔${c.reset}  Config written to ${c.dim}${cfConfigPath}${c.reset}`);
-
-  // Print DNS instructions
-  console.log(`\n  ${c.dim}─────────────────────────────────${c.reset}\n`);
-  console.log(`  ${c.bold}${c.white}Tunnel created!${c.reset}`);
-  console.log(`  ${c.white}Add a CNAME record pointing to:${c.reset}\n`);
-  console.log(`  ${c.pink}${c.bold}${tunnelUuid}.cfargotunnel.com${c.reset}\n`);
-  console.log(`  ${c.dim}Or run: cloudflared tunnel route dns ${tunnelName} ${domain}${c.reset}\n`);
+const MIN_CF_SIZE = 10 * 1024 * 1024; // 10 MB — valid cloudflared is ~30-50 MB
 
-  return { tunnelName, domain, cfConfigPath };
+function hasCloudflared() {
+  const which = PLATFORM === 'win32' ? 'where cloudflared' : 'which cloudflared';
+  try { execSync(which, { stdio: 'ignore' }); return true; } catch {}
+  const cfExe = PLATFORM === 'win32' ? CF_PATH + '.exe' : CF_PATH;
+  if (!fs.existsSync(cfExe)) return false;
+  if (fs.statSync(cfExe).size < MIN_CF_SIZE) {
+    fs.unlinkSync(cfExe);
+    return false;
+  }
+  return true;
 }
 
-class Stepper {
-  constructor(steps) {
-    this.steps = steps;
-    this.current = 0;
-    this.frame = 0;
-    this.interval = null;
-    this.done = false;
-    this.infoLines = [];   // extra lines shown below the progress bar
-    this._totalLines = 0;  // total lines rendered last frame (for cursor rewind)
-  }
+async function installCloudflared() {
+  if (hasCloudflared()) return;
+  fs.mkdirSync(BIN_DIR, { recursive: true });
 
-  start() {
-    console.log('');
-    // Hide cursor and suppress user input during animation
-    process.stdout.write('\x1b[?25l');
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-      process.stdin.resume();
-      this._stdinHandler = (data) => {
-        // Allow Ctrl+C
-        if (data[0] === 0x03) {
-          this._restoreTerminal();
-          process.exit(0);
-        }
-        // Discard everything else
-      };
-      process.stdin.on('data', this._stdinHandler);
+  // os.arch() returns Node's arch, not the OS. Use PROCESSOR_ARCHITECTURE on Windows for real OS arch.
+  const arch = PLATFORM === 'win32'
+    ? (process.env.PROCESSOR_ARCHITECTURE || os.arch()).toLowerCase()
+    : os.arch();
+  let url;
+  if (PLATFORM === 'win32') {
+    url = arch.includes('arm')
+      ? 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-arm64.exe'
+      : 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe';
+  } else if (PLATFORM === 'darwin') {
+    url = arch === 'arm64'
+      ? 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz'
+      : 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64.tgz';
+  } else if (PLATFORM === 'linux') {
+    if (arch === 'arm64' || arch === 'aarch64') {
+      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64';
+    } else if (arch === 'arm' || arch === 'armv7l') {
+      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm';
+    } else {
+      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64';
     }
-    this.interval = setInterval(() => {
-      this.frame = (this.frame + 1) % SPINNER.length;
-      this.render();
-    }, 80);
-    this.render();
+  } else {
+    throw new Error(`Unsupported platform: ${PLATFORM}/${arch}`);
   }
 
-  _restoreTerminal() {
-    process.stdout.write('\x1b[?25h');
-    if (process.stdin.isTTY) {
-      if (this._stdinHandler) {
-        process.stdin.removeListener('data', this._stdinHandler);
-        this._stdinHandler = null;
-      }
-      try { process.stdin.setRawMode(false); } catch {}
-      process.stdin.pause();
-    }
+  // Bounded: an unresponsive download must never hang a headless restart
+  // (the supervisor's detached relaunch runs through this path).
+  const DL_TIMEOUT = 180_000;
+  if (PLATFORM === 'win32') {
+    execSync(`curl.exe -fsSL -o "${CF_PATH}.exe" "${url}"`, { stdio: 'ignore', timeout: DL_TIMEOUT });
+  } else if (url.endsWith('.tgz')) {
+    execSync(`curl -fsSL "${url}" | tar xz -C "${BIN_DIR}"`, { stdio: 'ignore', timeout: DL_TIMEOUT });
+  } else {
+    execSync(`curl -fsSL -o "${CF_PATH}" "${url}"`, { stdio: 'ignore', timeout: DL_TIMEOUT });
+    fs.chmodSync(CF_PATH, 0o755);
   }
+}
 
-  setInfo(lines) {
-    this.infoLines = lines || [];
-    this.render();
-  }
+async function ensureCloudflared(spinner) {
+  if (hasCloudflared()) return;
+  if (spinner) spinner.update('Installing cloudflared...');
+  await installCloudflared();
+}
 
-  render() {
-    if (this.done) return;
+// ── Foreground boot (debug / no-daemon platforms / hosted containers) ──
+// Parses the supervisor's stdout protocol markers. Keep regexes in sync with the
+// emitters in supervisor/index.ts + supervisor/vite-dev.ts.
 
-    if (this._totalLines > 0) {
-      process.stdout.write(`\x1b[${this._totalLines}A`);
-    }
+function bootServer({ onTunnelUp, onReady } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      ['--import', 'tsx/esm', path.join(ROOT, 'supervisor/index.ts')],
+      { cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } },
+    );
 
-    const ratio = this.current / this.steps.length;
+    let tunnelUrl = null;
+    let relayUrl = null;
+    let resolved = false;
+    let stderrBuf = '';
+    let tunnelFired = false;
+    let tunnelFailed = false;
 
-    for (let i = 0; i < this.steps.length; i++) {
-      if (i < this.current) {
-        console.log(`  ${c.blue}✔${c.reset}  ${this.steps[i]}`);
-      } else if (i === this.current) {
-        console.log(`  ${c.pink}${SPINNER[this.frame]}${c.reset}  ${this.steps[i]}${c.dim}...${c.reset}`);
-      } else {
-        console.log(`  ${c.dim}○  ${this.steps[i]}${c.reset}`);
-      }
-    }
+    let viteWarmResolve;
+    const viteWarm = new Promise((r) => { viteWarmResolve = r; });
 
-    console.log(`\n  ${progressBar(ratio)}  ${c.dim}${Math.round(ratio * 100)}%${c.reset}`);
+    const doResolve = () => {
+      if (resolved) return;
+      resolved = true;
+      if (!tunnelFired && onTunnelUp) onTunnelUp();
+      if (onReady) onReady();
+      const config = readConfig() || {};
+      resolve({
+        child,
+        tunnelUrl: tunnelUrl || `http://localhost:${config.port || 7400}`,
+        relayUrl: relayUrl || config.relay?.url || null,
+        tunnelFailed,
+        viteWarm,
+      });
+    };
 
-    // steps + blank + progress = steps.length + 2, plus info lines
-    let lineCount = this.steps.length + 2;
+    const handleData = (data) => {
+      const text = data.toString();
 
-    if (this.infoLines.length) {
-      console.log('');
-      for (const line of this.infoLines) {
-        console.log(line);
+      const tunnelMatch = text.match(/__TUNNEL_URL__=(\S+)/);
+      if (tunnelMatch) {
+        tunnelUrl = tunnelMatch[1];
+        if (!tunnelFired && onTunnelUp) { tunnelFired = true; onTunnelUp(tunnelUrl); }
       }
-      lineCount += 1 + this.infoLines.length;
-    }
 
-    // Clear leftover lines when content shrinks (e.g. info lines removed)
-    if (lineCount < this._totalLines) {
-      const extra = this._totalLines - lineCount;
-      for (let i = 0; i < extra; i++) {
-        process.stdout.write('\x1b[2K\n');
-      }
-      process.stdout.write(`\x1b[${extra}A`);
-    }
+      const relayMatch = text.match(/__RELAY_URL__=(\S+)/);
+      if (relayMatch) relayUrl = relayMatch[1];
 
-    this._totalLines = lineCount;
-  }
+      if (text.includes('__VITE_WARM__')) viteWarmResolve();
+      if (text.includes('__READY__')) { doResolve(); return; }
+      if (text.includes('__TUNNEL_FAILED__')) { tunnelFailed = true; doResolve(); }
+    };
 
-  advance() {
-    this.current++;
-    this.render();
-  }
+    // Safety-net timeout: resolve after 45s even if __READY__ never arrives
+    setTimeout(doResolve, 45_000);
 
-  finish() {
-    this.done = true;
-    if (this.interval) clearInterval(this.interval);
-    this._restoreTerminal();
+    child.stdout.on('data', handleData);
+    child.stderr.on('data', (data) => {
+      stderrBuf += data.toString();
+      handleData(data);
+    });
 
-    if (this._totalLines > 0) {
-      process.stdout.write(`\x1b[${this._totalLines}A`);
-    }
-    // Clear all previously rendered lines
-    for (let i = 0; i < this._totalLines; i++) {
-      process.stdout.write('\x1b[2K\n');
-    }
-    process.stdout.write(`\x1b[${this._totalLines}A`);
+    // The global SIGINT/SIGTERM handlers (registered first, so they run first
+    // and exit immediately) kill foregroundChild — per-call listeners here
+    // would never run.
+    foregroundChild = child;
 
-    for (const step of this.steps) {
-      console.log(`  ${c.blue}✔${c.reset}  ${step}`);
-    }
-    console.log(`\n  ${progressBar(1)}  ${c.pink}Done${c.reset}`);
-  }
+    child.on('exit', (code) => {
+      if (!resolved) {
+        reject(new Error(stderrBuf.trim() || `Server exited with code ${code}`));
+      } else {
+        process.exit(code ?? 1);
+      }
+    });
+  });
 }
 
-function banner() {
-  console.log(`
-  ${c.g1}${c.bold}                              █▄         ${c.reset}
-  ${c.g2}${c.bold}    ▄              ▄          ██         ${c.reset}
-  ${c.g3}${c.bold}    ███▄███▄ ▄███▄ ████▄████▄ ████▄ ██ ██${c.reset}
-  ${c.g4}${c.bold}    ██ ██ ██ ██ ██ ██   ██ ██ ██ ██ ██▄██${c.reset}
-  ${c.g5}${c.bold}   ▄██ ██ ▀█▄▀███▀▄█▀  ▄████▀▄██ ██▄▄▀██▀${c.reset}
-  ${c.g6}${c.bold}                        ██            ██ ${c.reset}
-  ${c.g7}${c.bold}                        ▀           ▀▀▀  ${c.reset}
-  ${c.dim}v${pkg.version} · Self-hosted AI agent${c.reset}`);
+async function runForeground() {
+  const config = readConfig() || {};
+  const tunnelMode = tunnelModeOf(config);
+  const s = new Spinner().start('Starting Bloby (foreground)...');
+  let result;
+  try {
+    if (tunnelMode !== 'off' && tunnelMode !== 'named') await ensureCloudflared(s);
+    result = await bootServer({
+      onTunnelUp: (url) => { if (url) s.update(`Tunnel up at ${url}`); },
+    });
+  } catch (err) {
+    s.fail(`Server failed to start: ${err.message}`);
+    process.exit(1);
+  }
+  s.stopRaw();
+  printReadyBlock({
+    healthy: true,
+    ready: !result.tunnelFailed,
+    tunnelFailed: result.tunnelFailed,
+    tunnelUrl: result.tunnelFailed ? null : result.tunnelUrl,
+    relayUrl: result.relayUrl,
+    port: config.port || 7400,
+    tunnelMode,
+  });
+  console.log(`\n  ${c.dim}Running in the foreground — press Ctrl+C to stop${c.reset}\n`);
+  result.child.stdout.on('data', (d) => process.stdout.write(`  ${c.dim}${d.toString().trim()}${c.reset}\n`));
+  result.child.stderr.on('data', (d) => {
+    const line = d.toString().trim();
+    if (!line || line.includes('AssignProcessToJobObject')) return;
+    process.stderr.write(`  ${c.dim}${line}${c.reset}\n`);
+  });
+  // Stays attached; bootServer's child exit handler ends the process.
 }
 
-function getNetworkUrls(port) {
-  const urls = [];
-  const nets = os.networkInterfaces();
-  for (const [name, addrs] of Object.entries(nets)) {
-    for (const addr of addrs) {
-      if (addr.family !== 'IPv4' || addr.internal) continue;
-      const ip = addr.address;
-      // Tailscale uses 100.64.0.0/10 (CGNAT range)
-      if (ip.startsWith('100.')) {
-        urls.push({ type: 'tailscale', url: `http://${ip}:${port}`, ip });
-      } else if (ip.startsWith('192.168.') || ip.startsWith('10.') || ip.match(/^172\.(1[6-9]|2\d|3[01])\./)) {
-        urls.push({ type: 'lan', url: `http://${ip}:${port}`, ip });
-      }
-    }
-  }
-  return urls;
+// ── start / stop / restart cores (shared so restart ≡ stop + start, exactly) ──
+
+/** Step titles for a daemonized start — callers prepend their own (e.g. "Stopping Bloby"). */
+function startStepTitles(config) {
+  const wantTunnel = tunnelModeOf(config) !== 'off';
+  return ['Preparing', 'Starting server', ...(wantTunnel ? ['Connecting tunnel', 'Verifying connection'] : [])];
 }
 
-function privateNetworkMessage(port) {
-  const urls = getNetworkUrls(port);
-  const tailscale = urls.find(u => u.type === 'tailscale');
-  const lan = urls.find(u => u.type === 'lan');
+/** Runs the start sequence against a Steps ui positioned ON the "Preparing" step.
+ *  Advances through Preparing → Starting server → Connecting tunnel → Verifying
+ *  connection as the real signals arrive. */
+async function startCore({ ui, timeoutMs }) {
+  const config = readConfig() || {};
+  const tunnelMode = tunnelModeOf(config);
+  const wantTunnel = tunnelMode !== 'off';
 
-  console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
+  if (wantTunnel && tunnelMode !== 'named') await ensureCloudflared(ui);
 
-  ${c.bold}${c.white}Open your dashboard to finish setup:${c.reset}
-`);
+  const installed = installServiceFiles({ spinner: ui });
+  if (!installed.ok) return { ok: false, error: installed.error };
 
-  if (tailscale) {
-    console.log(`  ${c.cyan}${c.bold}${link(tailscale.url)}${c.reset}  ${c.dim}(Tailscale)${c.reset}`);
-  }
-  if (lan) {
-    console.log(`  ${c.blue}${c.bold}${link(lan.url)}${c.reset}  ${c.dim}(Local network)${c.reset}`);
+  // Marker baseline: rotate (only safe while certain-stopped) BEFORE capturing
+  // the byte offset, so __READY__ scanning starts exactly at this boot.
+  let logOffset = 0;
+  if (PLATFORM === 'darwin') {
+    if (launchdJob().loaded === false) rotateLaunchdLogIfBig();
+    try { logOffset = fs.statSync(LAUNCHD_LOG).size; } catch {}
   }
-  console.log(`  ${c.dim}${link(`http://localhost:${port}`)}${c.reset}  ${c.dim}(This machine)${c.reset}`);
+  const sinceMs = Date.now();
+  const oldTunnelUrl = config.tunnelUrl || null;
+  ui.update('');
 
-  if (!tailscale && !lan) {
-    console.log(`
-  ${c.dim}Tip: Install Tailscale to access from other devices:${c.reset}
-  ${c.dim}https://tailscale.com/download${c.reset}`);
-  }
+  const started = startDaemonService({ spinner: ui });
+  if (!started.ok) return { ok: false, error: started.error };
+  ui.advance(); // Preparing → Starting server
 
-  if (hasDaemonSupport()) {
-    console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
-
-  ${c.bold}${c.white}Commands:${c.reset}
-  ${c.dim}Status${c.reset}    ${c.pink}bloby status${c.reset}
-  ${c.dim}Logs${c.reset}      ${c.pink}bloby logs${c.reset}
-  ${c.dim}Stop${c.reset}      ${c.pink}bloby stop${c.reset}
-  ${c.dim}Restart${c.reset}   ${c.pink}bloby daemon restart${c.reset}
-  ${c.dim}Update${c.reset}    ${c.pink}bloby update${c.reset}
-  `);
-  } else {
-    console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
+  const ready = await waitForReady({ sinceMs, oldTunnelUrl, tunnelMode, ui, logOffset, ...(timeoutMs ? { timeoutMs } : {}) });
+  return { ok: true, ...ready, port: config.port || 7400, tunnelMode };
+}
 
-  ${c.bold}${c.white}Commands:${c.reset}
-  ${c.dim}Status${c.reset}    ${c.pink}bloby status${c.reset}
-  ${c.dim}Update${c.reset}    ${c.pink}bloby update${c.reset}
+async function stopCore({ spinner }) {
+  const stopped = await stopDaemonService({ spinner });
+  if (!stopped.ok) return stopped;
+  await killStraySupervisors();
+  return { ok: true };
+}
 
-  ${c.dim}Press Ctrl+C to stop${c.reset}
-  `);
+function describeRunning(config) {
+  const runtime = readRuntime();
+  const dPid = daemonPid();
+  if (config?.relay?.url) {
+    console.log(`  ${c.dim}${'URL'.padEnd(9)}${c.reset}${c.pink}${link(config.relay.url)}${c.reset}`);
+  } else if (config?.tunnelUrl) {
+    console.log(`  ${c.dim}${'URL'.padEnd(9)}${c.reset}${c.blue}${link(config.tunnelUrl)}${c.reset}`);
+  }
+  if (runtime || dPid) {
+    const pid = runtime?.pid || dPid;
+    const up = runtime?.startedAt ? ` · up ${formatUptime(Date.now() - runtime.startedAt)}` : '';
+    console.log(`  ${c.dim}${'PID'.padEnd(9)}${pid}${up}${c.reset}`);
   }
 }
 
-function tunnelFailedMessage(localUrl) {
-  console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
+// ── Commands ──
 
-  ${c.yellow}⚠${c.reset}  ${c.bold}${c.white}Tunnel failed to connect${c.reset}
+async function cmdStart() {
+  if (!fs.existsSync(CONFIG_PATH)) return cmdInit();
+  banner();
 
-  ${c.dim}CloudFlare quick tunnels are rate-limited.${c.reset}
-  ${c.dim}This usually resolves itself after a few minutes.${c.reset}
+  const config = readConfig();
+  const runtime = readRuntime();
+  const dPid = hasDaemonSupport() ? daemonPid() : null;
 
-  ${c.bold}${c.white}Your dashboard is available locally:${c.reset}
+  if (!hasDaemonSupport() || FOREGROUND) {
+    // Same already-running guard as the daemon path — otherwise a second
+    // foreground boot just dies on the occupied port with EADDRINUSE noise.
+    const live = runtime?.pid || dPid || scanSupervisors()[0]?.pid;
+    if (live) {
+      console.log(`\n  ${GLYPH.warn}  Bloby is already running ${c.dim}(PID ${live})${c.reset}. Stop it first: ${c.blue}bloby stop${c.reset}\n`);
+      process.exit(1);
+    }
+    if (!FOREGROUND) {
+      console.log(`\n  ${GLYPH.warn}  No service manager on this platform — running in the foreground.\n`);
+    }
+    return runForeground();
+  }
 
-  ${c.blue}${c.bold}${link(localUrl)}${c.reset}
-  ${c.dim}(cmd+click or ctrl+click to open)${c.reset}
+  if (dPid || runtime) {
+    if (dPid) {
+      resultBox([` ${c.blue}●${c.reset}  ${c.bold}Bloby is already running${c.reset}`]);
+      console.log(`\n  ${c.dim}Use ${c.reset}${c.blue}bloby restart${c.reset}${c.dim} if you want to restart it.${c.reset}\n`);
+      describeRunning(config);
+    } else {
+      console.log(`\n  ${GLYPH.warn}  Bloby is already running ${c.dim}(PID ${runtime.pid}, outside the daemon — a foreground or dev instance)${c.reset}.`);
+      console.log(`     Use ${c.blue}bloby restart${c.reset} to consolidate it under the background service.\n`);
+    }
+    commandsFooter();
+    return;
+  }
 
-  ${c.bold}${c.white}To retry the tunnel:${c.reset}
-  ${c.pink}bloby start${c.reset}
+  // Belt and suspenders: a supervisor that predates the pidfile won't have
+  // written supervisor.json — catch it with a process scan.
+  const strays = scanSupervisors();
+  if (strays.length > 0) {
+    console.log(`\n  ${GLYPH.warn}  Bloby is already running ${c.dim}(PID ${strays[0].pid}, outside the daemon)${c.reset}.`);
+    console.log(`     Use ${c.blue}bloby restart${c.reset} to consolidate it under the background service.\n`);
+    commandsFooter();
+    return;
+  }
 
-  ${c.bold}${c.white}For a persistent tunnel, use a named tunnel:${c.reset}
-  ${c.pink}bloby tunnel setup${c.reset}
-`);
+  const steps = new Steps(startStepTitles(config)).start();
+  const result = await startCore({ ui: steps });
+  if (!result.ok) {
+    steps.fail(`Failed to start: ${result.error}`);
+    console.log(`     ${c.dim}Check ${c.reset}${c.blue}bloby logs${c.reset}${c.dim} for details.${c.reset}`);
+    commandsFooter();
+    process.exit(1);
+  }
+  if (result.healthy && !result.tunnelFailed && (result.tunnelMode === 'off' || result.ready)) steps.finish();
+  else steps.fail();
+  printReadyBlock(result);
+  commandsFooter();
 }
 
-function finalMessage(tunnelUrl, relayUrl) {
-  console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
+async function cmdStop() {
+  banner();
+  if (!hasDaemonSupport()) {
+    console.log(`\n  ${GLYPH.warn}  No service manager on this platform — stop the foreground process with Ctrl+C.\n`);
+    process.exit(1);
+  }
 
-  ${c.bold}${c.white}Open your dashboard to finish setup:${c.reset}
+  // "Alive" includes a loaded-but-currently-dead service: during a crash loop
+  // the pid is dead between respawns, but launchd/systemd will resurrect it —
+  // stop must still boot the job out.
+  const jobLoaded = PLATFORM === 'darwin'
+    ? launchdJob().loaded !== false
+    : PLATFORM === 'linux' && ['active', 'activating'].includes(systemdShow().activeState);
+  const anythingAlive = jobLoaded || isDaemonActive() || readRuntime() || scanSupervisors().length > 0;
+  if (!anythingAlive) {
+    console.log(`\n  ${c.dim}●  Bloby is not running.${c.reset}`);
+    commandsFooter();
+    return;
+  }
+
+  console.log('');
+  const s = new Spinner().start('Stopping Bloby...');
+  const result = await stopCore({ spinner: s });
+  if (!result.ok) {
+    s.fail(`Failed to stop: ${result.error}`);
+    commandsFooter();
+    process.exit(1);
+  }
+  s.stopRaw();
+  resultBox([` ${c.bold}✔  Bloby stopped${c.reset}`]);
+  commandsFooter();
+}
+
+async function cmdRestart() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    console.log(`\n  ${GLYPH.err}  No config found. Run ${c.blue}bloby init${c.reset} first.\n`);
+    process.exit(1);
+  }
+  banner();
+  if (!hasDaemonSupport()) {
+    console.log(`\n  ${GLYPH.warn}  No service manager on this platform — restart the foreground process manually.\n`);
+    process.exit(1);
+  }
 
-  ${c.blue}${c.bold}${link(tunnelUrl)}${c.reset}
-  ${c.dim}(cmd+click or ctrl+click to open)${c.reset}`);
+  // Anything that can block (cloudflared download) happens BEFORE the stop —
+  // never leave Bloby down while waiting on the network.
+  const config = readConfig() || {};
+  const preMode = tunnelModeOf(config);
+  if (preMode !== 'off' && preMode !== 'named' && !hasCloudflared()) {
+    console.log('');
+    const sCf = new Spinner().start('Installing cloudflared...');
+    try { await installCloudflared(); sCf.succeed('cloudflared ready'); }
+    catch (e) { sCf.fail(`cloudflared install failed: ${e.message}`); process.exit(1); }
+  }
 
-  if (relayUrl && relayUrl !== tunnelUrl) {
-    console.log(`
-  ${c.bold}${c.white}Your permanent URL:${c.reset}
+  const steps = new Steps(['Stopping Bloby', ...startStepTitles(config)]).start();
+  const stopped = await stopCore({ spinner: steps });
+  if (!stopped.ok) {
+    steps.fail(`Failed to stop: ${stopped.error}`);
+    commandsFooter();
+    process.exit(1);
+  }
+  steps.advance(); // Stopping Bloby → Preparing
 
-  ${c.pink}${c.bold}${link(relayUrl)}${c.reset}`);
+  const result = await startCore({ ui: steps });
+  if (!result.ok) {
+    steps.fail(`Failed to start: ${result.error}`);
+    console.log(`     ${c.dim}Check ${c.reset}${c.blue}bloby logs${c.reset}${c.dim} for details.${c.reset}`);
+    commandsFooter();
+    process.exit(1);
   }
+  if (result.healthy && !result.tunnelFailed && (result.tunnelMode === 'off' || result.ready)) steps.finish();
+  else steps.fail();
+  printReadyBlock(result);
+  commandsFooter();
+}
 
-  if (hasDaemonSupport()) {
-    console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
-
-  ${c.bold}${c.white}Commands:${c.reset}
-  ${c.dim}Status${c.reset}    ${c.pink}bloby status${c.reset}
-  ${c.dim}Logs${c.reset}      ${c.pink}bloby logs${c.reset}
-  ${c.dim}Stop${c.reset}      ${c.pink}bloby stop${c.reset}
-  ${c.dim}Restart${c.reset}   ${c.pink}bloby daemon restart${c.reset}
-  ${c.dim}Update${c.reset}    ${c.pink}bloby update${c.reset}
-  `);
+async function cmdStatus() {
+  const config = readConfig();
+  const port = config?.port || 7400;
+  const runtime = readRuntime();
+  const dPid = daemonPid();
+  const installed = isDaemonInstalled();
+  const strays = scanSupervisors();
+  const health = await fetchHealth(port, 2000);
+
+  const pid = runtime?.pid || dPid || (strays[0]?.pid ?? null);
+  const running = pid !== null || !!health;
+  const version = runtime?.version || pkg.version;
+
+  // A loaded service with no live pid is crash-looping or throttled — launchd/
+  // systemd will respawn it, so calling that "stopped" would mislead.
+  const jobLoadedNoPid = !running && (
+    (PLATFORM === 'darwin' && installed && launchdJob().loaded === true) ||
+    (PLATFORM === 'linux' && ['activating', 'active'].includes(systemdShow().activeState))
+  );
+
+  if (running && health) {
+    const up = runtime?.startedAt ? ` · up ${formatUptime(Date.now() - runtime.startedAt)}` : (health.uptime != null ? ` · up ${formatUptime(health.uptime * 1000)}` : '');
+    const mode = dPid && pid === dPid ? 'daemon' : 'foreground';
+    const pidPart = pid ? ` · PID ${pid}` : '';
+    resultBox([` ${c.blue}●${c.reset}  ${c.bold}Bloby is running${c.reset}   ${c.dim}v${version}${pidPart}${up} · ${mode}${c.reset}`]);
+  } else if (running) {
+    resultBox([` ${c.yellow}●${c.reset}  ${c.bold}Bloby is starting${c.reset}   ${c.dim}PID ${pid} alive, not answering yet — give it a moment${c.reset}`]);
+  } else if (jobLoadedNoPid) {
+    resultBox([` ${c.yellow}●${c.reset}  ${c.bold}Bloby is restarting${c.reset}   ${c.dim}service loaded but the process is down — check ${c.reset}${c.blue}bloby logs${c.reset}`]);
+  } else if (installed) {
+    resultBox([` ${c.dim}●${c.reset}  ${c.bold}Bloby is stopped${c.reset}   ${c.dim}run ${c.reset}${c.blue}bloby start${c.reset}`]);
   } else {
-    console.log(`
-  ${c.dim}─────────────────────────────────${c.reset}
-
-  ${c.bold}${c.white}Commands:${c.reset}
-  ${c.dim}Status${c.reset}    ${c.pink}bloby status${c.reset}
-  ${c.dim}Update${c.reset}    ${c.pink}bloby update${c.reset}
+    resultBox([` ${c.dim}●${c.reset}  ${c.bold}Bloby is not set up${c.reset}   ${c.dim}run ${c.reset}${c.blue}bloby init${c.reset}`]);
+  }
 
-  ${c.dim}Press Ctrl+C to stop${c.reset}
-  `);
+  if (config) {
+    console.log('');
+    console.log(`  ${c.dim}${'Local'.padEnd(9)}${c.reset}${c.blue}${link(`http://localhost:${port}`)}${c.reset}`);
+    const mode = tunnelModeOf(config);
+    if (running && config.tunnelUrl) {
+      console.log(`  ${c.dim}${'Tunnel'.padEnd(9)}${c.reset}${c.blue}${link(config.tunnelUrl)}${c.reset}  ${c.dim}(${mode})${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}${'Tunnel'.padEnd(9)}${mode}${c.reset}`);
+    }
+    if (config.relay?.url) {
+      console.log(`  ${c.dim}${'Relay'.padEnd(9)}${c.reset}${c.pink}${link(config.relay.url)}${c.reset}`);
+    }
+    if (PLATFORM === 'darwin') {
+      let logNote = '';
+      try {
+        const st = fs.statSync(LAUNCHD_LOG);
+        logNote = `  ${c.dim}· updated ${formatAgo(Date.now() - st.mtimeMs)}${c.reset}`;
+      } catch {}
+      console.log(`  ${c.dim}${'Logs'.padEnd(9)}${LAUNCHD_LOG.replace(os.homedir(), '~')}${c.reset}${logNote}`);
+    } else if (PLATFORM === 'linux') {
+      console.log(`  ${c.dim}${'Logs'.padEnd(9)}journalctl -u ${SERVICE_NAME}${c.reset}`);
+    }
+    console.log(`  ${c.dim}${'Config'.padEnd(9)}${CONFIG_PATH.replace(os.homedir(), '~')}${c.reset}`);
   }
-}
 
-function readyMessage(tunnelUrl, relayUrl) {
-  if (relayUrl) {
-    console.log(`\n  ${c.pink}${c.bold}${link(relayUrl)}${c.reset}`);
-    console.log(`  ${c.dim}(cmd+click or ctrl+click to open)${c.reset}`);
+  // Trust warnings — never let status lie about which process is which.
+  if (running && dPid === null && pid) {
+    console.log(`\n  ${GLYPH.warn}  Running outside the daemon ${c.dim}(foreground or dev instance — logs/auto-restart don't apply)${c.reset}.`);
+    console.log(`     ${c.dim}Run ${c.reset}${c.blue}bloby restart${c.reset}${c.dim} to bring it back under the background service.${c.reset}`);
   }
-  if (tunnelUrl && tunnelUrl !== relayUrl) {
-    console.log(`  ${c.dim}Tunnel:${c.reset}  ${c.dim}${link(tunnelUrl)}${c.reset}`);
+  if (dPid && strays.some(p => p.pid !== dPid)) {
+    console.log(`\n  ${GLYPH.warn}  Found extra Bloby processes besides the daemon: ${strays.filter(p => p.pid !== dPid).map(p => p.pid).join(', ')}.`);
+    console.log(`     ${c.dim}Run ${c.reset}${c.blue}bloby restart${c.reset}${c.dim} to clean them up.${c.reset}`);
   }
-  console.log('');
-}
 
-function writeVersionFile(version) {
-  try { fs.writeFileSync(path.join(DATA_DIR, 'VERSION'), version); } catch {}
+  // Best-effort update check — never slows status down more than ~1.5s.
+  if (isTTY) {
+    try {
+      const res = await fetch(`https://registry.npmjs.org/bloby-bot/latest?_t=${Date.now()}`, {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(1500),
+      });
+      if (res.ok) {
+        const latest = await res.json();
+        if (latest.version && compareVersions(latest.version, pkg.version) > 0) {
+          console.log(`\n  ${GLYPH.dl}  Update available: ${c.dim}v${pkg.version} →${c.reset} ${c.bold}v${latest.version}${c.reset}  ${c.dim}— run ${c.reset}${c.blue}bloby update${c.reset}`);
+        }
+      }
+    } catch {}
+  }
+
+  commandsFooter();
 }
 
-/**
- * Poll daemon log for __READY__ and config.json for tunnel URL until the daemon
- * is fully ready (tunnel registered with relay). logOffset should be captured
- * BETWEEN stopping and starting the daemon so only new-session output is checked.
- *
- * Advances the stepper through tunnel + verification steps.
- */
-async function waitForDaemonHealth(stepper, config, hasTunnel, logOffset) {
-  const port = config.port || 7400;
-  const relayUrl = config.relay?.url || null;
-  let tunnelUrl = null;
-  let tunnelShown = false;
-  let ready = false;
+function cmdLogs() {
+  const lines = Math.max(1, Number(flagValue('-n') || flagValue('--lines') || 80) || 80);
 
-  const oldTunnelUrl = config.tunnelUrl || null;
+  // Provenance header — `bloby logs` must never silently show a dead process's
+  // output. Establish who is running and whether these logs belong to it.
+  const runtime = readRuntime();
+  const dPid = daemonPid();
+  const strays = scanSupervisors();
+  const livePid = runtime?.pid || dPid || strays[0]?.pid || null;
 
-  // Daemon log file — the supervisor writes __READY__ to stdout which goes here
-  const logFile = PLATFORM === 'darwin'
-    ? path.join(LAUNCHD_LOG_DIR, 'bloby.log')
-    : null;
+  if (PLATFORM === 'win32') {
+    console.log(`\n  ${GLYPH.warn}  Logs are shown in the foreground terminal on Windows.\n`);
+    process.exit(1);
+  }
 
-  for (let i = 0; i < 120; i++) {
-    await new Promise(r => setTimeout(r, 1000));
+  if (!livePid) {
+    console.log(`\n  ${c.dim}●  Bloby is not running — showing logs from the last run.${c.reset}\n`);
+  } else if (dPid === null) {
+    // Daemon logs (file or journal) can only contain daemon output — a live
+    // non-daemon instance means everything below is from a previous run.
+    const sink = PLATFORM === 'linux' ? 'the journal' : 'this log file';
+    console.log(`\n  ${GLYPH.warn}  Bloby is running ${c.bold}outside the daemon${c.reset} (PID ${livePid}) — its output is NOT in ${sink}.`);
+    console.log(`     ${c.dim}These lines are from the last daemon run. Run ${c.reset}${c.blue}bloby restart${c.reset}${c.dim} to fix.${c.reset}\n`);
+  } else if (runtime?.startedAt) {
+    console.log(`\n  ${c.blue}●${c.reset}  ${c.dim}PID ${livePid} · started ${formatAgo(Date.now() - runtime.startedAt)}${c.reset}\n`);
+  } else {
+    console.log('');
+  }
 
-    // Check for new tunnel URL in config
-    if (hasTunnel && !tunnelShown) {
-      try {
-        const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-        if (cfg.tunnelUrl && cfg.tunnelUrl !== oldTunnelUrl) {
-          tunnelUrl = cfg.tunnelUrl;
-          stepper.advance(); // Connecting tunnel done
-          if (relayUrl) {
-            stepper.setInfo([
-              `  ${c.dim}Waiting for ${c.reset}${c.white}${relayUrl.replace('https://', '')}${c.reset}${c.dim} to become reachable (can take up to 2 min)${c.reset}`,
-              `  ${c.dim}In the meanwhile you can access:${c.reset} ${c.blue}${link(tunnelUrl)}${c.reset}`,
-            ]);
-          }
-          tunnelShown = true;
-        }
-      } catch {}
+  if (PLATFORM === 'darwin') {
+    if (!fs.existsSync(LAUNCHD_LOG)) {
+      console.log(`  ${c.dim}No logs yet at ${LAUNCHD_LOG.replace(os.homedir(), '~')}${c.reset}`);
+      commandsFooter();
+      return;
     }
-
-    // Check for __READY__ in daemon log (emitted after relay registration)
-    if (!ready) {
-      if (logFile && fs.existsSync(logFile)) {
-        try {
-          const currentSize = fs.statSync(logFile).size;
-          if (currentSize > logOffset) {
-            const fd = fs.openSync(logFile, 'r');
-            const buf = Buffer.alloc(currentSize - logOffset);
-            fs.readSync(fd, buf, 0, buf.length, logOffset);
-            fs.closeSync(fd);
-            const newContent = buf.toString('utf-8');
-            if (newContent.includes('__READY__')) {
-              ready = true;
-            }
-          }
-        } catch {}
-      } else {
-        // Linux / no log file fallback: check local health
-        try {
-          const res = await fetch(`http://127.0.0.1:${port}/api/health`);
-          if (res.ok) ready = true;
-        } catch {}
-      }
+    if (FOLLOW) {
+      // -F (not -f): follows by NAME, so it survives rotation — no more silent stale tails.
+      spawnSync('tail', ['-F', '-n', String(lines), LAUNCHD_LOG], { stdio: 'inherit' });
+      return;
     }
-
-    if (ready && (!hasTunnel || tunnelShown)) break;
+    spawnSync('tail', ['-n', String(lines), LAUNCHD_LOG], { stdio: 'inherit' });
+    commandsFooter();
+    return;
   }
 
-  // If tunnel never came up, advance past tunnel step anyway
-  if (hasTunnel && !tunnelShown) {
-    stepper.advance();
+  // Linux: journald
+  const jArgs = ['-u', SERVICE_NAME, '-n', String(lines), '--no-pager', '-q'];
+  if (FOLLOW) {
+    spawnSync('journalctl', [...jArgs, '-f'], { stdio: 'inherit' });
+    return;
   }
-
-  if (tunnelShown) {
-    stepper.setInfo([]);
+  const res = spawnSync('journalctl', jArgs, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+  if (res.stdout && res.stdout.trim()) {
+    process.stdout.write(res.stdout);
+  } else {
+    console.log(`  ${c.dim}No journal entries readable. If Bloby has run before, your user may lack journal access:${c.reset}`);
+    console.log(`  ${c.blue}sudo journalctl -u ${SERVICE_NAME} -n ${lines}${c.reset}`);
   }
-
-  // Advance past "Verifying connection"
-  stepper.advance();
-
-  // Re-read config for final URLs
-  try {
-    const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-    if (cfg.tunnelUrl) tunnelUrl = cfg.tunnelUrl;
-  } catch {}
-
-  return { tunnelUrl, relayUrl, healthOk: ready };
+  commandsFooter();
 }
 
-// ── Steps ──
+// ── init ──
 
 function createConfig() {
   fs.mkdirSync(DATA_DIR, { recursive: true });
@@ -885,161 +1788,214 @@ function createConfig() {
   }
 }
 
-const MIN_CF_SIZE = 10 * 1024 * 1024; // 10 MB — valid cloudflared is ~30-50 MB
-
-function hasCloudflared() {
-  // Check system-wide install
-  const which = process.platform === 'win32' ? 'where cloudflared' : 'which cloudflared';
-  try { execSync(which, { stdio: 'ignore' }); return true; } catch {}
-
-  // Check local install (validate by file size, never execute — avoids Windows popup)
-  const cfExe = process.platform === 'win32' ? CF_PATH + '.exe' : CF_PATH;
-  if (!fs.existsSync(cfExe)) return false;
-  const size = fs.statSync(cfExe).size;
-  if (size < MIN_CF_SIZE) {
-    fs.unlinkSync(cfExe);
-    return false;
+function chooseTunnelMode() {
+  // Headless init (pipes, CI, provisioning without --hosted) can't drive an
+  // arrow-key menu — default to quick instead of crashing on setRawMode.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(`  ${c.dim}No interactive terminal — defaulting to the quick tunnel. Change later with ${c.reset}${c.blue}bloby tunnel setup${c.reset}${c.dim}.${c.reset}`);
+    return Promise.resolve('quick');
   }
-  return true;
-}
 
-async function installCloudflared() {
-  if (hasCloudflared()) return;
-
-  fs.mkdirSync(BIN_DIR, { recursive: true });
+  return new Promise((resolve) => {
+    const options = [
+      {
+        label: 'Quick Tunnel',
+        mode: 'quick',
+        tag: 'Easy and Fast',
+        tagColor: c.green,
+        desc: [
+          'Random CloudFlare tunnel URL on every start/update',
+          `Optional: Use Bloby Relay Server and access your bot at ${c.reset}${c.pink}open.bloby.bot/YOURBOT${c.reset}${c.dim} (Free)`,
+          `Or use a premium handle like ${c.reset}${c.pink}bloby.bot/YOURBOT${c.reset}${c.dim} ($5 one-time fee)`,
+        ],
+      },
+      {
+        label: 'Named Tunnel',
+        mode: 'named',
+        tag: 'Advanced',
+        tagColor: c.yellow,
+        desc: [
+          'Persistent URL with your own domain',
+          'Requires a CloudFlare account + domain',
+          `Use a subdomain like ${c.reset}${c.white}bot.YOURDOMAIN.COM${c.reset}${c.dim} or the root domain`,
+        ],
+      },
+      {
+        label: 'Private Network',
+        mode: 'off',
+        tag: 'Secure',
+        tagColor: c.cyan,
+        desc: [
+          'No public URL — access via local network or VPN only',
+          `Use with ${c.reset}${c.white}Tailscale${c.reset}${c.dim}, WireGuard, or any private network`,
+          'Your bot stays invisible to the internet',
+        ],
+      },
+    ];
 
-  const platform = os.platform();
-  // os.arch() returns Node's arch, not the OS. Use PROCESSOR_ARCHITECTURE on Windows for real OS arch.
-  const arch = platform === 'win32'
-    ? (process.env.PROCESSOR_ARCHITECTURE || os.arch()).toLowerCase()
-    : os.arch();
-  let url;
+    let selected = 0;
+    let lineCount = 0;
 
-  if (platform === 'win32') {
-    url = arch.includes('arm')
-      ? 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-arm64.exe'
-      : 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe';
-  } else if (platform === 'darwin') {
-    url = arch === 'arm64'
-      ? 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz'
-      : 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64.tgz';
-  } else if (platform === 'linux') {
-    if (arch === 'arm64' || arch === 'aarch64') {
-      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64';
-    } else if (arch === 'arm' || arch === 'armv7l') {
-      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm';
-    } else {
-      url = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64';
+    function writeLine(text = '') {
+      process.stdout.write(`\x1b[2K${text}\n`);
+      lineCount++;
     }
-  } else {
-    throw new Error(`Unsupported platform: ${platform}/${arch}`);
-  }
 
-  if (platform === 'win32') {
-    const dest = CF_PATH + '.exe';
-    execSync(`curl.exe -fsSL -o "${dest}" "${url}"`, { stdio: 'ignore' });
-  } else if (url.endsWith('.tgz')) {
-    execSync(`curl -fsSL "${url}" | tar xz -C "${BIN_DIR}"`, { stdio: 'ignore' });
-  } else {
-    execSync(`curl -fsSL -o "${CF_PATH}" "${url}"`, { stdio: 'ignore' });
-    fs.chmodSync(CF_PATH, 0o755);
-  }
-}
+    function render() {
+      if (lineCount > 0) process.stdout.write(`\x1b[${lineCount}A`);
+      lineCount = 0;
 
-// ── Boot server ──
+      writeLine(`  ${c.bold}${c.white}How do you want to connect your bot?${c.reset}`);
+      writeLine();
 
-function bootServer({ onTunnelUp, onReady } = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(
-      process.execPath,
-      ['--import', 'tsx/esm', path.join(ROOT, 'supervisor/index.ts')],
-      { cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } },
-    );
+      for (let i = 0; i < options.length; i++) {
+        const opt = options[i];
+        const isSelected = i === selected;
+        const bullet = isSelected ? `${c.pink}❯` : `${c.dim} `;
+        const label = isSelected ? `${c.bold}${c.white}${opt.label}` : `${c.dim}${opt.label}`;
+        const tag = `${opt.tagColor}[${opt.tag}]${c.reset}`;
 
-    let tunnelUrl = null;
-    let relayUrl = null;
-    let resolved = false;
-    let stderrBuf = '';
-    let tunnelFired = false;
-    let tunnelFailed = false;
+        writeLine(`  ${bullet} ${label}${c.reset}  ${tag}`);
+        for (const line of opt.desc) {
+          writeLine(`      ${c.dim}${line}${c.reset}`);
+        }
+        if (i < options.length - 1) writeLine();
+      }
+    }
 
-    // Vite warmup tracking
-    let viteWarmResolve;
-    const viteWarm = new Promise((r) => { viteWarmResolve = r; });
+    process.stdout.write('\x1b[?25l');
+    render();
 
-    const doResolve = () => {
-      if (resolved) return;
-      resolved = true;
-      if (!tunnelFired && onTunnelUp) onTunnelUp();
-      if (onReady) onReady();
-      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-      resolve({
-        child,
-        tunnelUrl: tunnelUrl || `http://localhost:${config.port}`,
-        relayUrl: relayUrl || config.relay?.url || null,
-        tunnelFailed,
-        viteWarm,
-      });
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf-8');
+
+    const onKey = (key) => {
+      if (key === '\x1b[A' || key === 'k') {
+        selected = (selected - 1 + options.length) % options.length;
+        render();
+      } else if (key === '\x1b[B' || key === 'j') {
+        selected = (selected + 1) % options.length;
+        render();
+      } else if (key === '\r' || key === '\n') {
+        process.stdout.write('\x1b[?25h');
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeListener('data', onKey);
+        resolve(options[selected].mode);
+      } else if (key === '\x03') {
+        restoreTerminal();
+        process.stdout.write('\n');
+        process.exit(130);
+      }
     };
 
-    const handleData = (data) => {
-      const text = data.toString();
+    process.stdin.on('data', onKey);
+  });
+}
 
-      const tunnelMatch = text.match(/__TUNNEL_URL__=(\S+)/);
-      if (tunnelMatch) {
-        tunnelUrl = tunnelMatch[1];
-        if (!tunnelFired && onTunnelUp) { tunnelFired = true; onTunnelUp(tunnelUrl); }
-      }
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
+}
 
-      const relayMatch = text.match(/__RELAY_URL__=(\S+)/);
-      if (relayMatch) relayUrl = relayMatch[1];
+async function runNamedTunnelSetup() {
+  const s = new Spinner().start('Checking cloudflared...');
+  await installCloudflared();
+  s.succeed('cloudflared ready');
+
+  // Resolve the binary ONCE. Note: spawnSync does not throw on ENOENT (it returns
+  // {error}), so a try/catch fallback around it is dead code — the old CLI
+  // silently skipped `tunnel login` whenever cloudflared wasn't on PATH.
+  const cf = (() => {
+    try { execSync(PLATFORM === 'win32' ? 'where cloudflared' : 'which cloudflared', { stdio: 'ignore' }); return 'cloudflared'; } catch {}
+    return PLATFORM === 'win32' ? CF_PATH + '.exe' : CF_PATH;
+  })();
 
-      if (text.includes('__VITE_WARM__')) {
-        viteWarmResolve();
-      }
+  console.log(`\n  ${c.bold}${c.white}Step 1:${c.reset} Log in to Cloudflare\n`);
+  console.log(`  ${c.dim}This will open a browser window. Authorize the domain you want to use.${c.reset}\n`);
+  const login = spawnSync(cf, ['tunnel', 'login'], { stdio: 'inherit' });
+  if (login.error || login.status !== 0) {
+    console.log(`\n  ${GLYPH.err}  cloudflared login failed${login.error ? `: ${login.error.message}` : ''}.\n`);
+    process.exit(1);
+  }
+  console.log('');
 
-      if (text.includes('__READY__')) {
-        doResolve();
-        return;
-      }
+  const tunnelName = (await ask(`  ${c.bold}Tunnel name${c.reset} ${c.dim}(default: bloby)${c.reset}: `)) || 'bloby';
 
-      if (text.includes('__TUNNEL_FAILED__')) {
-        tunnelFailed = true;
-        doResolve();
-      }
-    };
+  const s2 = new Spinner().start(`Creating tunnel "${tunnelName}"...`);
+  const create = spawnSync(cf, ['tunnel', 'create', tunnelName], { encoding: 'utf-8' });
+  if (create.error || create.status !== 0) {
+    s2.fail('Failed to create tunnel. It may already exist.');
+    console.log(`  ${c.dim}Try: cloudflared tunnel list${c.reset}\n`);
+    process.exit(1);
+  }
+  const createOutput = (create.stdout || '') + (create.stderr || '');
 
-    // Safety-net timeout: resolve after 45s even if __READY__ never arrives
-    setTimeout(doResolve, 45_000);
+  const uuidMatch = createOutput.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+  if (!uuidMatch) {
+    s2.fail('Could not parse tunnel UUID from output.');
+    console.log(`  ${c.dim}${createOutput}${c.reset}\n`);
+    process.exit(1);
+  }
+  const tunnelUuid = uuidMatch[1];
+  s2.succeed(`Tunnel created: ${c.dim}${tunnelUuid}${c.reset}`);
 
-    child.stdout.on('data', handleData);
-    child.stderr.on('data', (data) => {
-      stderrBuf += data.toString();
-      handleData(data);
-    });
+  const domain = await ask(`  ${c.bold}Your domain${c.reset} ${c.dim}(e.g. bot.mydomain.com)${c.reset}: `);
+  if (!domain) {
+    console.log(`\n  ${GLYPH.err}  Domain is required for named tunnels.\n`);
+    process.exit(1);
+  }
+
+  const config = readConfig() || {};
+  const port = config.port || 7400;
+  const cfHome = path.join(os.homedir(), '.cloudflared');
+  const cfConfigPath = path.join(DATA_DIR, 'cloudflared-config.yml');
+
+  const yamlContent = `tunnel: ${tunnelUuid}
+credentials-file: ${path.join(cfHome, `${tunnelUuid}.json`)}
+ingress:
+  - service: http://localhost:${port}
+`;
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(cfConfigPath, yamlContent);
+  console.log(`\n  ${GLYPH.ok}  Config written to ${c.dim}${cfConfigPath}${c.reset}`);
 
-    process.on('SIGINT', () => child.kill('SIGINT'));
-    process.on('SIGTERM', () => child.kill('SIGTERM'));
+  console.log(`\n${DIVIDER}\n`);
+  console.log(`  ${c.bold}${c.white}Tunnel created!${c.reset}`);
+  console.log(`  ${c.white}Add a CNAME record pointing to:${c.reset}\n`);
+  console.log(`  ${c.pink}${c.bold}${tunnelUuid}.cfargotunnel.com${c.reset}\n`);
+  console.log(`  ${c.dim}Or run: cloudflared tunnel route dns ${tunnelName} ${domain}${c.reset}\n`);
 
-    child.on('exit', (code) => {
-      if (!resolved) {
-        reject(new Error(stderrBuf.trim() || `Server exited with code ${code}`));
-      } else {
-        process.exit(code ?? 1);
-      }
-    });
-  });
+  return { tunnelName, domain, cfConfigPath };
 }
 
-// ── Main flows ──
+async function cmdInit() {
+  banner();
 
-async function init() {
-  if (!HOSTED) banner();
+  // Re-running init against a live install must not re-bootstrap anything (the
+  // health wait would just sit out its tunnel deadline against an unchanged URL).
+  if (fs.existsSync(CONFIG_PATH) && hasDaemonSupport()) {
+    const runtime = readRuntime();
+    const dPid = daemonPid();
+    if (dPid || runtime) {
+      const config = readConfig();
+      if (HOSTED) {
+        console.log(`__HOSTED_READY__=${JSON.stringify({ tunnelUrl: config?.tunnelUrl || `http://localhost:${config?.port || 7400}`, status: config?.tunnelUrl ? 'ok' : 'tunnel_failed', daemon: true })}`);
+        process.exit(0);
+      }
+      resultBox([` ${c.blue}●${c.reset}  ${c.bold}Bloby is already set up and running${c.reset}`]);
+      console.log(`\n  ${c.dim}Use ${c.reset}${c.blue}bloby restart${c.reset}${c.dim} to restart it, or ${c.reset}${c.blue}bloby tunnel setup${c.reset}${c.dim} to change the tunnel.${c.reset}\n`);
+      describeRunning(config);
+      commandsFooter();
+      return;
+    }
+  }
 
   createConfig();
   writeVersionFile(pkg.version);
 
-  // --hosted: non-interactive, quick tunnel, no prompts
+  // --hosted: non-interactive, quick tunnel, machine-readable output
   const tunnelMode = HOSTED ? 'quick' : await (async () => {
     console.log('');
     const mode = await chooseTunnelMode();
@@ -1047,8 +2003,7 @@ async function init() {
     return mode;
   })();
 
-  // Update config with chosen mode + generate wallet if needed
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  const config = readConfig() || {};
 
   // Generate USDC wallet (skip if one already exists)
   if (!config.wallet?.privateKey) {
@@ -1058,7 +2013,6 @@ async function init() {
     config.wallet = { privateKey, address: account.address };
   }
 
-  // Handle named tunnel setup before starting
   if (tunnelMode === 'named') {
     const setup = await runNamedTunnelSetup();
     config.tunnel = {
@@ -1072,433 +2026,147 @@ async function init() {
   }
   fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
 
-  const canDaemon = hasDaemonSupport();
-  const hasTunnelInit = tunnelMode !== 'off';
-
-  // Hosted mode: simple log lines instead of animated stepper
-  const log = HOSTED
-    ? (msg) => console.log(`[bloby] ${msg}`)
-    : null;
-
-  const steps = [
-    'Creating config',
-    ...(hasTunnelInit ? ['Installing cloudflared'] : []),
-    'Starting server',
-    ...(hasTunnelInit ? ['Connecting tunnel', 'Verifying connection'] : []),
-    'Preparing dashboard',
-    ...(canDaemon ? ['Setting up auto-start daemon'] : []),
-  ];
-
-  const stepper = HOSTED ? null : new Stepper(steps);
-  if (stepper) stepper.start();
+  const log = HOSTED ? (msg) => console.log(`[bloby] ${msg}`) : null;
 
-  // Config already created
-  if (log) log('Config created');
-  if (stepper) stepper.advance();
-
-  // Cloudflared (skip for named — already installed during setup, skip for off — no tunnel)
-  if (hasTunnelInit && tunnelMode !== 'named') {
-    if (log) log('Installing cloudflared...');
-    await installCloudflared();
-    if (log) log('Cloudflared ready');
-  }
-  if (hasTunnelInit && stepper) stepper.advance();
-
-  // Server + Tunnel
-  if (log) log('Starting server...');
-  if (stepper) stepper.advance();
-  let result;
-  try {
-    result = await bootServer({
-      onTunnelUp: hasTunnelInit ? (url) => {
-        if (log) log(`Tunnel up: ${url}`);
-        if (stepper) {
-          stepper.advance();  // Connecting tunnel done
-          if (config.relay?.url) {
-            stepper.setInfo([
-              `  ${c.dim}Waiting for ${c.reset}${c.white}${config.relay.url.replace('https://', '')}${c.reset}${c.dim} to become reachable (can take up to 2 min)${c.reset}`,
-              `  ${c.dim}In the meanwhile you can access:${c.reset} ${c.blue}${link(url)}${c.reset}`,
-            ]);
-          }
-        }
-      } : undefined,
-      onReady: hasTunnelInit ? () => {
-        if (log) log('Connection verified');
-        if (stepper) {
-          stepper.setInfo([]);
-          stepper.advance();  // Verifying connection done
-        }
-      } : undefined,
-    });
-  } catch (err) {
-    if (stepper) stepper.finish();
+  // Hosted containers / Windows: no service manager — run in the foreground and
+  // keep this process alive as the supervisor's parent (the hosted provisioner
+  // depends on this).
+  if (!hasDaemonSupport()) {
     if (HOSTED) {
-      console.error(JSON.stringify({ error: err.message }));
-      process.exit(1);
-    }
-    console.error(`\n  ${c.red}Server failed to start:${c.reset}`);
-    console.error(`  ${c.dim}${err.message}${c.reset}\n`);
-    process.exit(1);
-  }
-  let { child, tunnelUrl, relayUrl, tunnelFailed, viteWarm } = result;
-
-  // Wait for Vite to finish pre-transforming all modules (with timeout)
-  if (log) log('Preparing dashboard...');
-  await Promise.race([viteWarm, new Promise(r => setTimeout(r, 30_000))]);
-  if (stepper) stepper.advance();
-
-  // Install daemon (systemd on Linux, launchd on macOS)
-  if (canDaemon) {
-    if (log) log('Installing daemon...');
-    await killAndWait(child);
-    const nodePath = process.execPath;
-    const realHome = os.homedir();
-    const res = spawnSync(process.execPath, [process.argv[1], 'daemon', 'install'], {
-      stdio: 'pipe',  // Suppress subprocess output — stepper handles UI
-      env: { ...process.env, BLOBY_NODE_PATH: nodePath, BLOBY_REAL_HOME: realHome },
-    });
-
-    // Wait for the daemon's supervisor to get a new tunnel URL
-    // (the old one died with the temp server we just killed)
-    if (res.status === 0 && hasTunnelInit) {
-      if (log) log('Waiting for daemon tunnel URL...');
-      let daemonTunnelUrl = null;
-      for (let i = 0; i < 30; i++) {
-        await new Promise((r) => setTimeout(r, 1000));
-        try {
-          const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-          if (cfg.tunnelUrl && cfg.tunnelUrl !== tunnelUrl) {
-            daemonTunnelUrl = cfg.tunnelUrl;
-            break;
-          }
-        } catch {}
-      }
-      if (daemonTunnelUrl) tunnelUrl = daemonTunnelUrl;
-      // Also pick up relay URL that may have been saved earlier
+      if (log) log('Starting server (foreground, no daemon support)...');
+      let result;
       try {
-        const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-        if (cfg.relay?.url) relayUrl = cfg.relay.url;
-      } catch {}
-    }
-
-    if (stepper) {
-      stepper.advance();
-      stepper.finish();
+        await installCloudflared();
+        result = await bootServer({
+          onTunnelUp: (url) => { if (log && url) log(`Tunnel up: ${url}`); },
+        });
+      } catch (err) {
+        console.error(JSON.stringify({ error: err.message }));
+        process.exit(1);
+      }
+      await Promise.race([result.viteWarm, new Promise(r => setTimeout(r, 30_000))]);
+      console.log(`__HOSTED_READY__=${JSON.stringify({ tunnelUrl: result.tunnelUrl, status: result.tunnelFailed ? 'tunnel_failed' : 'ok' })}`);
+      result.child.stdout.on('data', (d) => process.stdout.write(d));
+      result.child.stderr.on('data', (d) => process.stderr.write(d));
+      return; // stays attached
     }
-
+    console.log(`\n  ${GLYPH.warn}  No service manager on this platform — Bloby will run in the foreground.\n`);
+    return runForeground();
+  }
+
+  if (log) log('Starting daemon...');
+  const initConfig = readConfig() || {};
+  const steps = new Steps(startStepTitles(initConfig)).start();
+  // Hosted provisioning treats tunnel_failed as meaningful — give cold cloud
+  // boxes a longer window before declaring the tunnel down.
+  const result = await startCore({ ui: steps, ...(HOSTED ? { timeoutMs: 180_000 } : {}) });
+  if (!result.ok) {
+    steps.fail(`Failed to start: ${result.error}`);
     if (HOSTED) {
-      // Machine-readable output for the provisioning script
-      const result = { tunnelUrl, status: tunnelFailed ? 'tunnel_failed' : 'ok' };
-      if (res.status === 0) result.daemon = true;
-      console.log(`__HOSTED_READY__=${JSON.stringify(result)}`);
-      process.exit(res.status ?? 0);
-    }
-
-    if (!hasTunnelInit) {
-      privateNetworkMessage(config.port);
-    } else if (tunnelFailed) {
-      tunnelFailedMessage(tunnelUrl);
-    } else {
-      finalMessage(tunnelUrl, relayUrl);
-    }
-    if (res.status === 0) {
-      console.log(`  ${c.blue}✔${c.reset}  Daemon installed — Bloby will auto-start on ${PLATFORM === 'darwin' ? 'login' : 'boot'}.`);
-    } else {
-      console.log(`  ${c.yellow}⚠${c.reset}  Daemon install failed. Run ${c.pink}bloby daemon install${c.reset} manually.`);
-    }
-    console.log('');
-    process.exit(res.status ?? 0);
-  }
-
-  if (stepper) stepper.finish();
-  if (HOSTED) {
-    const result = { tunnelUrl, status: tunnelFailed ? 'tunnel_failed' : 'ok' };
-    console.log(`__HOSTED_READY__=${JSON.stringify(result)}`);
-  } else if (!hasTunnelInit) {
-    privateNetworkMessage(config.port);
-  } else if (tunnelFailed) {
-    tunnelFailedMessage(tunnelUrl);
-  } else {
-    finalMessage(tunnelUrl, relayUrl);
-  }
-
-  child.stdout.on('data', (d) => {
-    process.stdout.write(`  ${c.dim}${d.toString().trim()}${c.reset}\n`);
-  });
-  child.stderr.on('data', (d) => {
-    const line = d.toString().trim();
-    if (!line || line.includes('AssignProcessToJobObject')) return;
-    process.stderr.write(`  ${c.dim}${line}${c.reset}\n`);
-  });
-}
-
-async function start() {
-  if (!fs.existsSync(CONFIG_PATH)) {
-    return init();
-  }
-
-  // If daemon is already running, don't start a second instance
-  if (isDaemonInstalled() && isDaemonActive()) {
-    banner();
-    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-    console.log(`\n  ${c.blue}●${c.reset} Bloby is already running as a daemon.\n`);
-    if (config.relay?.url) {
-      console.log(`  ${c.dim}URL:${c.reset}       ${c.pink}${link(config.relay.url)}${c.reset}`);
+      console.error(JSON.stringify({ error: result.error }));
     }
-    console.log(`  ${c.dim}Status:${c.reset}    ${c.pink}bloby daemon status${c.reset}`);
-    console.log(`  ${c.dim}Logs:${c.reset}      ${c.pink}bloby daemon logs${c.reset}`);
-    console.log(`  ${c.dim}Restart:${c.reset}   ${c.pink}bloby daemon restart${c.reset}`);
-    console.log(`  ${c.dim}Stop:${c.reset}      ${c.pink}bloby daemon stop${c.reset}\n`);
-    return;
-  }
-
-  const canDaemon = hasDaemonSupport();
-  const needsDaemon = canDaemon && !isDaemonInstalled();
-
-  banner();
-
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-  const tunnelMode = config.tunnel?.mode ?? (config.tunnel?.enabled === false ? 'off' : 'quick');
-  const hasTunnel = tunnelMode !== 'off';
-
-  const steps = [
-    'Loading config',
-    'Starting server',
-    ...(hasTunnel ? ['Connecting tunnel', 'Verifying connection'] : []),
-    'Preparing dashboard',
-    ...(needsDaemon ? ['Setting up auto-start daemon'] : []),
-  ];
-  const stepper = new Stepper(steps);
-  stepper.start();
-
-  stepper.advance(); // config exists
-  stepper.advance(); // starting
-
-  let result;
-  try {
-    result = await bootServer({
-      onTunnelUp: (url) => {
-        if (!hasTunnel) return;
-        stepper.advance();  // Connecting tunnel done
-        if (config.relay?.url) {
-          stepper.setInfo([
-            `  ${c.dim}Waiting for ${c.reset}${c.white}${config.relay.url.replace('https://', '')}${c.reset}${c.dim} to become reachable (can take up to 2 min)${c.reset}`,
-            `  ${c.dim}In the meanwhile you can access:${c.reset} ${c.blue}${link(url)}${c.reset}`,
-          ]);
-        }
-      },
-      onReady: () => {
-        if (!hasTunnel) return;
-        stepper.setInfo([]);
-        stepper.advance();  // Verifying connection done
-      },
-    });
-  } catch (err) {
-    stepper.finish();
-    console.error(`\n  ${c.red}Server failed to start:${c.reset}`);
-    console.error(`  ${c.dim}${err.message}${c.reset}\n`);
     process.exit(1);
   }
-  let { child, tunnelUrl, relayUrl, tunnelFailed, viteWarm } = result;
-
-  // Wait for Vite to finish pre-transforming all modules (with timeout)
-  await Promise.race([viteWarm, new Promise(r => setTimeout(r, 30_000))]);
-  stepper.advance();
-
-  // Install daemon (systemd on Linux, launchd on macOS) if not already installed
-  if (needsDaemon) {
-    await killAndWait(child);
-    const nodePath = process.execPath;
-    const realHome = os.homedir();
-    const res = spawnSync(process.execPath, [process.argv[1], 'daemon', 'install'], {
-      stdio: 'pipe',  // Suppress subprocess output — stepper handles UI
-      env: { ...process.env, BLOBY_NODE_PATH: nodePath, BLOBY_REAL_HOME: realHome },
-    });
-
-    // Wait for the daemon's supervisor to get a new tunnel URL
-    if (res.status === 0 && hasTunnel) {
-      let daemonTunnelUrl = null;
-      for (let i = 0; i < 30; i++) {
-        await new Promise((r) => setTimeout(r, 1000));
-        try {
-          const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-          if (cfg.tunnelUrl && cfg.tunnelUrl !== tunnelUrl) {
-            daemonTunnelUrl = cfg.tunnelUrl;
-            break;
-          }
-        } catch {}
-      }
-      if (daemonTunnelUrl) tunnelUrl = daemonTunnelUrl;
-      try {
-        const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-        if (cfg.relay?.url) relayUrl = cfg.relay.url;
-      } catch {}
-    }
-
-    stepper.advance();
-    stepper.finish();
-    if (!hasTunnel) {
-      privateNetworkMessage(config.port);
-    } else if (tunnelFailed) {
-      tunnelFailedMessage(tunnelUrl);
-    } else {
-      finalMessage(tunnelUrl, relayUrl);
-    }
-    if (res.status === 0) {
-      console.log(`  ${c.blue}✔${c.reset}  Daemon installed — Bloby will auto-start on ${PLATFORM === 'darwin' ? 'login' : 'boot'}.`);
-    } else {
-      console.log(`  ${c.yellow}⚠${c.reset}  Daemon install failed. Run ${c.pink}bloby daemon install${c.reset} manually.`);
-    }
-    console.log('');
-    process.exit(res.status ?? 0);
-  }
-
-  stepper.finish();
-  if (!hasTunnel) {
-    privateNetworkMessage(config.port);
-  } else if (tunnelFailed) {
-    tunnelFailedMessage(tunnelUrl);
-  } else {
-    finalMessage(tunnelUrl, relayUrl);
-  }
+  if (result.healthy && !result.tunnelFailed && (result.tunnelMode === 'off' || result.ready)) steps.finish();
+  else steps.fail();
 
-  child.stdout.on('data', (d) => {
-    process.stdout.write(`  ${c.dim}${d.toString().trim()}${c.reset}\n`);
-  });
-  child.stderr.on('data', (d) => {
-    const line = d.toString().trim();
-    if (!line || line.includes('AssignProcessToJobObject')) return;
-    process.stderr.write(`  ${c.dim}${line}${c.reset}\n`);
-  });
+  if (HOSTED) {
+    if (log) log(result.healthy ? 'Daemon running' : 'Daemon starting');
+    // status keyed off the supervisor's explicit __TUNNEL_FAILED__ marker (same
+    // semantics as the no-daemon foreground path) — a slow tunnel is not a failure.
+    const hostedStatus = result.tunnelFailed || !result.tunnelUrl ? 'tunnel_failed' : 'ok';
+    console.log(`__HOSTED_READY__=${JSON.stringify({ tunnelUrl: result.tunnelUrl || `http://localhost:${result.port}`, status: hostedStatus, daemon: true })}`);
+    process.exit(0);
+  }
+
+  printReadyBlock(result);
+  console.log(`\n  ${GLYPH.ok}  Bloby auto-starts on ${PLATFORM === 'darwin' ? 'login' : 'boot'}.`);
+  console.log(`  ${GLYPH.next} Open the dashboard above to finish setup.`);
+  commandsFooter();
 }
 
-async function status() {
-  const config = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : null;
-  const daemonRunning = isDaemonInstalled() && isDaemonActive();
-
-  // Try health endpoint
-  let healthOk = false;
-  let uptime = null;
-  if (config) {
-    try {
-      const res = await fetch(`http://localhost:${config.port}/api/health`);
-      const data = await res.json();
-      healthOk = true;
-      uptime = data.uptime;
-    } catch {}
-  }
+// ── update ──
 
-  if (healthOk) {
-    console.log(`\n  ${c.blue}●${c.reset} Bloby is running${daemonRunning ? ` ${c.dim}(daemon)${c.reset}` : ''}`);
-    if (uptime != null) console.log(`  ${c.dim}Uptime: ${uptime}s${c.reset}`);
-    if (config?.tunnelUrl) {
-      console.log(`  ${c.dim}Tunnel: ${c.reset}${c.blue}${link(config.tunnelUrl)}${c.reset}`);
-    }
-    if (config?.relay?.url) {
-      console.log(`  ${c.dim}Relay: ${c.reset}${c.pink}${link(config.relay.url)}${c.reset}`);
-    }
-    console.log(`  ${c.dim}Config: ${CONFIG_PATH}${c.reset}\n`);
-  } else if (daemonRunning) {
-    console.log(`\n  ${c.yellow}●${c.reset} Bloby daemon is running but not responding yet.`);
-    console.log(`  ${c.dim}It may still be starting up. Check logs:${c.reset}`);
-    console.log(`  ${c.pink}bloby daemon logs${c.reset}\n`);
-  } else {
-    console.log(`\n  ${c.dim}●${c.reset} Bloby is not running.\n`);
-  }
-}
+async function cmdUpdate() {
+  // When triggered by the supervisor (BLOBY_SELF_UPDATE=1), skip every daemon
+  // touch — the supervisor relaunches itself after we exit 0.
+  const selfUpdate = !!process.env.BLOBY_SELF_UPDATE;
 
-async function update() {
-  banner();
+  if (!selfUpdate) banner();
 
   // Refuse to run the update as root — file ownership would get poisoned
-  if (os.platform() !== 'win32' && process.getuid?.() === 0) {
-    console.log(`\n  ${c.red}✗${c.reset}  Do not run ${c.bold}bloby update${c.reset} with sudo.`);
-    console.log(`    The update manages sudo internally for daemon commands.\n`);
+  if (PLATFORM !== 'win32' && process.getuid?.() === 0) {
+    console.log(`\n  ${GLYPH.err}  Do not run ${c.bold}bloby update${c.reset} with sudo.`);
+    console.log('     The update manages sudo internally for daemon commands.\n');
     process.exit(1);
   }
 
   const currentVersion = pkg.version;
   console.log(`\n  ${c.dim}Current version: v${currentVersion}${c.reset}`);
-  console.log(`  ${c.blue}⠋${c.reset}  Checking for updates...\n`);
 
-  // Fetch latest package info from npm registry
+  const s = new Spinner().start('Checking for updates...');
+
   let latest;
   try {
-    const res = await fetch(`https://registry.npmjs.org/bloby-bot/latest?_t=${Date.now()}`, { headers: { 'Accept': 'application/json' } });
-    if (!res.ok) throw new Error();
+    const res = await fetch(`https://registry.npmjs.org/bloby-bot/latest?_t=${Date.now()}`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
     latest = await res.json();
-  } catch {
-    console.log(`  ${c.red}✗${c.reset}  Failed to check for updates\n`);
+  } catch (e) {
+    s.fail(`Failed to check for updates: ${e.message}`);
     process.exit(1);
   }
 
-  if (currentVersion === latest.version) {
-    console.log(`  ${c.blue}✔${c.reset}  Already up to date (v${currentVersion})\n`);
+  // <= covers registry lag too: never silently downgrade a locally-newer install.
+  if (compareVersions(latest.version, currentVersion) <= 0) {
+    s.succeed(`Already up to date (v${currentVersion})`);
+    commandsFooter();
     return;
   }
 
-  console.log(`  ${c.dim}v${currentVersion} → v${latest.version}${c.reset}\n`);
-
-  // When triggered by the supervisor (BLOBY_SELF_UPDATE=1), skip daemon stop/restart —
-  // the supervisor will exit after we finish, and the daemon manager restarts it.
-  const selfUpdate = !!process.env.BLOBY_SELF_UPDATE;
-  const daemonWasRunning = !selfUpdate && isDaemonInstalled() && isDaemonActive();
-
-  const updateConfig = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : {};
-  const updateTunnelMode = updateConfig.tunnel?.mode ?? (updateConfig.tunnel?.enabled === false ? 'off' : 'quick');
-  const updateHasTunnel = updateTunnelMode !== 'off';
-
-  const steps = [
-    'Downloading update',
-    ...(daemonWasRunning ? ['Stopping daemon'] : []),
-    'Updating files',
-    'Installing dependencies',
-    'Building interface',
-    ...(daemonWasRunning
-      ? ['Restarting daemon', ...(updateHasTunnel ? ['Connecting tunnel', 'Verifying connection'] : ['Verifying connection'])]
-      : []),
-  ];
+  s.succeed(`Found v${latest.version}  ${c.dim}(current: v${currentVersion})${c.reset}`);
 
-  const stepper = new Stepper(steps);
-  stepper.start();
+  const daemonWasRunning = !selfUpdate && isDaemonActive();
 
-  // Download tarball FIRST — before stopping daemon, so failure doesn't leave bot offline
-  const tarballUrl = latest.dist.tarball;
+  // Download tarball FIRST — before stopping the daemon, so failure doesn't leave the bot offline
+  const s2 = new Spinner().start('Downloading update...');
   const tmpDir = path.join(os.tmpdir(), `bloby-update-${Date.now()}`);
   fs.mkdirSync(tmpDir, { recursive: true });
   const tarball = path.join(tmpDir, 'bloby.tgz');
 
   try {
-    const res = await fetch(tarballUrl);
+    const res = await fetch(latest.dist.tarball, { signal: AbortSignal.timeout(300_000) });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
     const buf = Buffer.from(await res.arrayBuffer());
     fs.writeFileSync(tarball, buf);
     execSync(`tar xzf "${tarball}" -C "${tmpDir}"`, { stdio: 'ignore' });
   } catch (e) {
-    stepper.finish();
-    console.log(`\n  ${c.red}✗${c.reset}  Download failed: ${e.message}\n`);
+    s2.fail(`Download failed: ${e.message}`);
     fs.rmSync(tmpDir, { recursive: true, force: true });
     process.exit(1);
   }
-  stepper.advance();
+  s2.succeed('Downloaded.');
 
-  // Stop daemon AFTER download succeeds — minimizes downtime
-  // Skipped during self-update (supervisor handles restart via process exit)
+  // Stop the daemon AFTER the download succeeds — minimizes downtime.
+  // Skipped during self-update (the supervisor handles its own relaunch).
+  // A failed stop is fatal: copying new files under a running old version
+  // leaves a half-upgraded install serving live traffic.
   if (daemonWasRunning) {
-    try {
-      if (PLATFORM === 'darwin') {
-        execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-      } else {
-        const cmd = needsSudo() ? `sudo systemctl stop ${SERVICE_NAME}` : `systemctl stop ${SERVICE_NAME}`;
-        execSync(cmd, { stdio: 'ignore' });
-      }
-    } catch (e) {
-      console.log(`  ${c.yellow}⚠${c.reset}  Could not stop daemon: ${e.message}`);
+    const s3 = new Spinner().start('Stopping Bloby...');
+    const stopped = await stopCore({ spinner: s3 }); // also sweeps stray supervisors so an old instance can't answer the post-update health check
+    if (!stopped.ok) {
+      s3.fail(`Could not stop Bloby: ${stopped.error}`);
+      console.log(`     ${c.dim}Stop it manually, then re-run ${c.reset}${c.blue}bloby update${c.reset}${c.dim}.${c.reset}\n`);
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      process.exit(1);
     }
-    stepper.advance();
+    s3.succeed('Stopped.');
   }
 
   const extracted = path.join(tmpDir, 'package');
+  const s4 = new Spinner().start('Updating files...');
 
   // Update code directories (preserve workspace/ user data)
   try {
@@ -1517,6 +2185,32 @@ async function update() {
       }
     }
 
+    // Always update framework files that ship with each version.
+    // These are not user-editable — user code lives in src/components/, src/pages/, backend/, etc.
+    const frameworkFiles = [
+      'workspace/client/index.html',   // splash screen, SW registration, meta tags
+      'workspace/client/src/main.tsx', // React entry point, app-ready signal
+    ];
+    for (const rel of frameworkFiles) {
+      const src = path.join(extracted, rel);
+      const dst = path.join(DATA_DIR, rel);
+      if (fs.existsSync(src)) {
+        fs.cpSync(src, dst, { force: true });
+      }
+    }
+
+    // Always update public assets that ship with the framework (animation spritesheet, icons).
+    // Only copy specific files — never overwrite user-added public assets.
+    const frameworkAssets = ['spritesheet.webp', 'headphones_spritesheet.webp'];
+    const publicSrc = path.join(extracted, 'workspace', 'client', 'public');
+    const publicDst = path.join(DATA_DIR, 'workspace', 'client', 'public');
+    for (const asset of frameworkAssets) {
+      const src = path.join(publicSrc, asset);
+      if (fs.existsSync(src)) {
+        fs.cpSync(src, path.join(publicDst, asset), { force: true });
+      }
+    }
+
     // Update code files (never touches config.json, memory.db, etc.)
     for (const file of ['package.json', 'vite.config.ts', 'vite.bloby.config.ts', 'tsconfig.json', 'postcss.config.js', 'components.json']) {
       const src = path.join(extracted, file);
@@ -1533,12 +2227,11 @@ async function update() {
       fs.cpSync(distSrc, dst, { recursive: true });
     }
   } catch (e) {
-    console.log(`  ${c.red}✗${c.reset}  File copy failed: ${e.message}`);
+    s4.fail(`File copy failed: ${e.message}`);
     fs.rmSync(tmpDir, { recursive: true, force: true });
     process.exit(1);
   }
-
-  stepper.advance();
+  s4.succeed('Files updated.');
 
   const distDst = path.join(DATA_DIR, 'dist-bloby');
 
@@ -1546,34 +2239,40 @@ async function update() {
   // A failed install while new source files are already in place leaves the
   // app permanently broken (e.g. crash loop on a new import). Treat as fatal,
   // surface the npm output so the cause is debuggable, and don't claim success.
+  const s5 = new Spinner().start('Installing dependencies...');
   try {
     ensureNpmrc(DATA_DIR);
     execSync('npm install --omit=dev', { cwd: DATA_DIR, stdio: 'pipe', timeout: 300_000 });
   } catch (e) {
+    s5.stopRaw();
     if (e.stdout) process.stderr.write(e.stdout);
     if (e.stderr) process.stderr.write(e.stderr);
-    console.log(`\n  ${c.red}✗${c.reset}  npm install failed during update: ${e.message}`);
-    console.log(`    Your install is now partially upgraded. To recover:\n      cd ~/.bloby && npm install --omit=dev\n`);
+    console.log(`\n  ${GLYPH.err}  npm install failed during update: ${e.message}`);
+    console.log('     Your install is now partially upgraded. To recover:\n       cd ~/.bloby && npm install --omit=dev\n');
     fs.rmSync(tmpDir, { recursive: true, force: true });
     process.exit(1);
   }
   const stillMissing = missingDeps(DATA_DIR);
   if (stillMissing.length > 0) {
-    console.log(`\n  ${c.red}✗${c.reset}  npm install reported success but these deps are missing: ${stillMissing.join(', ')}`);
-    console.log(`    Try: cd ~/.bloby && rm -rf node_modules package-lock.json && npm install --omit=dev\n`);
+    s5.stopRaw();
+    console.log(`\n  ${GLYPH.err}  npm install reported success but these deps are missing: ${stillMissing.join(', ')}`);
+    console.log('     Try: cd ~/.bloby && rm -rf node_modules package-lock.json && npm install --omit=dev\n');
     fs.rmSync(tmpDir, { recursive: true, force: true });
     process.exit(1);
   }
-  stepper.advance();
+  s5.succeed('Dependencies installed.');
 
   // Rebuild UI if not in tarball
   if (!fs.existsSync(path.join(distDst, 'onboard.html'))) {
+    const s6 = new Spinner().start('Building interface...');
     try {
       if (fs.existsSync(distDst)) fs.rmSync(distDst, { recursive: true });
       execSync('npm run build:bloby', { cwd: DATA_DIR, stdio: 'ignore', timeout: 300_000 });
-    } catch {}
+      s6.succeed('Interface built.');
+    } catch {
+      s6.warn('Interface build skipped — will build on first start.');
+    }
   }
-  stepper.advance();
 
   // Read release notes and write version before cleanup
   let releaseNotes = '';
@@ -1582,373 +2281,154 @@ async function update() {
     releaseNotes = newPkg.releaseNotes || '';
   } catch {}
   writeVersionFile(latest.version);
-
-  // Clean up
   fs.rmSync(tmpDir, { recursive: true, force: true });
 
-  // Restart daemon if it was running (skipped during self-update)
-  let updateResult = null;
-  if (daemonWasRunning) {
-    // Capture log offset before starting so we only detect new-session __READY__
-    const updateLogFile = path.join(LAUNCHD_LOG_DIR, 'bloby.log');
-    let updateLogOffset = 0;
-    if (PLATFORM === 'darwin' && fs.existsSync(updateLogFile)) {
-      try { updateLogOffset = fs.statSync(updateLogFile).size; } catch {}
-    }
-
-    try {
-      if (PLATFORM === 'darwin') {
-        execSync(`launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-      } else {
-        const cmd = needsSudo() ? `sudo systemctl start ${SERVICE_NAME}` : `systemctl start ${SERVICE_NAME}`;
-        execSync(cmd, { stdio: 'ignore' });
-      }
-    } catch {}
-    stepper.advance(); // Restarting daemon done
-
-    // Wait for daemon to become healthy and tunnel to connect
-    updateResult = await waitForDaemonHealth(stepper, updateConfig, updateHasTunnel, updateLogOffset);
-  }
-
-  stepper.finish();
-
-  console.log(`\n  ${c.blue}${c.bold}✔  Updated to v${latest.version}${c.reset}\n`);
+  console.log(`\n  ${c.pink}${c.bold}✔  Updated to v${latest.version}${c.reset}\n`);
 
   if (releaseNotes) {
     console.log(`  ${c.bold}${c.white}What's new:${c.reset}`);
     const notes = Array.isArray(releaseNotes) ? releaseNotes : [releaseNotes];
-    notes.forEach((note, i) => {
-      console.log(`  ${c.dim}${i + 1}.${c.reset} ${note}`);
-    });
+    notes.forEach((note, i) => console.log(`  ${c.dim}${i + 1}.${c.reset} ${note}`));
     console.log('');
   }
 
-  // During self-update, supervisor handles restart — just exit cleanly
+  // During self-update the supervisor handles its own relaunch — just exit 0.
   if (selfUpdate) {
-    console.log(`  Files updated — supervisor will restart with new version.\n`);
+    console.log('  Files updated — supervisor will restart onto the new version.\n');
     return;
   }
 
+  // Restart only if it was running before — update does not start a stopped bot.
   if (daemonWasRunning) {
-    if (updateResult && updateResult.healthOk) {
-      console.log(`  ${c.blue}✔${c.reset}  Daemon restarted with new version.`);
-      readyMessage(updateResult.tunnelUrl, updateResult.relayUrl);
+    const cfgNow = readConfig() || {};
+    const steps = new Steps(startStepTitles(cfgNow)).start();
+    const result = await startCore({ ui: steps });
+    if (result.ok && result.healthy) {
+      if (!result.tunnelFailed && (result.tunnelMode === 'off' || result.ready)) steps.finish();
+      else steps.fail();
+      printReadyBlock(result);
     } else {
-      console.log(`  ${c.yellow}⚠${c.reset}  Daemon may still be starting. Check ${c.pink}bloby daemon status${c.reset}\n`);
-    }
-  } else if (isDaemonInstalled()) {
-    try {
-      if (PLATFORM === 'darwin') {
-        execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null; launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-      } else {
-        const cmd = needsSudo() ? `sudo systemctl start ${SERVICE_NAME}` : `systemctl start ${SERVICE_NAME}`;
-        execSync(cmd, { stdio: 'ignore' });
-      }
-      console.log(`  ${c.blue}✔${c.reset}  Daemon started with new version.\n`);
-    } catch {
-      console.log(`  ${c.dim}Run ${c.reset}${c.pink}bloby daemon start${c.reset}${c.dim} to launch.${c.reset}\n`);
+      steps.fail(`Bloby may still be starting — check ${c.blue}bloby status${c.reset}.`);
     }
   } else {
-    console.log(`  ${c.dim}Run ${c.reset}${c.pink}bloby start${c.reset}${c.dim} to launch.${c.reset}\n`);
+    console.log(`  ${c.dim}Bloby was not running. Start it with ${c.reset}${c.blue}bloby start${c.reset}${c.dim} when ready.${c.reset}`);
   }
+  commandsFooter();
 }
 
-// ── Daemon ──
+// ── daemon (advanced; the useful actions alias the top-level commands) ──
+
+function printDaemonHelp() {
+  console.log(`\n  ${c.bold}bloby daemon <action>${c.reset}\n`);
+  console.log(`    ${c.blue}${'install'.padEnd(12)}${c.reset}Install the background service and start it`);
+  console.log(`    ${c.blue}${'start'.padEnd(12)}${c.reset}Same as ${c.dim}bloby start${c.reset}`);
+  console.log(`    ${c.blue}${'stop'.padEnd(12)}${c.reset}Same as ${c.dim}bloby stop${c.reset}`);
+  console.log(`    ${c.blue}${'restart'.padEnd(12)}${c.reset}Same as ${c.dim}bloby restart${c.reset}`);
+  console.log(`    ${c.blue}${'status'.padEnd(12)}${c.reset}Same as ${c.dim}bloby status${c.reset}`);
+  console.log(`    ${c.blue}${'logs'.padEnd(12)}${c.reset}Same as ${c.dim}bloby logs${c.reset}`);
+  console.log(`    ${c.blue}${'uninstall'.padEnd(12)}${c.reset}Remove the background service\n`);
+}
 
-async function daemon(sub) {
-  // Platform guard
+async function cmdDaemon(sub) {
   if (!hasDaemonSupport()) {
     const hint = PLATFORM === 'win32'
       ? 'Use Task Scheduler to keep Bloby running in the background.'
       : 'No supported daemon system found.';
-    console.log(`\n  ${c.yellow}⚠${c.reset}  Daemon mode is not supported on this platform.`);
+    console.log(`\n  ${GLYPH.warn}  Daemon mode is not supported on this platform.`);
     console.log(`  ${c.dim}${hint}${c.reset}\n`);
     process.exit(1);
   }
 
-  const action = sub || 'install';
-
-  // ── macOS (launchd) ──
-  if (PLATFORM === 'darwin') {
-    switch (action) {
-      case 'install': {
-        const dataDir = ROOT; // Uses REPO_ROOT in dev, DATA_DIR (~/.bloby) in production
-        if (!fs.existsSync(path.join(dataDir, 'supervisor', 'index.ts'))) {
-          console.log(`\n  ${c.red}✗${c.reset}  Run ${c.pink}bloby init${c.reset} first.\n`);
-          process.exit(1);
-        }
-
-        // Unload existing plist if loaded
-        if (isLaunchdInstalled()) {
-          try { execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
-        }
-
-        const nodePath = process.env.BLOBY_NODE_PATH || process.execPath;
-        const plist = generateLaunchdPlist({ nodePath, dataDir });
-
-        // Ensure LaunchAgents directory exists
-        fs.mkdirSync(path.dirname(LAUNCHD_PLIST_PATH), { recursive: true });
-        fs.writeFileSync(LAUNCHD_PLIST_PATH, plist);
-        execSync(`launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-
-        // Verify it started
-        await new Promise((r) => setTimeout(r, 2000));
-        if (isLaunchdActive()) {
-          console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon installed and running.`);
-          console.log(`  ${c.dim}It will auto-start on login.${c.reset}`);
-          console.log(`\n  ${c.dim}View logs:${c.reset}  ${c.pink}bloby daemon logs${c.reset}`);
-          console.log(`  ${c.dim}Stop:${c.reset}       ${c.pink}bloby daemon stop${c.reset}`);
-          console.log(`  ${c.dim}Uninstall:${c.reset}  ${c.pink}bloby daemon uninstall${c.reset}\n`);
-        } else {
-          console.log(`\n  ${c.yellow}⚠${c.reset}  Plist installed but process may not be running.`);
-          console.log(`  ${c.dim}Check with: ${c.reset}${c.pink}bloby daemon status${c.reset}\n`);
-        }
-        break;
-      }
-
-      case 'stop': {
-        if (!isLaunchdInstalled()) {
-          console.log(`\n  ${c.yellow}⚠${c.reset}  Daemon not installed. Run ${c.pink}bloby daemon install${c.reset} first.\n`);
-          process.exit(1);
-        }
-        execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-        console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon stopped.\n`);
-        break;
-      }
-
-      case 'start': {
-        if (!isLaunchdInstalled()) {
-          console.log(`\n  ${c.yellow}⚠${c.reset}  Daemon not installed. Run ${c.pink}bloby daemon install${c.reset} first.\n`);
-          process.exit(1);
-        }
-        // Reload: unload first in case it's already loaded, then load
-        try { execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
-        execSync(`launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-        console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon started.\n`);
-        break;
-      }
-
-      case 'restart': {
-        if (!isLaunchdInstalled()) {
-          console.log(`\n  ${c.yellow}⚠${c.reset}  Daemon not installed. Run ${c.pink}bloby daemon install${c.reset} first.\n`);
-          process.exit(1);
-        }
-
-        banner();
-
-        const restartConfig = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : {};
-        const restartTunnelMode = restartConfig.tunnel?.mode ?? (restartConfig.tunnel?.enabled === false ? 'off' : 'quick');
-        const restartHasTunnel = restartTunnelMode !== 'off';
-
-        const restartSteps = [
-          'Stopping daemon',
-          'Starting daemon',
-          ...(restartHasTunnel ? ['Connecting tunnel', 'Verifying connection'] : ['Verifying connection']),
-        ];
-        const restartStepper = new Stepper(restartSteps);
-        restartStepper.start();
-
-        try { execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
-        restartStepper.advance(); // Stopping daemon done
-
-        // Capture log offset between stop and start so we only see new session output
-        const restartLogFile = path.join(LAUNCHD_LOG_DIR, 'bloby.log');
-        let restartLogOffset = 0;
-        if (fs.existsSync(restartLogFile)) {
-          try { restartLogOffset = fs.statSync(restartLogFile).size; } catch {}
-        }
-
-        execSync(`launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-        restartStepper.advance(); // Starting daemon done
+  switch (sub) {
+    case undefined:
+    case 'help':
+      printDaemonHelp();
+      commandsFooter();
+      return;
 
-        const restartResult = await waitForDaemonHealth(restartStepper, restartConfig, restartHasTunnel, restartLogOffset);
-        restartStepper.finish();
-
-        console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon restarted.`);
-        readyMessage(restartResult.tunnelUrl, restartResult.relayUrl);
-        break;
-      }
-
-      case 'status': {
-        if (!isLaunchdInstalled()) {
-          console.log(`\n  ${c.dim}●${c.reset} Daemon not installed.\n`);
-          break;
-        }
-        const active = isLaunchdActive();
-        if (active) {
-          console.log(`\n  ${c.blue}●${c.reset} Bloby daemon is running.`);
-        } else {
-          console.log(`\n  ${c.dim}●${c.reset} Bloby daemon is stopped.`);
-        }
-        console.log(`  ${c.dim}Plist:${c.reset} ${LAUNCHD_PLIST_PATH}`);
-        console.log(`  ${c.dim}Logs:${c.reset}  ${LAUNCHD_LOG_DIR}/bloby.log\n`);
-        break;
-      }
-
-      case 'logs': {
-        const logFile = path.join(LAUNCHD_LOG_DIR, 'bloby.log');
-        if (!fs.existsSync(logFile)) {
-          console.log(`\n  ${c.dim}No logs found at ${logFile}${c.reset}\n`);
-          break;
-        }
-        spawnSync('tail', ['-f', '-n', '50', logFile], { stdio: 'inherit' });
-        break;
-      }
-
-      case 'uninstall': {
-        try { execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
-        if (fs.existsSync(LAUNCHD_PLIST_PATH)) fs.unlinkSync(LAUNCHD_PLIST_PATH);
-        console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon uninstalled.\n`);
-        break;
+    case 'install': {
+      if (!fs.existsSync(path.join(ROOT, 'supervisor', 'index.ts'))) {
+        console.log(`\n  ${GLYPH.err}  Run ${c.blue}bloby init${c.reset} first.\n`);
+        process.exit(1);
       }
-
-      default:
-        console.log(`\n  ${c.red}✗${c.reset}  Unknown daemon command: ${action}`);
-        console.log(`  ${c.dim}Available: install, start, stop, restart, status, logs, uninstall${c.reset}\n`);
+      console.log('');
+      const s = new Spinner().start('Installing service...');
+      await ensureCloudflared(s);
+      const installed = installServiceFiles({ spinner: s });
+      if (!installed.ok) {
+        s.fail(`Failed to install service: ${installed.error}`);
+        commandsFooter();
         process.exit(1);
-    }
-    return;
-  }
-
-  // ── Linux (systemd) ──
-
-  // Check systemd is available
-  try {
-    execSync('systemctl --version', { stdio: 'ignore' });
-  } catch {
-    console.log(`\n  ${c.red}✗${c.reset}  systemd not found. Daemon mode requires systemd.\n`);
-    process.exit(1);
-  }
-
-  switch (action) {
-    case 'install': {
-      if (!fs.existsSync(path.join(getRealHome(), '.bloby', 'supervisor', 'index.ts'))) {
-        console.log(`\n  ${c.red}✗${c.reset}  Run ${c.pink}bloby init${c.reset} first.\n`);
+      }
+      const started = startDaemonService({ spinner: s });
+      if (!started.ok) {
+        s.fail(`Service installed but failed to start: ${started.error}`);
+        commandsFooter();
         process.exit(1);
       }
-
-      // Re-exec with sudo if needed
-      if (needsSudo()) sudoReExec();
-
-      const user = getRealUser();
-      const home = getRealHome();
-      const nodePath = process.env.BLOBY_NODE_PATH || process.execPath;
-      const dataDir = path.join(home, '.bloby');
-
-      const unit = generateUnitFile({ user, home, nodePath, dataDir });
-      fs.writeFileSync(SERVICE_PATH, unit);
-
-      execSync('systemctl daemon-reload', { stdio: 'ignore' });
-      execSync(`systemctl enable ${SERVICE_NAME}`, { stdio: 'ignore' });
-      execSync(`systemctl start ${SERVICE_NAME}`, { stdio: 'ignore' });
-
-      // Verify it started
-      await new Promise((r) => setTimeout(r, 2000));
-      if (isServiceActive()) {
-        console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon installed and running.`);
-        console.log(`  ${c.dim}It will auto-start on boot.${c.reset}`);
-        console.log(`\n  ${c.dim}View logs:${c.reset}  ${c.pink}bloby daemon logs${c.reset}`);
-        console.log(`  ${c.dim}Stop:${c.reset}       ${c.pink}bloby daemon stop${c.reset}`);
-        console.log(`  ${c.dim}Uninstall:${c.reset}  ${c.pink}bloby daemon uninstall${c.reset}\n`);
+      // Verify the process actually appears (no fixed sleep — poll briefly).
+      let pid = null;
+      for (let i = 0; i < 20; i++) {
+        pid = daemonPid();
+        if (pid) break;
+        await new Promise(r => setTimeout(r, 500));
+      }
+      if (pid) {
+        s.succeed(`Service installed and running ${c.dim}(PID ${pid})${c.reset}. Auto-starts on ${PLATFORM === 'darwin' ? 'login' : 'boot'}.`);
       } else {
-        console.log(`\n  ${c.yellow}⚠${c.reset}  Service installed but may not be running.`);
-        console.log(`  ${c.dim}Check with: ${c.reset}${c.pink}bloby daemon status${c.reset}\n`);
+        s.warn(`Service installed but the process has not appeared yet — check ${c.blue}bloby status${c.reset}.`);
       }
-      break;
-    }
-
-    case 'stop': {
-      if (needsSudo()) sudoReExec();
-      execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: 'inherit' });
-      console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon stopped.\n`);
-      break;
+      commandsFooter();
+      return;
     }
 
-    case 'start': {
-      if (needsSudo()) sudoReExec();
-      execSync(`systemctl start ${SERVICE_NAME}`, { stdio: 'inherit' });
-      console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon started.\n`);
-      break;
-    }
-
-    case 'restart': {
-      if (needsSudo()) sudoReExec();
-
-      banner();
-
-      const sysRestartConfig = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : {};
-      const sysRestartTunnelMode = sysRestartConfig.tunnel?.mode ?? (sysRestartConfig.tunnel?.enabled === false ? 'off' : 'quick');
-      const sysRestartHasTunnel = sysRestartTunnelMode !== 'off';
-
-      const sysRestartSteps = [
-        'Stopping daemon',
-        'Starting daemon',
-        ...(sysRestartHasTunnel ? ['Connecting tunnel', 'Verifying connection'] : ['Verifying connection']),
-      ];
-      const sysRestartStepper = new Stepper(sysRestartSteps);
-      sysRestartStepper.start();
-
-      execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: 'ignore' });
-      sysRestartStepper.advance(); // Stopping daemon done
-
-      execSync(`systemctl start ${SERVICE_NAME}`, { stdio: 'ignore' });
-      sysRestartStepper.advance(); // Starting daemon done
-
-      // Linux: no log file offset, falls back to local health check
-      const sysRestartResult = await waitForDaemonHealth(sysRestartStepper, sysRestartConfig, sysRestartHasTunnel, 0);
-      sysRestartStepper.finish();
-
-      console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon restarted.`);
-      readyMessage(sysRestartResult.tunnelUrl, sysRestartResult.relayUrl);
-      break;
-    }
-
-    case 'status': {
-      spawnSync('systemctl', ['status', SERVICE_NAME], { stdio: 'inherit' });
-      break;
-    }
-
-    case 'logs': {
-      spawnSync('journalctl', ['-u', SERVICE_NAME, '-f', '-n', '50'], { stdio: 'inherit' });
-      break;
-    }
+    case 'start': return cmdStart();
+    case 'stop': return cmdStop();
+    case 'restart': return cmdRestart();
+    case 'status': return cmdStatus();
+    case 'logs': return cmdLogs();
 
     case 'uninstall': {
-      if (needsSudo()) sudoReExec();
-      try { execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: 'ignore' }); } catch {}
-      try { execSync(`systemctl disable ${SERVICE_NAME}`, { stdio: 'ignore' }); } catch {}
-      if (fs.existsSync(SERVICE_PATH)) fs.unlinkSync(SERVICE_PATH);
-      execSync('systemctl daemon-reload', { stdio: 'ignore' });
-      console.log(`\n  ${c.blue}✔${c.reset}  Bloby daemon uninstalled.\n`);
-      break;
+      console.log('');
+      const s = new Spinner().start('Uninstalling service...');
+      await stopDaemonService();
+      await killStraySupervisors();
+      if (PLATFORM === 'darwin') {
+        if (fs.existsSync(LAUNCHD_PLIST_PATH)) fs.unlinkSync(LAUNCHD_PLIST_PATH);
+      } else if (PLATFORM === 'linux') {
+        runPrivileged(['systemctl', 'disable', SERVICE_NAME], { spinner: s });
+        runPrivileged(['rm', '-f', SERVICE_PATH], { spinner: s });
+        runPrivileged(['systemctl', 'daemon-reload'], { spinner: s });
+      }
+      s.succeed('Service uninstalled.');
+      commandsFooter();
+      return;
     }
 
     default:
-      console.log(`\n  ${c.red}✗${c.reset}  Unknown daemon command: ${action}`);
-      console.log(`  ${c.dim}Available: install, start, stop, restart, status, logs, uninstall${c.reset}\n`);
-      process.exit(1);
+      console.log(`\n  ${GLYPH.err}  Unknown daemon action: ${c.bold}${sub}${c.reset}`);
+      printDaemonHelp();
+      process.exit(2);
   }
 }
 
-// ── Tunnel management ──
-
-function ask(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
-}
+// ── tunnel ──
 
-async function tunnel(sub) {
+async function cmdTunnel(sub) {
   const action = sub || 'status';
 
   switch (action) {
     case 'setup': {
       banner();
+      if (!process.stdin.isTTY) {
+        console.log(`\n  ${GLYPH.err}  Tunnel setup is interactive — run it from a terminal.\n`);
+        process.exit(1);
+      }
       console.log(`\n  ${c.bold}${c.white}Named Tunnel Setup${c.reset}`);
 
       const setup = await runNamedTunnelSetup();
 
-      // Update bloby config
-      const config = fs.existsSync(CONFIG_PATH) ? JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')) : {};
+      const config = readConfig() || {};
       config.tunnel = {
         mode: 'named',
         name: setup.tunnelName,
@@ -1956,83 +2436,75 @@ async function tunnel(sub) {
         configPath: setup.cfConfigPath,
       };
       fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
-      console.log(`  ${c.blue}✔${c.reset}  Bloby config updated\n`);
+      console.log(`  ${GLYPH.ok}  Bloby config updated\n`);
 
-      // Offer restart if daemon is running
-      if (isDaemonInstalled() && isDaemonActive()) {
-        const restart = await ask(`  ${c.bold}Restart daemon now?${c.reset} ${c.dim}(Y/n)${c.reset}: `);
+      if (isDaemonActive()) {
+        const restart = await ask(`  ${c.bold}Restart Bloby now?${c.reset} ${c.dim}(Y/n)${c.reset}: `);
         if (!restart || restart.toLowerCase() === 'y') {
-          try {
-            if (PLATFORM === 'darwin') {
-              execSync(`launchctl unload "${LAUNCHD_PLIST_PATH}" 2>/dev/null; launchctl load "${LAUNCHD_PLIST_PATH}"`, { stdio: 'ignore' });
-            } else {
-              const cmd = needsSudo() ? `sudo systemctl restart ${SERVICE_NAME}` : `systemctl restart ${SERVICE_NAME}`;
-              execSync(cmd, { stdio: 'ignore' });
-            }
-            console.log(`\n  ${c.blue}✔${c.reset}  Daemon restarted.\n`);
-          } catch {
-            console.log(`\n  ${c.yellow}⚠${c.reset}  Restart failed. Try ${c.pink}bloby daemon restart${c.reset}\n`);
-          }
+          return cmdRestart();
         }
       } else {
-        console.log(`  ${c.dim}Run ${c.reset}${c.pink}bloby start${c.reset}${c.dim} to launch with the named tunnel.${c.reset}\n`);
+        console.log(`  ${c.dim}Run ${c.reset}${c.blue}bloby start${c.reset}${c.dim} to launch with the named tunnel.${c.reset}\n`);
       }
-      break;
+      commandsFooter();
+      return;
     }
 
     case 'status': {
       if (!fs.existsSync(CONFIG_PATH)) {
-        console.log(`\n  ${c.dim}No config found. Run ${c.reset}${c.pink}bloby init${c.reset}${c.dim} first.${c.reset}\n`);
+        console.log(`\n  ${c.dim}No config found. Run ${c.reset}${c.blue}bloby init${c.reset}${c.dim} first.${c.reset}`);
+        commandsFooter();
         return;
       }
-      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-      const mode = config.tunnel?.mode ?? (config.tunnel?.enabled === false ? 'off' : 'quick');
+      const config = readConfig() || {};
+      const mode = tunnelModeOf(config);
 
       console.log(`\n  ${c.bold}${c.white}Tunnel Configuration${c.reset}\n`);
-      console.log(`  ${c.dim}Mode:${c.reset}    ${c.bold}${mode}${c.reset}`);
+      console.log(`  ${c.dim}${'Mode'.padEnd(9)}${c.reset}${c.bold}${mode}${c.reset}`);
       if (mode === 'named') {
-        if (config.tunnel?.name) console.log(`  ${c.dim}Name:${c.reset}    ${config.tunnel.name}`);
-        if (config.tunnel?.domain) console.log(`  ${c.dim}Domain:${c.reset}  ${c.pink}${config.tunnel.domain}${c.reset}`);
-        if (config.tunnel?.configPath) console.log(`  ${c.dim}Config:${c.reset}  ${config.tunnel.configPath}`);
+        if (config.tunnel?.name) console.log(`  ${c.dim}${'Name'.padEnd(9)}${c.reset}${config.tunnel.name}`);
+        if (config.tunnel?.domain) console.log(`  ${c.dim}${'Domain'.padEnd(9)}${c.reset}${c.pink}${config.tunnel.domain}${c.reset}`);
+        if (config.tunnel?.configPath) console.log(`  ${c.dim}${'Config'.padEnd(9)}${c.reset}${config.tunnel.configPath}`);
       }
       if (config.tunnelUrl) {
-        console.log(`  ${c.dim}URL:${c.reset}     ${c.blue}${link(config.tunnelUrl)}${c.reset}`);
+        console.log(`  ${c.dim}${'URL'.padEnd(9)}${c.reset}${c.blue}${link(config.tunnelUrl)}${c.reset}`);
       }
-      console.log('');
-      break;
+      commandsFooter();
+      return;
     }
 
     case 'reset': {
       if (!fs.existsSync(CONFIG_PATH)) {
-        console.log(`\n  ${c.dim}No config found. Run ${c.reset}${c.pink}bloby init${c.reset}${c.dim} first.${c.reset}\n`);
+        console.log(`\n  ${c.dim}No config found. Run ${c.reset}${c.blue}bloby init${c.reset}${c.dim} first.${c.reset}`);
+        commandsFooter();
         return;
       }
-      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+      const config = readConfig() || {};
       config.tunnel = { mode: 'quick' };
       delete config.tunnelUrl;
       fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
-      console.log(`\n  ${c.blue}✔${c.reset}  Tunnel mode reset to ${c.bold}quick${c.reset} (random trycloudflare.com URL).\n`);
-
-      if (isDaemonInstalled() && isDaemonActive()) {
-        console.log(`  ${c.dim}Restart the daemon to apply: ${c.reset}${c.pink}bloby daemon restart${c.reset}\n`);
+      console.log(`\n  ${GLYPH.ok}  Tunnel mode reset to ${c.bold}quick${c.reset} (random trycloudflare.com URL).`);
+      if (isDaemonActive()) {
+        console.log(`  ${c.dim}Restart to apply: ${c.reset}${c.blue}bloby restart${c.reset}`);
       }
-      break;
+      commandsFooter();
+      return;
     }
 
     default:
-      console.log(`\n  ${c.red}✗${c.reset}  Unknown tunnel command: ${action}`);
+      console.log(`\n  ${GLYPH.err}  Unknown tunnel command: ${c.bold}${action}${c.reset}`);
       console.log(`  ${c.dim}Available: setup, status, reset${c.reset}\n`);
-      process.exit(1);
+      process.exit(2);
   }
 }
 
 // ── Password Reset ──
 
-async function passwordReset() {
+async function cmdPasswordReset() {
   const DB_PATH = path.join(DATA_DIR, 'memory.db');
 
   if (!fs.existsSync(DB_PATH)) {
-    console.log(`\n  ${c.red}✗${c.reset}  No database found. Run ${c.pink}bloby init${c.reset} and complete setup first.\n`);
+    console.log(`\n  ${GLYPH.err}  No database found. Run ${c.blue}bloby init${c.reset} and complete setup first.\n`);
     process.exit(1);
   }
 
@@ -2051,15 +2523,15 @@ async function passwordReset() {
 
   db.close();
 
-  console.log(`\n  ${c.blue}✔${c.reset}  Password reset successful.\n`);
-  console.log(`  ${c.dim}The onboard wizard will appear on your next visit`);
-  console.log(`  so you can create a new password.${c.reset}\n`);
+  console.log(`\n  ${GLYPH.ok}  Password reset successful.`);
+  console.log(`  ${c.dim}The onboard wizard will appear on your next visit so you can create a new password.${c.reset}`);
 
-  // Auto-restart daemon if it's running
-  if (isDaemonInstalled() && isDaemonActive()) {
-    console.log(`  ${c.dim}Restarting Bloby daemon...${c.reset}`);
-    daemon('restart');
+  // Restart so the running supervisor drops cached sessions
+  if (isDaemonActive()) {
+    console.log('');
+    return cmdRestart();
   }
+  commandsFooter();
 }
 
 // ── x402 (Base mainnet payment client) ──
@@ -2096,7 +2568,7 @@ async function ensureX402Module() {
         { cwd: toolsDir, stdio: 'inherit' },
       );
     } catch {
-      console.error(`  ${c.red}✗${c.reset}  Failed to install x402-fetch. Check network and retry.`);
+      console.error(`  ${GLYPH.err}  Failed to install x402-fetch. Check network and retry.`);
       process.exit(1);
     }
   }
@@ -2104,7 +2576,7 @@ async function ensureX402Module() {
   return import(pathToFileURL(installed).href);
 }
 
-async function x402Pay(rest) {
+async function cmdX402(rest) {
   if (!rest.length || rest.includes('-h') || rest.includes('--help')) {
     console.log(`
   ${c.bold}bloby x402 <url> [options]${c.reset}
@@ -2126,8 +2598,8 @@ async function x402Pay(rest) {
     process.exit(rest.length ? 0 : 1);
   }
 
-  const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
-  if (!cfg.wallet?.privateKey) {
+  const cfg = readConfig();
+  if (!cfg?.wallet?.privateKey) {
     console.error('  ✗  No wallet found in ~/.bloby/config.json. Run `bloby init` first.');
     process.exit(1);
   }
@@ -2194,19 +2666,28 @@ async function x402Pay(rest) {
   }
 }
 
-// ── Route ──
+// ── Router (strict: only known commands run; anything else errors with a hint) ──
 
 switch (command) {
-  case 'init':    init(); break;
-  case 'start':   start(); break;
-  case 'stop':    daemon('stop'); break;
-  case 'logs':    daemon('logs'); break;
-  case 'status':  status(); break;
-  case 'update':  update(); break;
-  case 'daemon':  daemon(subcommand); break;
-  case 'tunnel':  tunnel(subcommand); break;
-  case 'password-reset': passwordReset(); break;
-  case 'x402':    x402Pay(args.slice(1)); break;
+  case undefined:
+    // Bare `bloby` — documented first-run UX: set up if new, otherwise start.
+    if (flags.has('--version') || flags.has('-v')) { console.log(pkg.version); break; }
+    if (flags.has('--help') || flags.has('-h')) { printHelp(); break; }
+    fs.existsSync(CONFIG_PATH) ? cmdStart() : cmdInit();
+    break;
+  case 'init':    cmdInit(); break;
+  case 'start':   cmdStart(); break;
+  case 'stop':    cmdStop(); break;
+  case 'restart': cmdRestart(); break;
+  case 'status':  cmdStatus(); break;
+  case 'logs':    cmdLogs(); break;
+  case 'update':  cmdUpdate(); break;
+  case 'daemon':  cmdDaemon(subcommand); break;
+  case 'tunnel':  cmdTunnel(subcommand); break;
+  case 'password-reset': cmdPasswordReset(); break;
+  case 'x402':    cmdX402(argv.slice(x402Index + 1)); break;
+  case 'help':    printHelp(); break;
+  case 'version': console.log(pkg.version); break;
   default:
-    fs.existsSync(CONFIG_PATH) ? start() : init();
+    unknownCommand(command);
 }