nebula-treasury 0.1.0

package/src/commands/drain.ts

@@ -0,0 +1,90 @@
+import { cancel, confirm, intro, isCancel, log, outro, spinner } from '@clack/prompts'
+import { NETWORK_RPC, drainAgentEOA, explorerTxUrl } from 'nebula-ai-core'
+import { http, type Address, createPublicClient, formatEther, isAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { withSilencedConsole } from '../util/silence-console'
+import { unlockAgentSigner } from './_unlock'
+
+export interface DrainOpts {
+  /** Target address. If omitted, defaults to the operator wallet on this config. */
+  to?: string
+  /** Skip the destructive confirmation prompt. */
+  yes?: boolean
+}
+
+export async function runDrain(opts: DrainOpts): Promise<void> {
+  intro('nebula drain')
+
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    cancel('No nebula.config.ts found. Run `nebula init` first.')
+    return
+  }
+  const { config } = loaded
+  if (!config.identity.agent) {
+    cancel('Config has no agent. Run `nebula init` first.')
+    return
+  }
+
+  const network = config.network
+  const agentAddress = config.identity.agent as Address
+
+  const targetRaw = opts.to ?? (config.identity.operator as string | undefined)
+  if (!targetRaw) {
+    cancel('No --to address provided and config has no operator. Pass --to <0x...>.')
+    return
+  }
+  if (!isAddress(targetRaw)) {
+    cancel(`--to is not a valid address: ${targetRaw}`)
+    return
+  }
+  const to = targetRaw as Address
+
+  const publicClient = createPublicClient({ transport: http(NETWORK_RPC[network]) })
+  const before = await publicClient.getBalance({ address: agentAddress })
+  log.info(
+    [
+      `agent      ${agentAddress}`,
+      `balance    ${formatEther(before)} Mantle`,
+      `target     ${to}`,
+      `network    ${network}`,
+    ].join('\n'),
+  )
+
+  if (before === 0n) {
+    log.warn('Agent EOA already empty.')
+    outro('nothing to drain')
+    return
+  }
+
+  if (!opts.yes) {
+    const ok = (await confirm({
+      message: `Sweep agent EOA balance (${formatEther(before)} Mantle minus gas) to ${to}?`,
+      initialValue: false,
+    })) as boolean | symbol
+    if (isCancel(ok) || !ok) {
+      cancel('Aborted.')
+      return
+    }
+  }
+
+  const unlocked = await unlockAgentSigner(config)
+  if (!unlocked) return
+  try {
+    const sSweep = spinner()
+    sSweep.start(`Sweeping agent EOA → ${to}`)
+    try {
+      const result = await withSilencedConsole(() =>
+        drainAgentEOA({ network, privkeyHex: unlocked.agentPrivkey, to }),
+      )
+      sSweep.stop(
+        `swept ${formatEther(result.amountSent)} Mantle (gas reserved ${formatEther(result.gasReserved)} Mantle) → ${explorerTxUrl(network, result.txHash)}`,
+      )
+      outro(`agent ${agentAddress} drained to ${to}`)
+    } catch (e) {
+      sSweep.stop(`sweep failed: ${(e as Error).message.slice(0, 160)}`)
+    }
+  } finally {
+    await unlocked.close()
+  }
+}

package/src/commands/gateway-logs.ts

