npm - nebula-treasury - Versions diffs - 0.1.0 - Mend

nebula-treasury 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/README.md +39 -0
package/bin/nebula +11 -0
package/package.json +65 -0
package/src/commands/_agents.ts +14 -0
package/src/commands/_unlock.ts +66 -0
package/src/commands/chat-telegram.ts +398 -0
package/src/commands/chat.tsx +1293 -0
package/src/commands/drain.ts +90 -0
package/src/commands/gateway-logs.ts +49 -0
package/src/commands/gateway-run.ts +42 -0
package/src/commands/gateway-start.ts +216 -0
package/src/commands/gateway-status.ts +90 -0
package/src/commands/gateway-stop.ts +133 -0
package/src/commands/gateway.ts +101 -0
package/src/commands/identity.ts +178 -0
package/src/commands/init/cost.ts +40 -0
package/src/commands/init/funding-gate.ts +64 -0
package/src/commands/init/model-picker.ts +25 -0
package/src/commands/init/operator-picker.ts +233 -0
package/src/commands/init/telegram-step.ts +245 -0
package/src/commands/init/wizard-state.ts +94 -0
package/src/commands/init.ts +439 -0
package/src/commands/logs.ts +37 -0
package/src/commands/model.ts +48 -0
package/src/commands/pairing-approve.ts +65 -0
package/src/commands/pairing-clear.ts +39 -0
package/src/commands/pairing-list.ts +55 -0
package/src/commands/pairing-revoke.ts +49 -0
package/src/commands/pairing.ts +81 -0
package/src/commands/status.ts +44 -0
package/src/commands/telegram-remove.ts +62 -0
package/src/commands/telegram-setup.ts +64 -0
package/src/commands/telegram-status.ts +87 -0
package/src/commands/telegram.ts +44 -0
package/src/config/load.ts +35 -0
package/src/config/render.ts +99 -0
package/src/index.ts +153 -0
package/src/ui/app.tsx +673 -0
package/src/ui/approval-summary.ts +32 -0
package/src/ui/markdown-parse.ts +219 -0
package/src/ui/markdown.tsx +37 -0
package/src/ui/state.ts +181 -0
package/src/util/bootstrap-mode.ts +25 -0
package/src/util/bootstrap-progress-box.ts +378 -0
package/src/util/cli-version.ts +28 -0
package/src/util/format.ts +11 -0
package/src/util/gateway-spawn.ts +125 -0
package/src/util/gateway-version.ts +154 -0
package/src/util/github-releases.ts +79 -0
package/src/util/profile-key.ts +25 -0
package/src/util/ref-resolver.ts +55 -0
package/src/util/silence-console.ts +40 -0
package/src/util/telegram-secrets.ts +218 -0

package/src/util/bootstrap-progress-box.ts ADDED Viewed

