@promus/cli 0.24.17

package/src/config/load.ts

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { type PromusConfig, agentPaths } from '@promus/core'
+
+/**
+ * Load the user's `promus.config.ts`.
+ *
+ * Phase 6.6: canonical location is `~/.promus/config.ts` (returned by
+ * `agentPaths.config`). If that file exists, it wins. Otherwise, fall back
+ * to walking upward from cwd looking for `promus.config.ts` (legacy v0.5.0
+ * pattern, kept so existing dev setups still work without a migration step).
+ */
+export async function findAndLoadConfig(
+  startDir: string = process.cwd(),
+): Promise<{ config: PromusConfig; path: string } | null> {
+  const canonical = agentPaths.config
+  if (existsSync(canonical)) {
+    const mod = (await import(canonical)) as { default: PromusConfig }
+    if (!mod.default) throw new Error(`promus config at ${canonical} has no default export`)
+    return { config: mod.default, path: canonical }
+  }
+
+  let dir = resolve(startDir)
+  while (true) {
+    const candidate = resolve(dir, 'promus.config.ts')
+    if (existsSync(candidate)) {
+      const mod = (await import(candidate)) as { default: PromusConfig }
+      if (!mod.default) throw new Error(`promus.config.ts at ${candidate} has no default export`)
+      return { config: mod.default, path: candidate }
+    }
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/config/render.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'bun:test'
+import type { PromusConfig } from '@promus/core'
+import { renderConfigTs } from './render'
+
+const baseConfig: PromusConfig = {
+  identity: { iNFT: null, operator: null, agent: null },
+  network: '0g-mainnet',
+  storage: { network: '0g-mainnet' },
+  brain: { provider: null, model: null },
+  plugins: ['system'],
+  tools: {},
+  imports: { claudeCode: true },
+}
+
+describe('renderConfigTs sandbox block', () => {
+  test('fresh config (no sandbox set) emits default + commented examples for each tier', () => {
+    const out = renderConfigTs(baseConfig)
+    // Active default
+    expect(out).toContain(`sandbox: { mode: 'none' }`)
+    // Commented OPTION 2 (os)
+    expect(out).toContain('OPTION 2: os')
+    expect(out).toContain(`//  sandbox: { mode: 'os' }`)
+    // Commented OPTION 3 (docker)
+    expect(out).toContain('OPTION 3: docker')
+    expect(out).toContain(`//    mode: 'docker'`)
+    expect(out).toContain(`//    dockerImage: 'nikolaik/python-nodejs:python3.11-nodejs20'`)
+    expect(out).toContain('//    dockerMountWorkspace: false')
+    // PROMUS_SANDBOX_MODE override hint
+    expect(out).toContain('PROMUS_SANDBOX_MODE')
+  })
+
+  test('config with sandbox.mode="os" already set emits the chosen value, not the template', () => {
+    const out = renderConfigTs({ ...baseConfig, sandbox: { mode: 'os' } })
+    expect(out).toContain(`"mode": "os"`)
+    // No verbose template when operator already chose
+    expect(out).not.toContain('OPTION 2: os')
+    expect(out).not.toContain('OPTION 3: docker')
+  })
+
+  test('config with sandbox.mode="docker" + image emits the full chosen object', () => {
+    const out = renderConfigTs({
+      ...baseConfig,
+      sandbox: {
+        mode: 'docker',
+        dockerImage: 'custom/img:tag',
+        dockerMountWorkspace: true,
+      },
+    })
+    expect(out).toContain(`"mode": "docker"`)
+    expect(out).toContain(`"dockerImage": "custom/img:tag"`)
+    expect(out).toContain(`"dockerMountWorkspace": true`)
+    expect(out).not.toContain('OPTION')
+  })
+
+  test('annotated template documents resource caps with hermes default values', () => {
+    const out = renderConfigTs(baseConfig)
+    expect(out).toContain('// dockerCpu: 1')
+    expect(out).toContain('// dockerMemoryMb: 5120')
+    expect(out).toContain('// dockerDiskMb: 51200')
+    expect(out).toContain('// dockerNoNetwork: true')
+  })
+
+  test('config with sandbox docker + resource caps emits chosen numeric values', () => {
+    const out = renderConfigTs({
+      ...baseConfig,
+      sandbox: {
+        mode: 'docker',
+        dockerCpu: 2,
+        dockerMemoryMb: 4096,
+        dockerNoNetwork: true,
+      },
+    })
+    expect(out).toContain(`"dockerCpu": 2`)
+    expect(out).toContain(`"dockerMemoryMb": 4096`)
+    expect(out).toContain(`"dockerNoNetwork": true`)
+    expect(out).not.toContain('OPTION')
+  })
+
+  test('output is valid TypeScript (parses as a default-export module)', async () => {
+    const out = renderConfigTs(baseConfig)
+    const { writeFile, rm, mkdtemp } = await import('node:fs/promises')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const dir = await mkdtemp(join(tmpdir(), 'promus-render-test-'))
+    const path = join(dir, 'config.ts')
+    try {
+      await writeFile(path, out, 'utf8')
+      const mod = await import(path)
+      expect(mod.default).toBeDefined()
+      expect(mod.default.sandbox).toEqual({ mode: 'none' })
+      expect(mod.default.network).toBe('0g-mainnet')
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/config/render.ts

@@ -0,0 +1,110 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { PromusConfig } from '@promus/core'
+
+export interface RenderConfigOpts {
+  header?: string
+  subname?: string | null
+}
+
+/**
+ * Serialize an PromusConfig into a `~/.promus/config.ts` file body.
+ *
+ * Phase 6.6: the config lives at `~/.promus/config.ts` which is outside any
+ * workspace, so it MUST NOT import `@promus/core` (the import won't
+ * resolve from `~/.promus/`). We emit a plain `export default { ... }` object;
+ * the runtime loader treats it as `PromusConfig` directly.
+ */
+export function renderConfigTs(cfg: PromusConfig, opts: RenderConfigOpts = {}): string {
+  const header = opts.header ?? ''
+  const subnameLine =
+    opts.subname !== undefined ? `  subname: ${JSON.stringify(opts.subname)},\n` : ''
+  const operatorLine = cfg.operator ? `  operator: ${JSON.stringify(cfg.operator)},\n` : ''
+  // Phase 9.5 / v0.10.1: emit either the operator's chosen sandbox config OR an
+  // annotated "OPTION 1/2/3" block so the operator can opt in by uncommenting.
+  // Mirrors hermes-agent's cli-config.yaml.example pattern: documentation IS
+  // the UX, not an interactive wizard. Default mode stays `none` (passthrough)
+  // for back-compat.
+  const sandboxBlock = renderSandboxBlock(cfg.sandbox)
+  const deployTargetLine =
+    cfg.deployTarget && cfg.deployTarget !== 'local'
+      ? `  deployTarget: ${JSON.stringify(cfg.deployTarget)},\n`
+      : ''
+  return `${header ? `${header}\n\n` : ''}export default {
+  identity: ${JSON.stringify(cfg.identity)},
+  network: ${JSON.stringify(cfg.network)},
+  storage: { network: ${JSON.stringify(cfg.storage.network)} },
+  brain: {
+    provider: ${JSON.stringify(cfg.brain.provider)},
+    model: ${JSON.stringify(cfg.brain.model)},
+  },
+  plugins: ${JSON.stringify(cfg.plugins)},
+  tools: ${JSON.stringify(cfg.tools)},
+  imports: { claudeCode: ${cfg.imports.claudeCode} },
+${deployTargetLine}${operatorLine}${subnameLine}${sandboxBlock}}
+`
+}
+
+function renderSandboxBlock(sandbox: PromusConfig['sandbox']): string {
+  // Phase 11: deploy-target sandbox metadata (id/providerAddress/endpoint/
+  // snapshotName) OR Phase 9.5 limb-sandbox mode = anything non-default → emit
+  // verbatim. Only surface the doc-comment template when the operator has
+  // touched neither.
+  const hasPhase11Metadata =
+    sandbox?.id || sandbox?.providerAddress || sandbox?.endpoint || sandbox?.snapshotName
+  const hasNonDefaultLimbMode = sandbox?.mode && sandbox.mode !== 'none'
+  if (hasPhase11Metadata || hasNonDefaultLimbMode) {
+    return `  sandbox: ${JSON.stringify(sandbox, null, 2).replace(/\n/g, '\n  ')},\n`
+  }
+  // Fresh install: write the active default + commented examples for the
+  // other tiers. Operator can opt in by uncommenting and editing.
+  return `  sandbox: { mode: 'none' },
+  // ---------------------------------------------------------------------------
+  //  Limb sandbox (Phase 9.5). Defense-in-depth beneath the permission floor:
+  //  even when the modal grants 'allow session' or YOLO disables prompts,
+  //  the sandbox profile/container blocks writes outside an allowlist.
+  //  All shell.run / code.execute / shell.process_start spawns route through
+  //  the chosen backend. fs.* and browser.* still run on the host (PathGuard
+  //  applies). Override at runtime via PROMUS_SANDBOX_MODE=os|docker|none.
+  //
+  //  OPTION 1: none (default): passthrough, fastest, permission floor only.
+  //
+  //  OPTION 2: os (macOS sandbox-exec / seatbelt). Allows writes to agentDir +
+  //    cwd + /tmp/promus-* + /var/folders. Denies reads of ~/.ssh, ~/.aws,
+  //    ~/Library/Keychains, ~/.config/gcloud. Linux bubblewrap pending.
+  //  sandbox: { mode: 'os' },
+  //
+  //  OPTION 3: docker (long-lived container per session), every shell-class
+  //    spawn through 'docker exec'. Auto-detects Docker Desktop or Podman.
+  //    Default image 'nikolaik/python-nodejs:python3.11-nodejs20' (matches
+  //    hermes; ~700 MB; bash + python3 + node + npm + git on standard PATH).
+  //    Override with 'oven/bun:1' (~250 MB) if you only need bun/ts.
+  //    'dockerMountWorkspace: true' bind-mounts your launch cwd into
+  //    /workspace (off by default for max isolation). 'dockerRuntimePath'
+  //    forces a specific runtime binary. Resource caps are unset by default
+  //    (container competes fairly with host work). Set them to mirror hermes'
+  //    production hardening: dockerCpu=1, dockerMemoryMb=5120, dockerDiskMb=
+  //    51200 (Linux+overlay2 only). dockerNoNetwork=true blocks all internet
+  //    access from the container (max paranoia for code.execute).
+  //  sandbox: {
+  //    mode: 'docker',
+  //    dockerImage: 'nikolaik/python-nodejs:python3.11-nodejs20',
+  //    dockerMountWorkspace: false,
+  //    // dockerRuntimePath: '/opt/homebrew/bin/podman',
+  //    // dockerCpu: 1,           // CPU cores cap
+  //    // dockerMemoryMb: 5120,   // 5 GB memory cap
+  //    // dockerDiskMb: 51200,    // 50 GB disk cap (Linux + overlay2 only)
+  //    // dockerNoNetwork: true,  // block all network from inside container
+  //  },
+  // ---------------------------------------------------------------------------
+`
+}
+
+export async function writeConfigTs(
+  path: string,
+  cfg: PromusConfig,
+  opts: RenderConfigOpts = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, renderConfigTs(cfg, opts), 'utf8')
+}

package/src/index.ts

@@ -0,0 +1,378 @@
+/**
+ * CLI argv dispatch. Keeps phase 2 minimal: no subcommand → chat REPL,
+ * otherwise route to commands/<name>.
+ */
+
+const argv = process.argv.slice(2)
+// First arg starting with `--` means the user invoked the default subcommand
+// (chat) with flags, e.g. `promus --yolo`. Treat it as if `chat` were implicit.
+// Exception: `--help` and `--version` are top-level commands, not chat flags.
+const first = argv[0]
+const isTopLevelFlag = first === '--help' || first === '--version'
+const sub = first?.startsWith('--') && !isTopLevelFlag ? 'chat' : first
+
+async function main(): Promise<void> {
+  switch (sub) {
+    case undefined:
+    case 'chat': {
+      const { runChat } = await import('./commands/chat')
+      const resumeIdx = argv.indexOf('--resume')
+      const resumeSession = resumeIdx >= 0 ? argv[resumeIdx + 1] : undefined
+      await runChat({ yolo: argv.includes('--yolo'), resume: resumeSession })
+      return
+    }
+    case 'init': {
+      if (argv.includes('--resume')) {
+        const { findAndLoadConfig } = await import('./config/load')
+        const loaded = await findAndLoadConfig()
+        if (!loaded) {
+          console.error('promus init --resume: no promus.config.ts found in cwd or parents.')
+          process.exit(1)
+        }
+        const { runResumeInit } = await import('./commands/init/resume')
+        await runResumeInit({ config: loaded.config, configPath: loaded.path })
+        return
+      }
+      const { runInit } = await import('./commands/init')
+      await runInit()
+      return
+    }
+    case 'status': {
+      const { runStatus } = await import('./commands/status')
+      await runStatus()
+      return
+    }
+    case 'logs': {
+      const { runLogs } = await import('./commands/logs')
+      const tailIdx = argv.indexOf('--tail')
+      const tail = tailIdx >= 0 ? Number(argv[tailIdx + 1]) : undefined
+      const agentIdx = argv.indexOf('--agent')
+      const agent = agentIdx >= 0 ? argv[agentIdx + 1] : undefined
+      await runLogs({ agent, tail })
+      return
+    }
+    case 'restore': {
+      const ref = argv[1]
+      if (!ref) {
+        console.error(
+          'usage: promus restore <iNFT-ref>\n  ref formats:\n    eip155:16661:0x<contract>:<tokenId>\n    0g-mainnet:0x<contract>:<tokenId>\n    0g-testnet:0x<contract>:<tokenId>',
+        )
+        process.exit(1)
+      }
+      const { runRestore } = await import('./commands/restore')
+      await runRestore({ ref })
+      return
+    }
+    case 'transfer': {
+      const { parseTransferArgs, runTransfer } = await import('./commands/transfer')
+      const parsed = parseTransferArgs(argv.slice(1))
+      if ('error' in parsed) {
+        console.error(
+          `promus transfer: ${parsed.error}\n  usage: promus transfer <iNFT-ref> --to <addr> [--recipient-key 0x...] [--dry-run] [--yes] [--no-purge]`,
+        )
+        process.exit(1)
+      }
+      await runTransfer(parsed)
+      return
+    }
+    case 'topup': {
+      const agentIdx = argv.indexOf('--agent')
+      const computeIdx = argv.indexOf('--compute')
+      // v0.21.5: --sandbox is the canonical flag for SandboxBilling (Galileo
+      // testnet runtime fees). --provider stays as a deprecated alias for
+      // backwards compat with v0.17.1+ runbooks.
+      const sandboxIdx = argv.indexOf('--sandbox')
+      const providerIdx = argv.indexOf('--provider')
+      const visionIdx = argv.indexOf('--vision')
+      const parseAmount = (flag: string, raw: string | undefined): number | undefined => {
+        if (raw === undefined) return undefined
+        const n = Number(raw)
+        if (!Number.isFinite(n) || n <= 0 || n > 1e6) {
+          console.error(
+            `Bad amount for ${flag}: ${raw}\n  Each topup flag takes an amount in 0G, not an address: ${flag} <amount>\n  Examples: promus topup --compute 2     promus topup --sandbox 5     promus topup --agent 1     promus topup --vision 1`,
+          )
+          process.exit(2)
+        }
+        return n
+      }
+      const agent = parseAmount('--agent', agentIdx >= 0 ? argv[agentIdx + 1] : undefined)
+      const compute = parseAmount('--compute', computeIdx >= 0 ? argv[computeIdx + 1] : undefined)
+      const sandboxArg = parseAmount(
+        '--sandbox',
+        sandboxIdx >= 0 ? argv[sandboxIdx + 1] : undefined,
+      )
+      const providerLegacyArg = parseAmount(
+        '--provider',
+        providerIdx >= 0 ? argv[providerIdx + 1] : undefined,
+      )
+      const vision = parseAmount('--vision', visionIdx >= 0 ? argv[visionIdx + 1] : undefined)
+      if (providerLegacyArg !== undefined && sandboxArg === undefined) {
+        console.warn(
+          '[deprecated] `promus topup --provider` is renamed to `--sandbox` (Galileo testnet billing); both flags work for now but `--provider` will be removed in a future release.',
+        )
+      } else if (providerLegacyArg !== undefined && sandboxArg !== undefined) {
+        console.error(
+          'promus topup: cannot pass both --sandbox and --provider; pick one (--sandbox is canonical).',
+        )
+        process.exit(2)
+      }
+      const sandbox = sandboxArg ?? providerLegacyArg
+      const { runTopup } = await import('./commands/topup')
+      await runTopup({ agent, compute, sandbox, vision })
+      return
+    }
+    case 'model': {
+      const { runModel } = await import('./commands/model')
+      await runModel()
+      return
+    }
+    case 'sync': {
+      const { runSync } = await import('./commands/sync')
+      await runSync()
+      return
+    }
+    case 'profile': {
+      // v0.23.0: `promus profile init` seeds user/profile.md if missing, derives
+      // the operator-scoped PROFILE AES key, and either (sandbox) POSTs it to
+      // /admin/profile-key or (local) runs a sync that anchors the slot.
+      const profileSub = argv[1]
+      if (profileSub === 'init') {
+        const { runProfileInit } = await import('./commands/profile')
+        await runProfileInit()
+        return
+      }
+      console.error(
+        `Unknown profile subcommand: ${profileSub ?? '(none)'} — try 'promus profile init'`,
+      )
+      process.exit(1)
+      return
+    }
+    case 'migrate-keystore': {
+      const { runMigrateKeystore } = await import('./commands/migrate-keystore')
+      await runMigrateKeystore()
+      return
+    }
+    case 'deploy': {
+      const { runDeploy } = await import('./commands/deploy')
+      await runDeploy()
+      return
+    }
+    case 'upgrade': {
+      const { parseUpgradeArgs, runUpgrade } = await import('./commands/upgrade')
+      await runUpgrade(parseUpgradeArgs(argv.slice(1)))
+      return
+    }
+    case 'resume': {
+      const yes = argv.includes('--yes') || argv.includes('-y')
+      const { runResume } = await import('./commands/resume')
+      await runResume({ yes })
+      return
+    }
+    case 'pause': {
+      const yes = argv.includes('--yes') || argv.includes('-y')
+      const { runPause } = await import('./commands/pause')
+      await runPause({ yes })
+      return
+    }
+    case 'ledger': {
+      const sub = argv[1]
+      const validSubs = ['balance', 'refund', 'retrieve', 'close'] as const
+      type Sub = (typeof validSubs)[number]
+      if (sub && !validSubs.includes(sub as Sub)) {
+        console.error(
+          `promus ledger: unknown subcommand '${sub}' (expected: ${validSubs.join(' | ')})`,
+        )
+        process.exit(1)
+      }
+      const chosen = (sub ?? 'balance') as Sub
+      const amountIdx = argv.indexOf('--amount')
+      const amount = amountIdx >= 0 ? Number(argv[amountIdx + 1]) : undefined
+      const all = argv.includes('--all')
+      const yes = argv.includes('--yes') || argv.includes('-y')
+      const { runLedger } = await import('./commands/ledger')
+      await runLedger({ sub: chosen, amount, all, yes })
+      return
+    }
+    case 'balance': {
+      const agentIdx = argv.indexOf('--agent')
+      const agent = agentIdx >= 0 ? argv[agentIdx + 1] : undefined
+      const { runBalance } = await import('./commands/balance')
+      await runBalance({ agent })
+      return
+    }
+    case 'drain': {
+      const toIdx = argv.indexOf('--to')
+      const to = toIdx >= 0 ? argv[toIdx + 1] : undefined
+      const yes = argv.includes('--yes') || argv.includes('-y')
+      const { runDrain } = await import('./commands/drain')
+      await runDrain({ to, yes })
+      return
+    }
+    case 'telegram': {
+      const { parseTelegramArgs, runTelegram } = await import('./commands/telegram')
+      const parsed = parseTelegramArgs(argv.slice(1))
+      if ('error' in parsed) {
+        console.error(`promus telegram: ${parsed.error}`)
+        process.exit(1)
+      }
+      await runTelegram(parsed)
+      return
+    }
+    case 'pairing': {
+      const { parsePairingArgs, runPairing } = await import('./commands/pairing')
+      const parsed = parsePairingArgs(argv.slice(1))
+      if ('error' in parsed) {
+        console.error(`promus pairing: ${parsed.error}`)
+        process.exit(1)
+      }
+      await runPairing(parsed)
+      return
+    }
+    case 'admin': {
+      const { parseAdminArgs, runAdmin } = await import('./commands/admin')
+      const parsed = parseAdminArgs(argv.slice(1))
+      if ('error' in parsed) {
+        console.error(`promus admin: ${parsed.error}`)
+        process.exit(1)
+      }
+      await runAdmin(parsed)
+      return
+    }
+    case 'gateway': {
+      const { parseGatewayArgs, runGateway } = await import('./commands/gateway')
+      const parsed = parseGatewayArgs(argv.slice(1))
+      if ('error' in parsed) {
+        console.error(`promus gateway: ${parsed.error}`)
+        process.exit(1)
+      }
+      await runGateway(parsed)
+      return
+    }
+    case 'inspect': {
+      const { runInspect, isValidSlot } = await import('./commands/inspect')
+      const remaining = argv.slice(1)
+      const positional: string[] = []
+      const flags: Record<string, string | boolean> = {}
+      for (let i = 0; i < remaining.length; i++) {
+        const a = remaining[i]!
+        if (a === '--raw' || a === '--diff' || a === '--json' || a === '--full') {
+          flags[a.slice(2)] = true
+        } else if (a === '--slot' || a === '--tx' || a === '--out') {
+          const v = remaining[++i]
+          if (!v) {
+            console.error(`promus inspect: ${a} requires a value`)
+            process.exit(1)
+          }
+          flags[a.slice(2)] = v
+        } else if (a.startsWith('--')) {
+          console.error(`promus inspect: unknown flag ${a}`)
+          process.exit(1)
+        } else {
+          positional.push(a)
+        }
+      }
+      if (positional.length > 1) {
+        console.error('promus inspect: at most one positional ref allowed')
+        process.exit(1)
+      }
+      const slotFlag = flags.slot
+      let slotName: import('@promus/core').IntelligentDataSlot | undefined
+      if (typeof slotFlag === 'string') {
+        if (!isValidSlot(slotFlag)) {
+          console.error(
+            'promus inspect: --slot must be one of memory-index, identity, persona, profile, keystore, activity-log',
+          )
+          process.exit(1)
+        }
+        slotName = slotFlag
+      }
+      const txFlag = flags.tx
+      if (typeof txFlag === 'string' && !/^0x[0-9a-fA-F]{64}$/.test(txFlag)) {
+        console.error('promus inspect: --tx must be a 32-byte hex hash')
+        process.exit(1)
+      }
+      await runInspect({
+        ref: positional[0],
+        slot: slotName,
+        tx: typeof txFlag === 'string' ? (txFlag as `0x${string}`) : undefined,
+        raw: flags.raw === true,
+        diff: flags.diff === true,
+        json: flags.json === true,
+        full: flags.full === true,
+        out: typeof flags.out === 'string' ? flags.out : undefined,
+      })
+      return
+    }
+    case '-h':
+    case '--help':
+    case 'help': {
+      printHelp()
+      return
+    }
+    case '-v':
+    case '--version':
+    case 'version': {
+      const { resolveCliVersion } = await import('./util/cli-version')
+      const v = await resolveCliVersion()
+      console.log(v)
+      return
+    }
+    default: {
+      console.log(`Unknown command: ${sub}`)
+      printHelp()
+      process.exit(1)
+    }
+  }
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      'promus: sovereign agent harness CLI',
+      '',
+      'Commands:',
+      '  promus init                bootstrap a new agent identity + keystore',
+      '  promus [--yolo]            interactive chat with your agent (default; --yolo skips approvals)',
+      '  promus status              show agent + wallet + config state',
+      '  promus logs                tail the activity log  (flags: --tail N, --agent <id>)',
+      '  promus restore <ref>       recover an agent from an iNFT (ref: eip155:421614:0x..:N)',
+      '  promus transfer <ref>      transfer iNFT to a new operator with re-encrypted keystore',
+      '                             flags: --to <addr>, --recipient-key <hex>, --oracle-key <hex>,',
+      '                                    --dry-run, --yes, --no-purge',
+      '  promus balance             full economic position: agent EOA + operator balance',
+      "                             flags: --agent <addr>  (defaults to active config's agent)",
+      '  promus drain --to <addr>   sweep agent EOA balance to address (default: operator)',
+      '  promus sync                force flush memory + activity-log to IPFS + anchor on chain',
+      '  promus migrate-keystore    upgrade v0.5.0 passphrase keystore to v0.6 operator-wallet',
+      '  promus upgrade [<ref>]     roll harness to new ref in place (default: latest published release)',
+      '                             flags: --ref vX.Y.Z',
+      '  promus telegram <sub>      configure phone-DM gateway  (subs: setup | status | remove)',
+      '                             flags: --yes (skip remove confirmation)',
+      '  promus pairing <sub>       manage DM pairing approvals (subs: list | approve | revoke | clear-pending)',
+      '                             usage: promus pairing approve telegram <code>',
+      '  promus gateway <sub>       always-on agent gateway daemon  (subs: run | start | stop | restart | status | logs)',
+      '                             run = foreground, start = bg + Touch ID, stop = SIGTERM via lock',
+      '  promus inspect [ref]       audit on-chain memory slots (flags: --slot, --tx, --raw, --diff, --json, --full, --out <dir>)',
+      '  promus version             print CLI version  (aliases: --version, -v)',
+      '  promus help                show this message  (aliases: --help, -h)',
+      '',
+      '(`promus` remains a working alias for `promus`.)',
+      '',
+    ].join('\n'),
+  )
+}
+
+main()
+  .then(() => {
+    // Force-exit on success because some 0G SDKs (Storage Indexer, Compute
+    // broker, WalletConnect relay) leak open handles (websockets, heartbeat
+    // timers) that we don't have hooks to drain. Without this, one-shot
+    // commands like `promus init` would hang at the prompt indefinitely after
+    // their work completed. `chat` returns only when the user actually quits,
+    // so this also gives chat a clean exit. Exit code 0 = normal success.
+    process.exit(0)
+  })
+  .catch(e => {
+    console.error('fatal:', (e as Error).message)
+    process.exit(1)
+  })