@@ -0,0 +1,49 @@
+/**
+ * `nebula gateway logs [--tail N] [-f]` — tail the gateway log.
+ *
+ * v0.19.x: gateway daemon logs to stdout/stderr only (inherited by `gateway run`
+ * or backgrounded by `gateway start`). v0.19.3 wires a log file at
+ * `~/.nebula/agents/<id>/gateway.log` for tailing. Until then, this command
+ * informs the user where to look.
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { agentPaths, placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface GatewayLogsOpts {
+  agentId?: string
+  tail: number
+  follow: boolean
+}
+
+export async function runGatewayLogs(opts: GatewayLogsOpts): Promise<void> {
+  let agentId = opts.agentId
+  if (!agentId) {
+    const found = await findAndLoadConfig()
+    if (!found?.config) {
+      console.error('nebula gateway logs: no nebula.config.ts and no --agent provided')
+      process.exit(1)
+    }
+    const agentEoa = found.config.identity.agent
+    if (!agentEoa) {
+      console.error('nebula gateway logs: config has no agent EOA; run `nebula init` first')
+      process.exit(1)
+    }
+    agentId = placeholderAgentId(agentEoa)
+  }
+  const logFile = join(agentPaths.agent(agentId).dir, 'gateway.log')
+  if (!existsSync(logFile)) {
+    console.log(`gateway log not found at ${logFile}`)
+    console.log('v0.19.x: gateway daemon logs to stdout when run via `nebula gateway run`.')
+    console.log(
+      'Background it with: nohup bun packages/gateway/bin/nebula-gateway-local > ~/nebula-logs/gateway.log 2>&1 &',
+    )
+    return
+  }
+  const args = ['-n', String(opts.tail), ...(opts.follow ? ['-f'] : []), logFile]
+  const proc = spawn('tail', args, { stdio: 'inherit' })
+  proc.on('exit', code => process.exit(code ?? 0))
+}

package/src/commands/gateway-run.ts

@@ -0,0 +1,42 @@
+/**
+ * `nebula gateway run` — foreground daemon (blocks; Ctrl+C to stop).
+ *
+ * Spawns `nebula-gateway-local` (the bin in nebula-ai-gateway) with
+ * inherit stdio so the user sees logs live. Reads operator-session for the
+ * cached AES keys; fails loud if no session exists ("run nebula gateway start
+ * first").
+ */
+
+import { spawn } from 'node:child_process'
+import { join } from 'node:path'
+import { resolveLocalBin } from '../util/gateway-spawn'
+
+export interface GatewayRunOpts {
+  agentId?: string
+}
+
+export async function runGatewayForeground(opts: GatewayRunOpts): Promise<void> {
+  const env = { ...process.env }
+  if (opts.agentId) env.NEBULA_AGENT_ID = opts.agentId
+  // Default NEBULA_CONFIG to ~/.nebula/config.ts if not already set.
+  if (!env.NEBULA_CONFIG) {
+    env.NEBULA_CONFIG = join(env.HOME ?? '', '.nebula', 'config.ts')
+  }
+
+  const localBin = resolveLocalBin()
+  const proc = spawn('bun', [localBin], {
+    env,
+    stdio: 'inherit',
+  })
+  proc.on('exit', code => process.exit(code ?? 0))
+  proc.on('error', err => {
+    console.error(`nebula gateway run: spawn failed — ${err.message}`)
+    process.exit(1)
+  })
+
+  const forwardSignal = (sig: NodeJS.Signals): void => {
+    if (!proc.killed) proc.kill(sig)
+  }
+  process.on('SIGINT', () => forwardSignal('SIGINT'))
+  process.on('SIGTERM', () => forwardSignal('SIGTERM'))
+}

package/src/commands/gateway-start.ts