@@ -0,0 +1,378 @@
+/**
+ * Multi-line ANSI progress box for sandbox bootstrap. Replaces the single-line
+ * clack spinner across the launch + poll + /healthz window:
+ *
+ *   ╭─ bootstrap progress ────────────────────────╮
+ *   │  [00:00] launchScript uploaded to Daytona   │
+ *   │  [00:12] apt update                     ✓   │
+ *   │  [00:38] system deps installed          ✓   │
+ *   │  [01:04] bun runtime installed          ✓   │
+ *   │  [01:22] nebula 0.24.7 installed         ✓   │
+ *   │  [01:45] browser deps installed         ✓   │
+ *   │  [02:08] harness daemon spawned         ✓   │
+ *   │  [02:11] /healthz Ready                 ✓   │
+ *   ╰─────────────────────────────────────────────╯
+ *
+ * Rendering uses `\x1b[NA` (cursor up) + `\x1b[0J` (clear to end) to redraw
+ * the same N+2 lines in place. Falls back to per-transition lines (no ANSI)
+ * when stdout is not a TTY (CI, piped output).
+ */
+import { BOOTSTRAP_STAGE_MARKERS } from 'nebula-ai-gateway'
+const TIME_SLOT_WIDTH = 7
+const LABEL_WIDTH = 32
+const CONTENT_WIDTH = 45
+const FRAME_WIDTH = CONTENT_WIDTH + 2
+const SPINNER_FRAMES = ['◐', '◓', '◑', '◒'] as const
+export type BootstrapStageId =
+  | 'launch-upload'
+  | 'apt-update'
+  | 'system-deps'
+  | 'bun-install'
+  | 'nebula-install'
+  | 'browser-deps'
+  | 'harness-spawn'
+  | 'healthz-ready'
+export type BootstrapStageStatus = 'pending' | 'running' | 'done' | 'failed'
+const STAGE_ORDER: readonly BootstrapStageId[] = [
+  'launch-upload',
+  'apt-update',
+  'system-deps',
+  'bun-install',
+  'nebula-install',
+  'browser-deps',
+  'harness-spawn',
+  'healthz-ready',
+] as const
+const DEFAULT_LABELS: Record<BootstrapStageId, string> = {
+  'launch-upload': 'launchScript uploaded to Daytona',
+  'apt-update': 'apt update',
+  'system-deps': 'system deps installed',
+  'bun-install': 'bun runtime installed',
+  'nebula-install': 'nebula installed',
+  'browser-deps': 'browser deps installed',
+  'harness-spawn': 'harness daemon spawned',
+  'healthz-ready': '/healthz Ready',
+}
+interface StageState {
+  id: BootstrapStageId
+  label: string
+  status: BootstrapStageStatus
+  /** Seconds since box start when status transitioned to running. */
+  startedSec?: number
+  /** Seconds since box start when status transitioned to done/failed. */
+  endedSec?: number
+}
+export interface BootstrapProgressBoxOpts {
+  /** Box title. Defaults to "bootstrap progress". */
+  title?: string
+  /** Per-stage label override. Useful for injecting the version into nebula-install. */
+  labels?: Partial<Record<BootstrapStageId, string>>
+  /** Stream to write to. Defaults to process.stdout. */
+  out?: NodeJS.WritableStream & { isTTY?: boolean }
+}
+/**
+ * Map a raw STAGE marker (emitted by the gateway bootstrap script as
+ * `STAGE: <body>` and extracted by sandbox-provision's poll loop) to a stage
+ * id. Returns null for unknown markers; callers should treat unknown markers
+ * as informational, not as state transitions. Marker prefixes come from
+ * `BOOTSTRAP_STAGE_MARKERS` in the gateway package so renames stay in lockstep.
+ */
+export function mapBootstrapMarkerToStage(marker: string): BootstrapStageId | null {
+  const m = marker.trim()
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.aptUpdate)) return 'apt-update'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.systemDeps)) return 'system-deps'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.bunInstall)) return 'bun-install'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.nebulaInstall)) return 'nebula-install'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.browserDeps)) return 'browser-deps'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.harnessSpawn)) return 'harness-spawn'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.harnessReady)) return 'harness-spawn'
+  return null
+}
+export class BootstrapProgressBox {
+  private readonly title: string
+  private readonly out: NodeJS.WritableStream & { isTTY?: boolean }
+  private readonly useAnsi: boolean
+  private readonly stages: StageState[]
+  private startMs = 0
+  private tickIdx = 0
+  /** Number of lines we wrote the LAST time render() ran (so we know how
+   *  many to clear before the next render). Zero before the first render. */
+  private renderedLines = 0
+  /** Cleared on render — tracks last-printed status per stage in non-TTY mode. */
+  private readonly nonTtyLastPrinted = new Map<BootstrapStageId, BootstrapStageStatus>()
+  constructor(opts: BootstrapProgressBoxOpts = {}) {
+    this.title = opts.title ?? 'bootstrap progress'
+    this.out = opts.out ?? process.stdout
+    this.useAnsi = this.out.isTTY === true
+    this.stages = STAGE_ORDER.map(id => ({
+      id,
+      label: opts.labels?.[id] ?? DEFAULT_LABELS[id],
+      status: 'pending' as BootstrapStageStatus,
+    }))
+  }
+  start(): void {
+    this.startMs = Date.now()
+    if (!this.useAnsi) return
+    this.render()
+  }
+  /**
+   * Update one stage. When `status === 'running'`, every previously-running
+   * stage that hasn't transitioned to done/failed is auto-completed (the
+   * bash script is sequential, so a new stage starting implies the prior
+   * ones finished). Stages before the activated one that are still pending
+   * are also auto-completed — this handles conditional stages (e.g.
+   * bun-install gets skipped when bun is already in PATH).
+   */
+  markStage(id: BootstrapStageId, status: BootstrapStageStatus): void {
+    const sec = this.elapsedSec()
+    const idx = this.stages.findIndex(s => s.id === id)
+    if (idx < 0) return
+    if (status === 'running') {
+      for (let i = 0; i < idx; i++) {
+        const s = this.stages[i]!
+        if (s.status !== 'done' && s.status !== 'failed') {
+          s.status = 'done'
+          s.endedSec = sec
+        }
+      }
+      const target = this.stages[idx]!
+      if (target.status === 'pending') target.startedSec = sec
+      target.status = 'running'
+    } else {
+      const target = this.stages[idx]!
+      target.status = status
+      target.endedSec = sec
+      if (target.startedSec === undefined) target.startedSec = sec
+    }
+    this.tickIdx += 1
+    this.render()
+  }
+  /**
+   * Bump the spinner glyph + elapsed counter. Call every 1-5s while a
+   * running stage is in-flight to keep the visual alive even when no STAGE
+   * marker has arrived. No-op when the box hasn't started yet or when no
+   * stage is currently running.
+   */
+  tick(): void {
+    if (this.renderedLines === 0 && this.useAnsi) {
+      this.render()
+      return
+    }
+    this.tickIdx += 1
+    this.render()
+  }
+  /**
+   * Finalize the box. Marks any still-running stages as done (assumed
+   * complete; the upstream success signal is what triggered stop()), draws
+   * one final frame, and emits the trailing newline so subsequent CLI
+   * output (e.g. final spinner success line) starts cleanly below.
+   */
+  stop(): void {
+    const sec = this.elapsedSec()
+    for (const s of this.stages) {
+      if (s.status === 'running') {
+        s.status = 'done'
+        s.endedSec = sec
+      }
+    }
+    this.render()
+    if (this.useAnsi) this.out.write('\n')
+  }
+  /**
+   * Mark the box as aborted. Any running stage becomes failed; pending
+   * stages stay pending so the operator sees where bootstrap got stuck.
+   */
+  fail(): void {
+    const sec = this.elapsedSec()
+    for (const s of this.stages) {
+      if (s.status === 'running') {
+        s.status = 'failed'
+        s.endedSec = sec
+      }
+    }
+    this.render()
+    if (this.useAnsi) this.out.write('\n')
+  }
+  private elapsedSec(): number {
+    return Math.max(0, Math.round((Date.now() - this.startMs) / 1000))
+  }
+  private render(): void {
+    if (!this.useAnsi) {
+      this.renderNonTty()
+      return
+    }
+    const lines = this.buildLines()
+    if (this.renderedLines > 0) {
+      this.out.write(`\x1b[${this.renderedLines}A\x1b[0J`)
+    }
+    for (const line of lines) this.out.write(`${line}\n`)
+    this.renderedLines = lines.length
+  }
+  /**
+   * Non-TTY fallback: print one line per state change instead of a redrawn
+   * box. Tracks last-printed status per stage so re-renders don't spam.
+   */
+  private renderNonTty(): void {
+    for (const s of this.stages) {
+      const prev = this.nonTtyLastPrinted.get(s.id)
+      if (prev === s.status) continue
+      if (s.status === 'pending') continue
+      const tag =
+        s.status === 'done'
+          ? '[ok]'
+          : s.status === 'failed'
+            ? '[fail]'
+            : s.status === 'running'
+              ? '[..]'
+              : ''
+      const time =
+        s.status === 'running'
+          ? formatTime(s.startedSec ?? 0)
+          : formatTime(s.endedSec ?? this.elapsedSec())
+      this.out.write(`${tag} [${time}] ${s.label}\n`)
+      this.nonTtyLastPrinted.set(s.id, s.status)
+    }
+  }
+  private buildLines(): string[] {
+    const header = `╭─ ${this.title} ${'─'.repeat(FRAME_WIDTH - this.title.length - 5)}╮`
+    const footer = `╰${'─'.repeat(FRAME_WIDTH - 2)}╯`
+    const rows = this.stages.map(s => this.formatRow(s))
+    return [header, ...rows, footer]
+  }
+  private formatRow(s: StageState): string {
+    const timeText = pickTimeText(s)
+    const timeCol =
+      timeText === null ? ' '.repeat(TIME_SLOT_WIDTH) : `[${timeText}]`.padEnd(TIME_SLOT_WIDTH)
+    const labelText = truncate(s.label, LABEL_WIDTH).padEnd(LABEL_WIDTH)
+    const glyph = pickGlyph(s, this.tickIdx)
+    return `│  ${timeCol} ${labelText} ${glyph} │`
+  }
+}
+function pickTimeText(s: StageState): string | null {
+  if (s.status === 'pending') return null
+  const sec = s.status === 'running' ? (s.startedSec ?? 0) : (s.endedSec ?? s.startedSec ?? 0)
+  return formatTime(sec)
+}
+function formatTime(sec: number): string {
+  const m = Math.floor(sec / 60)
+  const s = sec % 60
+  return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+}
+function pickGlyph(s: StageState, tickIdx: number): string {
+  if (s.status === 'done') return '✓'
+  if (s.status === 'failed') return '✗'
+  if (s.status === 'running') return SPINNER_FRAMES[tickIdx % SPINNER_FRAMES.length]!
+  return ' '
+}
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s
+  return `${s.slice(0, max - 1)}…`
+}
+export const __testing = {
+  STAGE_ORDER,
+  DEFAULT_LABELS,
+  SPINNER_FRAMES,
+  formatTime,
+  truncate,
+}
+/**
+ * Lifecycle owner for the bootstrap progress UX. Wraps the clack spinner
+ * (which renders the pre-bootstrap phase: deposit + createSandbox) and a
+ * lazily-created `BootstrapProgressBox` (which renders the actual bootstrap
+ * stages). Encapsulates the takeover handoff so `init.ts` and `upgrade.ts`
+ * don't repeat the same `let box / spinnerStopped` dance.
+ */
+export interface ClackSpinnerLike {
+  message: (msg: string) => void
+  stop: (msg?: string, code?: number) => void
+}
+export interface BootstrapProgressControllerOpts {
+  spinner: ClackSpinnerLike
+  cliVersion: string
+  /** Text shown when the spinner stops + the box takes over (e.g. "sandbox started, running bootstrap"). */
+  startedMsg: string
+}
+export class BootstrapProgressController {
+  private box: BootstrapProgressBox | null = null
+  private spinnerStopped = false
+  private readonly spinner: ClackSpinnerLike
+  private readonly cliVersion: string
+  private readonly startedMsg: string
+  constructor(opts: BootstrapProgressControllerOpts) {
+    this.spinner = opts.spinner
+    this.cliVersion = opts.cliVersion
+    this.startedMsg = opts.startedMsg
+  }
+  onProgress = (msg: string): void => {
+    if (this.box) return
+    this.spinner.message(msg)
+  }
+  onStageEvent = (stage: BootstrapStageId, status: BootstrapStageStatus): void => {
+    if (!this.box) {
+      this.spinner.stop(this.startedMsg)
+      this.spinnerStopped = true
+      this.box = new BootstrapProgressBox({
+        labels: { 'nebula-install': `nebula ${this.cliVersion} installed` },
+      })
+      this.box.start()
+    }
+    this.box.markStage(stage, status)
+  }
+  onTick = (): void => {
+    this.box?.tick()
+  }
+  /** Box closes itself; success line printed via the caller's `emit` (typically `log.step`). */
+  finalize(successLine: string, emit: (msg: string) => void): void {
+    if (this.box) {
+      this.box.stop()
+      emit(successLine)
+    } else {
+      this.spinner.stop(successLine)
+    }
+  }
+  /** Box marks running stage as failed; error line printed via caller's `emit` (typically `log.error`). */
+  fail(errLine: string, emit: (msg: string) => void): void {
+    if (this.box) {
+      this.box.fail()
+      emit(errLine)
+    } else if (!this.spinnerStopped) {
+      this.spinner.stop(errLine)
+    }
+  }
+}