@@ -0,0 +1,216 @@
+/**
+ * `nebula gateway start` — interactive Touch ID + write operator-session,
+ * then fork the gateway daemon detached.
+ *
+ * Flow:
+ *   1. Load config from ~/.nebula/config.ts
+ *   2. Resolve agentId (override via --agent or first agent in config)
+ *   3. Check if gateway already running (lock file). If yes, error.
+ *   4. Pick operator signer + interactive Touch ID via existing operator-picker
+ *   5. Pre-derive scope keys via precomputeAllScopes (keystore + telegram)
+ *   6. Write operator-session file (perm 0600, 24h TTL)
+ *   7. Spawn nebula-gateway-local detached + wait for socket to become readable
+ *      (proves the daemon booted cleanly)
+ *   8. Print pid + socket path
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spinner } from '@clack/prompts'
+import {
+  OPERATOR_BLOB_SCOPES,
+  type OperatorBlobScope,
+  agentPaths,
+  buildOperatorSession,
+  decodeKeystoreBytes,
+  decodeOperatorBlobBytes,
+  isOperatorSessionComplete,
+  placeholderAgentId,
+  precomputeAllScopes,
+  readOperatorSession,
+  requiredScopesForAgent,
+  tryDecryptKeystoreWithKey,
+  tryDecryptOperatorBlobWithKey,
+  writeOperatorSession,
+} from 'nebula-ai-core'
+import { type Address, getAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { spawnGatewayDaemon } from '../util/gateway-spawn'
+import { telegramSecretsPath } from '../util/telegram-secrets'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export interface GatewayStartOpts {
+  agentId?: string
+}
+
+export async function runGatewayStart(opts: GatewayStartOpts): Promise<void> {
+  const found = await findAndLoadConfig()
+  if (!found?.config) {
+    console.error('nebula gateway start: no nebula.config.ts found in cwd or ~/.nebula/')
+    process.exit(1)
+  }
+  const config = found.config
+  const agentAddress = getAddress(config.identity.agent as Address)
+  const agentId = opts.agentId ?? placeholderAgentId(agentAddress)
+  const paths = agentPaths.agent(agentId)
+  const socketPath = join(paths.dir, 'gateway.sock')
+
+  // v0.23.2: if the socket exists, check for version drift. If the running
+  // daemon's version differs from the on-disk CLI binary, auto-restart so
+  // operators don't have to remember `nebula gateway restart` after every
+  // `bun add -g nebula-ai-cli@N`. If versions match, bail with the
+  // legacy "already running" error.
+  if (existsSync(socketPath)) {
+    const { createHash } = await import('node:crypto')
+    const { homedir } = await import('node:os')
+    const identityHash = createHash('sha256').update(agentId).digest('hex').slice(0, 16)
+    const lockFile = join(homedir(), '.nebula', 'locks', `nebula-gateway-${identityHash}.lock`)
+    const { ensureGatewayVersionMatchesCli } = await import('../util/gateway-version')
+    const drift = await ensureGatewayVersionMatchesCli({ socketPath, lockFile })
+    if (drift.action === 'ok' || drift.action === 'no-cli-version') {
+      console.error(
+        `nebula gateway start: socket already exists at ${socketPath} — gateway may be running (version ${drift.daemonVersion ?? 'unknown'}). Try \`nebula gateway stop\` first.`,
+      )
+      process.exit(1)
+    }
+    console.log(`note: ${drift.note}`)
+  }
+
+  // v0.21.12: derive the set of scope keys this agent's daemon will need
+  // based on what's on disk (always 'keystore'; adds 'telegram' when
+  // telegram-secrets.encrypted is present, etc.). The cached session is only
+  // "complete enough to skip Touch ID" when it contains every required key.
+  // Pre-fix, this used the binary `isOperatorSessionFresh` which returned
+  // true for any non-expired session, even one written by a path that didn't
+  // derive TELEGRAM. The daemon then booted, found no telegram scope key,
+  // and silently dropped all inbound TG messages.
+  const required = requiredScopesForAgent(agentId)
+  const extraScopes = required.filter((s): s is Exclude<typeof s, 'keystore'> => s !== 'keystore')
+  const complete = isOperatorSessionComplete(agentId, required)
+  if (!complete) {
+    const sUnlock = spinner()
+    sUnlock.start('Unlocking operator wallet for session-key derivation')
+    let operator: Awaited<ReturnType<typeof loadOrPickOperatorSigner>>
+    try {
+      operator = await loadOrPickOperatorSigner({
+        network: config.network,
+        hint: config.operator,
+      })
+    } catch (e) {
+      sUnlock.stop(`unlock failed: ${(e as Error).message.slice(0, 160)}`)
+      process.exit(1)
+    }
+    if (!operator) {
+      sUnlock.stop('operator unlock cancelled')
+      process.exit(1)
+    }
+
+    sUnlock.message(`Deriving scope keys (${required.join(' + ')})`)
+    try {
+      // v0.24.10: verify each derived canonical key against the on-disk
+      // encrypted artifact. If verify fails (e.g. fox's pre-v0.24.9 WC
+      // keystore was encrypted with the legacy empty-EIP712Domain hash),
+      // `precomputeAllScopes` falls back to the legacy variant via the WC
+      // signer's escape hatch and caches the WORKING key. Without this,
+      // the daemon would boot with a stale canonical key + the
+      // `precomputedKey skips fallback` semantic and panic on first
+      // AES-GCM decrypt.
+      const verifyKey = buildKeystoreVerifier(agentId)
+      const keys = await precomputeAllScopes(operator, agentAddress, extraScopes, { verifyKey })
+      const sess = buildOperatorSession({ agent: agentAddress, keys })
+      writeOperatorSession(agentId, sess)
+      sUnlock.stop('operator-session written (24h TTL)')
+    } catch (e) {
+      sUnlock.stop(`derive failed: ${(e as Error).message.slice(0, 160)}`)
+      await operator.close?.()
+      process.exit(1)
+    }
+    await operator.close?.()
+  } else {
+    console.log(`operator-session complete (${required.join(' + ')}); skipping Touch ID`)
+  }
+
+  // Spawn gateway daemon detached. Inherit stdio for the first ~3s so the
+  // user sees boot errors, then redirect to log file when ready.
+  const sBoot = spinner()
+  sBoot.start(`Spawning gateway daemon (agent=${agentId.slice(0, 8)}…)`)
+
+  const result = await spawnGatewayDaemon({
+    agentId,
+    configPath: found.path ?? '',
+    socketPath,
+    timeoutMs: 10_000,
+    // v0.21.12: redirect daemon stdout/stderr to gateway.log (default
+    // 'log-file' mode) so boot errors survive the parent's exit. Operators
+    // see the log via `nebula gateway logs` or by tailing
+    // ~/.nebula/agents/<id>/gateway.log directly.
+  })
+  if (result.ready) {
+    sBoot.stop(`gateway running pid=${result.pid} socket=${socketPath}`)
+    console.log('stop with: nebula gateway stop')
+    console.log('logs:      nebula gateway logs -f')
+  } else {
+    const reason = result.reason ?? 'unknown'
+    const detail = result.error ? `: ${result.error}` : ''
+    sBoot.stop(
+      `gateway did not bind socket within 10s (reason=${reason} pid=${result.pid ?? '?'})${detail}; check above output`,
+    )
+    process.exit(1)
+  }
+}
+
+// Stub — wired by gateway-status when needed.
+export function _operatorSessionPresent(agentId: string): boolean {
+  return readOperatorSession(agentId) !== null
+}
+
+/**
+ * v0.24.10: returns a verifier that `precomputeAllScopes` calls after each
+ * canonical key derive. The verifier:
+ *
+ * - For 'keystore': trial-decrypts `<agentDir>/keystore.json` with the
+ *   candidate key. Returns true on success, false on AES-GCM auth failure.
+ *   False triggers the legacy empty-EIP712Domain fallback inside
+ *   `precomputeAllScopes` so pre-v0.24.9 WC-init'd keystores (only known
+ *   instance is fox, tokenId #5) can still flip to the correct AES key on
+ *   first boot under v0.24.10+.
+ *
+ * - For TELEGRAM: trial-decrypts `<agentDir>/telegram-secrets.encrypted`
+ *   when present. Same legacy-fallback semantic.
+ *
+ * - For PROFILE / unknown: returns true unconditionally. PROFILE has no
+ *   on-disk artifact to verify against (the encrypted blob lives in iNFT
+ *   slot 3 on chain); the keystore-scope detection above already cascades
+ *   the legacy flag to PROFILE via `precomputeAllScopes`'s
+ *   `useLegacyForRest` branch, so the PROFILE key is derived via the
+ *   matching variant without needing a verify here.
+ *
+ * - On missing keystore (init flow never reached this code path, so this
+ *   is a defensive fallback): returns true so the derive completes; the
+ *   daemon's own decrypt at boot will surface the real error.
+ */
+function buildKeystoreVerifier(agentId: string) {
+  const keystorePath = agentPaths.agent(agentId).keystore
+  const tgSecretsPath = telegramSecretsPath(agentId)
+  return async (scope: 'keystore' | OperatorBlobScope, key: Buffer): Promise<boolean> => {
+    if (scope === 'keystore') {
+      if (!existsSync(keystorePath)) return true
+      try {
+        const ks = decodeKeystoreBytes(new TextEncoder().encode(readFileSync(keystorePath, 'utf8')))
+        return tryDecryptKeystoreWithKey(ks, key)
+      } catch {
+        return true
+      }
+    }
+    if (scope === OPERATOR_BLOB_SCOPES.TELEGRAM) {
+      if (!existsSync(tgSecretsPath)) return true
+      try {
+        const blob = decodeOperatorBlobBytes(new Uint8Array(readFileSync(tgSecretsPath)))
+        return tryDecryptOperatorBlobWithKey(blob, key, OPERATOR_BLOB_SCOPES.TELEGRAM)
+      } catch {
+        return true
+      }
+    }
+    return true
+  }
+}