package/src/util/cli-version.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Resolve the CLI package's own version. Used by `nebula --version` and to pin
+ * the gateway version installed in sandbox containers (mode=npm) so the
+ * gateway matches the CLI.
+ *
+ * Reads package.json via a path relative to this module so it works in every
+ * install layout: monorepo workspace (where bare-specifier resolution of
+ * `nebula-ai-cli` doesn't include /package.json without an exports entry),
+ * `bun add -g` global install, and Bun's per-project content store.
+ */
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+export async function resolveCliVersion(): Promise<string> {
+  const here = fileURLToPath(import.meta.url)
+  const pkgPath = resolve(here, '../../../package.json')
+  try {
+    const raw = await readFile(pkgPath, 'utf-8')
+    const pkg = JSON.parse(raw) as { version?: unknown }
+    if (typeof pkg.version !== 'string') {
+      throw new Error('package.json missing version field')
+    }
+    return pkg.version
+  } catch (e) {
+    throw new Error(`cannot read CLI version from ${pkgPath}: ${(e as Error).message}`)
+  }
+}

package/src/util/format.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Truncate an EVM 0x-address to first 6 + last 4 (e.g. 0x1234…abcd) for
+ * compact UI rendering. Returns the input unchanged for short or non-0x
+ * values (e.g. an `.0g` name, `'?'`, or empty), so callers can pass any
+ * identifier without checking type first.
+ */
+export function shortAddr(addr?: string | null): string {
+  if (!addr) return '?'
+  if (!addr.startsWith('0x') || addr.length <= 12) return addr
+  return `${addr.slice(0, 6)}…${addr.slice(-4)}`
+}

package/src/util/gateway-spawn.ts ADDED Viewed

@@ -0,0 +1,125 @@
+/**
+ * v0.21.5 Bundle B: spawn-and-wait helper for the local gateway daemon.
+ *
+ * Two callers share this:
+ *   - `nebula gateway start` (interactive Touch ID flow → spawn detached)
+ *   - `nebula` chat fallback when no sock is present (auto-spawn before
+ *     embedded TUI fallthrough — see Bundle C / chat.tsx)
+ *
+ * The helper does NOT perform operator-session unlock. Callers that need a
+ * fresh session must run that path before invoking this. If the daemon dies
+ * during boot because no session exists, the sock never appears and we
+ * surface the failure as `{ ready: false, reason: 'timeout' }`.
+ */
+import { type ChildProcess, spawn } from 'node:child_process'
+import { existsSync, mkdirSync, openSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { agentPaths } from 'nebula-ai-core'
+export interface SpawnGatewayDaemonOpts {
+  agentId: string
+  configPath: string
+  socketPath: string
+  /** Max ms to wait for the unix sock to appear. Default 10_000. */
+  timeoutMs?: number
+  /**
+   * Where to send daemon stdout/stderr. Default 'log-file' which redirects
+   * to `~/.nebula/agents/<id>/gateway.log` (truncated on each boot) so
+   * detached daemon diagnostics survive the parent's exit. 'inherit' keeps
+   * the legacy behavior where output goes to the parent's tty (and vanishes
+   * on detach). 'ignore' drops everything.
+   */
+  stdio?: 'inherit' | 'ignore' | 'log-file'
+  /** Override the bin resolution (tests). */
+  binPath?: string
+  /** Override env (tests). */
+  env?: NodeJS.ProcessEnv
+}
+export interface SpawnGatewayDaemonResult {
+  ready: boolean
+  /** Detached child PID iff spawn succeeded (regardless of readiness). */
+  pid?: number
+  /** Reason populated on failure: 'spawn-failed' | 'timeout' | 'pre-existing'. */
+  reason?: 'spawn-failed' | 'timeout' | 'pre-existing'
+  /** First-line error message when spawn failed. */
+  error?: string
+}
+export function resolveLocalBin(): string {
+  const pkgUrl = import.meta.resolve('nebula-ai-gateway/package.json')
+  const pkgRoot = dirname(fileURLToPath(pkgUrl))
+  return join(pkgRoot, 'bin', 'nebula-gateway-local')
+}
+export async function spawnGatewayDaemon(
+  opts: SpawnGatewayDaemonOpts,
+): Promise<SpawnGatewayDaemonResult> {
+  if (existsSync(opts.socketPath)) {
+    return { ready: false, reason: 'pre-existing' }
+  }
+  const bin = opts.binPath ?? resolveLocalBin()
+  const env: NodeJS.ProcessEnv = {
+    ...(opts.env ?? process.env),
+    NEBULA_AGENT_ID: opts.agentId,
+    NEBULA_CONFIG: opts.configPath,
+  }
+  const stdioMode = opts.stdio ?? 'log-file'
+  // v0.21.12: when stdio is 'log-file' redirect daemon stdout+stderr to
+  // ~/.nebula/agents/<id>/gateway.log (truncate-on-restart). Pre-fix this
+  // helper used 'inherit' which sent output to the parent's tty; once the
+  // parent CLI returned, those handles vanished and operators couldn't see
+  // why the daemon misbehaved. Truncation is fine because operators rarely
+  // reboot the daemon mid-session and `nebula gateway logs -f` only follows
+  // the current invocation.
+  let stdioCfg: ['ignore', 'inherit' | 'ignore' | number, 'inherit' | 'ignore' | number]
+  if (stdioMode === 'log-file') {
+    const logPath = join(agentPaths.agent(opts.agentId).dir, 'gateway.log')
+    try {
+      mkdirSync(dirname(logPath), { recursive: true })
+      const fd = openSync(logPath, 'w') // truncate on each boot
+      stdioCfg = ['ignore', fd, fd]
+    } catch {
+      // If we can't open the log file (perm, disk), fall back to ignore so
+      // we still spawn cleanly. Operators lose diagnostics but the daemon
+      // boots.
+      stdioCfg = ['ignore', 'ignore', 'ignore']
+    }
+  } else {
+    stdioCfg = ['ignore', stdioMode, stdioMode]
+  }
+  let proc: ChildProcess
+  try {
+    proc = spawn('bun', [bin], {
+      env,
+      detached: true,
+      stdio: stdioCfg,
+    })
+    proc.unref()
+  } catch (err) {
+    return {
+      ready: false,
+      reason: 'spawn-failed',
+      error: (err as Error).message?.slice(0, 200),
+    }
+  }
+  const timeoutMs = opts.timeoutMs ?? 10_000
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(opts.socketPath)) {
+      return { ready: true, pid: proc.pid }
+    }
+    await new Promise(r => setTimeout(r, 200))
+  }
+  return {
+    ready: false,
+    pid: proc.pid,
+    reason: 'timeout',
+  }
+}