package/src/commands/gateway-status.ts

@@ -0,0 +1,90 @@
+/**
+ * `nebula gateway status` — show PID, uptime, socket path, lock state,
+ * operator-session freshness.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import {
+  agentPaths,
+  isOperatorSessionFresh,
+  placeholderAgentId,
+  readOperatorSession,
+} from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface GatewayStatusOpts {
+  agentId?: string
+}
+
+function fmtAge(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m`
+  const h = Math.floor(m / 60)
+  return `${h}h${m % 60}m`
+}
+
+export async function runGatewayStatus(opts: GatewayStatusOpts): Promise<void> {
+  let agentId = opts.agentId
+  if (!agentId) {
+    const found = await findAndLoadConfig()
+    if (!found?.config) {
+      console.error('nebula gateway status: no nebula.config.ts and no --agent provided')
+      process.exit(1)
+    }
+    const agentEoa = found.config.identity.agent
+    if (!agentEoa) {
+      console.error('nebula gateway status: config has no agent EOA; run `nebula init` first')
+      process.exit(1)
+    }
+    agentId = placeholderAgentId(agentEoa)
+  }
+  const paths = agentPaths.agent(agentId)
+  const socketPath = join(paths.dir, 'gateway.sock')
+  const identityHash = createHash('sha256').update(agentId).digest('hex').slice(0, 16)
+  const lockFile = join(homedir(), '.nebula', 'locks', `nebula-gateway-${identityHash}.lock`)
+
+  console.log(`agent:        ${agentId}`)
+  console.log(`socket:       ${socketPath} ${existsSync(socketPath) ? '(present)' : '(absent)'}`)
+  console.log(`lock:         ${lockFile} ${existsSync(lockFile) ? '(present)' : '(absent)'}`)
+
+  // PID + uptime via lock file.
+  if (existsSync(lockFile)) {
+    try {
+      const parsed = JSON.parse(readFileSync(lockFile, 'utf8')) as { pid?: number }
+      if (typeof parsed.pid === 'number') {
+        let alive = false
+        try {
+          process.kill(parsed.pid, 0)
+          alive = true
+        } catch {
+          /* dead */
+        }
+        const stat = statSync(lockFile)
+        const ageMs = Date.now() - stat.mtimeMs
+        console.log(`pid:          ${parsed.pid} ${alive ? '(alive)' : '(dead — stale lock)'}`)
+        console.log(`lock-age:     ${fmtAge(ageMs)}`)
+      }
+    } catch {
+      console.log('pid:          (lock file unreadable)')
+    }
+  } else {
+    console.log('pid:          (not running)')
+  }
+
+  // Operator-session freshness.
+  const fresh = isOperatorSessionFresh(agentId)
+  console.log(`session:      ${fresh ? 'fresh' : 'absent or expired'}`)
+  if (fresh) {
+    const sess = readOperatorSession(agentId)
+    if (sess) {
+      const remaining = sess.expiresAt - Date.now()
+      const scopes = Object.keys(sess.keys).filter(k => sess.keys[k as keyof typeof sess.keys])
+      console.log(`session-ttl:  ${fmtAge(remaining)} remaining (scopes: ${scopes.join(', ')})`)
+    }
+  }
+}