package/src/util/gateway-version.ts ADDED Viewed

@@ -0,0 +1,154 @@
+/**
+ * v0.23.2: detect and auto-heal version drift between the on-disk CLI binary
+ * and a running gateway daemon.
+ *
+ * Scenario this fixes:
+ *   1. Operator runs `bun add -g nebula-ai-cli@<new>` — global binary
+ *      swaps on disk.
+ *   2. The previously-running gateway daemon was spawned from the OLD binary
+ *      and pinned its node_modules at boot. `/healthz` reports the old version
+ *      forever.
+ *   3. Operator runs `nebula` (chat) or `nebula gateway start`. Without this
+ *      helper, chat.tsx re-attaches to the stale daemon — operator sees old
+ *      features for the entire daemon lifetime.
+ *
+ * With this helper: any caller that sees a pre-existing socket calls
+ * `ensureGatewayVersionMatchesCli` first, which fetches /healthz, compares
+ * versions, and if drift is detected: kills the old daemon, removes the
+ * stale socket, and returns 'restarted' so the caller respawns fresh.
+ */
+import { existsSync, readFileSync, unlinkSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+export interface VersionCheckOpts {
+  /** Path to the gateway's unix socket. */
+  socketPath: string
+  /** Path to the lockfile holding daemon pid (for SIGTERM). */
+  lockFile?: string
+  /** Override the on-disk CLI version (tests). */
+  cliVersion?: string
+  /** Override the fetch implementation (tests). */
+  fetchImpl?: typeof fetch
+  /** Max ms to wait after SIGTERM for the socket to disappear. Default 4000. */
+  killTimeoutMs?: number
+}
+export interface VersionCheckResult {
+  /** What we observed and did. */
+  action: 'ok' | 'restarted' | 'unreachable' | 'no-cli-version'
+  cliVersion?: string
+  daemonVersion?: string
+  /** Human-readable note for the operator. */
+  note?: string
+}
+/** Read the version baked into the nebula-ai-gateway package on disk. */
+export function readLocalGatewayVersion(): string | undefined {
+  try {
+    const pkgUrl = import.meta.resolve('nebula-ai-gateway/package.json')
+    const pkgPath = fileURLToPath(pkgUrl)
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string }
+    return pkg.version
+  } catch {
+    return undefined
+  }
+}
+/** Fetch /healthz over the unix socket. Returns the daemon's reported version. */
+export async function fetchDaemonVersion(
+  socketPath: string,
+  fetchImpl?: typeof fetch,
+): Promise<string | undefined> {
+  const f = fetchImpl ?? globalThis.fetch
+  try {
+    const r = await f('http://localhost/healthz', { unix: socketPath } as RequestInit & {
+      unix: string
+    })
+    if (!r.ok) return undefined
+    const body = (await r.json()) as { version?: string }
+    return body.version
+  } catch {
+    return undefined
+  }
+}
+/**
+ * Compare running-daemon version against on-disk CLI version. If they drift,
+ * SIGTERM the pid in the lockfile, wait up to killTimeoutMs for the socket
+ * to disappear, and return `action='restarted'` to signal the caller to
+ * spawn a fresh daemon.
+ *
+ * If versions match → `action='ok'`.
+ * If /healthz unreachable (zombie socket) → `action='unreachable'` after
+ * cleaning the stale socket file so the caller can spawn fresh.
+ * If on-disk CLI version cannot be resolved → `action='no-cli-version'`
+ * (skip check defensively).
+ */
+export async function ensureGatewayVersionMatchesCli(
+  opts: VersionCheckOpts,
+): Promise<VersionCheckResult> {
+  if (!existsSync(opts.socketPath)) {
+    return { action: 'ok', note: 'no socket; nothing to check' }
+  }
+  const cliVersion = opts.cliVersion ?? readLocalGatewayVersion()
+  if (!cliVersion) {
+    return {
+      action: 'no-cli-version',
+      note: 'could not resolve on-disk CLI version; skipping drift check',
+    }
+  }
+  const daemonVersion = await fetchDaemonVersion(opts.socketPath, opts.fetchImpl)
+  if (!daemonVersion) {
+    try {
+      unlinkSync(opts.socketPath)
+    } catch {}
+    return {
+      action: 'unreachable',
+      cliVersion,
+      note: 'daemon socket present but /healthz unreachable; removed stale socket',
+    }
+  }
+  if (daemonVersion === cliVersion) {
+    return { action: 'ok', cliVersion, daemonVersion }
+  }
+  // Drift detected. Kill the daemon via pid in lockfile.
+  let killedPid: number | undefined
+  if (opts.lockFile && existsSync(opts.lockFile)) {
+    try {
+      const parsed = JSON.parse(readFileSync(opts.lockFile, 'utf8')) as { pid?: number }
+      if (typeof parsed.pid === 'number') {
+        try {
+          process.kill(parsed.pid, 'SIGTERM')
+          killedPid = parsed.pid
+        } catch {}
+      }
+    } catch {}
+  }
+  // Wait for the socket to disappear (daemon exits, cleans up).
+  const killTimeoutMs = opts.killTimeoutMs ?? 4000
+  const deadline = Date.now() + killTimeoutMs
+  while (Date.now() < deadline && existsSync(opts.socketPath)) {
+    await new Promise(r => setTimeout(r, 100))
+  }
+  // If socket still here, force-remove it. The lockfile cleanup happens when
+  // the parent invokes spawnGatewayDaemon (which clears stale locks at boot).
+  if (existsSync(opts.socketPath)) {
+    try {
+      unlinkSync(opts.socketPath)
+    } catch {}
+  }
+  return {
+    action: 'restarted',
+    cliVersion,
+    daemonVersion,
+    note: `version drift: daemon=${daemonVersion} vs cli=${cliVersion}; killed pid=${killedPid ?? '?'}, socket cleaned`,
+  }
+}