package/src/commands/gateway-stop.ts

@@ -0,0 +1,133 @@
+/**
+ * `nebula gateway stop` — SIGTERM the running gateway daemon via the lock
+ * file's PID. Falls through to SIGKILL after a 5s grace period.
+ */
+
+import { existsSync, readFileSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { agentPaths, placeholderAgentId } from 'nebula-ai-core'
+import { findAndLoadConfig } from '../config/load'
+
+export interface GatewayStopOpts {
+  agentId?: string
+}
+
+function lockPath(_agentId: string): string {
+  // Mirror packages/core/src/locks.ts — `~/.nebula/locks/<scope>-<sha256(identity).slice(0,16)>.lock`
+  // For 'nebula-gateway' scope. We compute the same hash as the lock module.
+  // Easiest: read all lock files and find one matching the agent.
+  return join(homedir(), '.nebula', 'locks')
+}
+
+function findGatewayLock(agentId: string): string | null {
+  // The lock filename embeds sha256(agentId).slice(0, 16). Compute it.
+  const { createHash } = require('node:crypto')
+  const identityHash = createHash('sha256').update(agentId).digest('hex').slice(0, 16)
+  const lockFile = join(lockPath(agentId), `nebula-gateway-${identityHash}.lock`)
+  return existsSync(lockFile) ? lockFile : null
+}
+
+export async function runGatewayStop(opts: GatewayStopOpts): Promise<void> {
+  let agentId = opts.agentId
+  if (!agentId) {
+    const found = await findAndLoadConfig()
+    if (!found?.config) {
+      console.error('nebula gateway stop: no nebula.config.ts and no --agent provided')
+      process.exit(1)
+    }
+    const agentEoa = found.config.identity?.agent ?? null
+    if (!agentEoa) {
+      console.error('nebula gateway stop: config has no agent EOA; run `nebula init` first')
+      process.exit(1)
+    }
+    agentId = placeholderAgentId(agentEoa)
+    const label = `agent ${agentId.slice(0, 8)}…`
+    const eoaLabel = ` (EOA ${agentEoa.slice(0, 6)}…${agentEoa.slice(-4)})`
+    const configPath = found.path ?? '<unknown>'
+    console.log(`nebula gateway stop → ${label}${eoaLabel}`)
+    console.log(`  config: ${configPath}`)
+    console.log(
+      '  if this is not the agent you meant, set NEBULA_ROOT or pass --agent <id> before re-running.',
+    )
+  }
+  const lockFile = findGatewayLock(agentId)
+  if (!lockFile) {
+    console.log(`gateway not running (no lock at ${lockPath(agentId)})`)
+    return
+  }
+  let pid: number
+  try {
+    const raw = readFileSync(lockFile, 'utf8').trim()
+    // Lock files are JSON with shape `{pid, scope, identityHash, expiresAt}`.
+    const parsed = JSON.parse(raw) as { pid?: number }
+    if (typeof parsed.pid !== 'number') {
+      console.error('nebula gateway stop: lock file has no pid field')
+      process.exit(1)
+    }
+    pid = parsed.pid
+  } catch (e) {
+    console.error(`nebula gateway stop: lock file unreadable — ${(e as Error).message}`)
+    process.exit(1)
+  }
+
+  // Verify the PID is alive.
+  try {
+    process.kill(pid, 0)
+  } catch {
+    console.log(`gateway not running (stale lock pid=${pid}); cleaning up`)
+    try {
+      unlinkSync(lockFile)
+    } catch {
+      /* ignore */
+    }
+    return
+  }
+
+  // Send SIGTERM, wait up to 5s, then SIGKILL.
+  console.log(`stopping gateway pid=${pid} ...`)
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch (e) {
+    console.error(`nebula gateway stop: SIGTERM failed — ${(e as Error).message}`)
+    process.exit(1)
+  }
+
+  const start = Date.now()
+  while (Date.now() - start < 5_000) {
+    try {
+      process.kill(pid, 0)
+    } catch {
+      console.log(`gateway stopped pid=${pid}`)
+      // Lock file is auto-removed by daemon's shutdown handler. Belt + suspenders:
+      try {
+        if (existsSync(lockFile)) unlinkSync(lockFile)
+      } catch {
+        /* ignore */
+      }
+      // Also clean up the socket file in case the daemon didn't.
+      const socketPath = join(agentPaths.agent(agentId).dir, 'gateway.sock')
+      try {
+        if (existsSync(socketPath)) unlinkSync(socketPath)
+      } catch {
+        /* ignore */
+      }
+      return
+    }
+    await new Promise(r => setTimeout(r, 200))
+  }
+
+  console.log('gateway did not exit in 5s; sending SIGKILL')
+  try {
+    process.kill(pid, 'SIGKILL')
+  } catch (e) {
+    console.error(`nebula gateway stop: SIGKILL failed — ${(e as Error).message}`)
+    process.exit(1)
+  }
+  try {
+    if (existsSync(lockFile)) unlinkSync(lockFile)
+  } catch {
+    /* ignore */
+  }
+  console.log(`gateway force-killed pid=${pid}`)
+}