@promus/cli 0.24.17

package/src/commands/gateway-status.ts

@@ -0,0 +1,88 @@
+/**
+ * `promus 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,
+  iNFTAgentId,
+  isOperatorSessionFresh,
+  readOperatorSession,
+} from '@promus/core'
+import { type Address, getAddress } from 'viem'
+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('promus gateway status: no promus.config.ts and no --agent provided')
+      process.exit(1)
+    }
+    const contractAddress = getAddress(found.config.identity.iNFT!.contract as Address)
+    const tokenId = BigInt(found.config.identity.iNFT!.tokenId)
+    agentId = iNFTAgentId({ contractAddress, tokenId })
+  }
+  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(), '.promus', 'locks', `@promus/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 @@
+/**
+ * `promus 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, iNFTAgentId } from '@promus/core'
+import { type Address, getAddress } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+
+export interface GatewayStopOpts {
+  agentId?: string
+}
+
+function lockPath(_agentId: string): string {
+  // Mirror packages/core/src/locks.ts — `~/.promus/locks/<scope>-<sha256(identity).slice(0,16)>.lock`
+  // For '@promus/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(), '.promus', '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), `@promus/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('promus gateway stop: no promus.config.ts and no --agent provided')
+      process.exit(1)
+    }
+    const contractAddress = getAddress(found.config.identity.iNFT!.contract as Address)
+    const tokenId = BigInt(found.config.identity.iNFT!.tokenId)
+    agentId = iNFTAgentId({ contractAddress, tokenId })
+    const subname = found.config.subname ?? null
+    const agentEoa = (found.config.identity?.agent as string | undefined) ?? null
+    const label = subname ? `${subname}.promus.0g` : `agent ${agentId.slice(0, 8)}…`
+    const eoaLabel = agentEoa ? ` (EOA ${agentEoa.slice(0, 6)}…${agentEoa.slice(-4)})` : ''
+    const configPath = found.path ?? '<unknown>'
+    console.log(`promus gateway stop → ${label}${eoaLabel}`)
+    console.log(`  config: ${configPath}`)
+    console.log(
+      '  if this is not the agent you meant, set PROMUS_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('promus gateway stop: lock file has no pid field')
+      process.exit(1)
+    }
+    pid = parsed.pid
+  } catch (e) {
+    console.error(`promus 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(`promus 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(`promus 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}`)
+}

package/src/commands/gateway.ts

@@ -0,0 +1,101 @@
+/**
+ * `promus gateway <sub>` argv dispatcher.
+ *
+ * Subs:
+ *   run       — foreground daemon (blocks; Ctrl+C to stop). Uses operator-session.
+ *   start     — interactive: prompt Touch ID, write operator-session, fork daemon.
+ *   stop      — SIGTERM the running daemon via the lock file's PID.
+ *   restart   — stop + start.
+ *   status    — show PID, uptime, socket path, lock state.
+ *   logs      — tail the gateway log (--tail N, --follow).
+ *
+ * v0.19.x scope: run + start + stop + status. restart/logs/install/setup ship
+ * in v0.19.3 alongside launchd plist generator.
+ */
+
+export type GatewaySub = 'run' | 'start' | 'stop' | 'restart' | 'status' | 'logs'
+
+export interface ParsedGatewayArgs {
+  sub: GatewaySub
+  /** Optional --agent <id> override; defaults to config-derived. */
+  agentId?: string
+  /** --tail N for logs; default 100. */
+  tail?: number
+  /** --follow / -f for logs. */
+  follow?: boolean
+}
+
+export type ParseResult = ParsedGatewayArgs | { error: string }
+
+export function parseGatewayArgs(argv: string[]): ParseResult {
+  const sub = argv[0]
+  if (!sub) {
+    return { error: 'usage: promus gateway <run | start | stop | restart | status | logs>' }
+  }
+  if (!['run', 'start', 'stop', 'restart', 'status', 'logs'].includes(sub)) {
+    return { error: `unknown gateway sub: ${sub}` }
+  }
+  let agentId: string | undefined
+  let tail: number | undefined
+  let follow = false
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--agent') {
+      const v = argv[++i]
+      if (!v) return { error: '--agent requires a value' }
+      agentId = v
+    } else if (a === '--tail') {
+      const v = argv[++i]
+      if (!v) return { error: '--tail requires a value' }
+      const n = Number.parseInt(v, 10)
+      if (!Number.isFinite(n) || n < 0) return { error: '--tail must be a positive integer' }
+      tail = n
+    } else if (a === '--follow' || a === '-f') {
+      follow = true
+    } else {
+      return { error: `unknown flag: ${a}` }
+    }
+  }
+  return { sub: sub as GatewaySub, agentId, tail, follow }
+}
+
+export async function runGateway(parsed: ParsedGatewayArgs): Promise<void> {
+  switch (parsed.sub) {
+    case 'run': {
+      const { runGatewayForeground } = await import('./gateway-run')
+      await runGatewayForeground({ agentId: parsed.agentId })
+      return
+    }
+    case 'start': {
+      const { runGatewayStart } = await import('./gateway-start')
+      await runGatewayStart({ agentId: parsed.agentId })
+      return
+    }
+    case 'stop': {
+      const { runGatewayStop } = await import('./gateway-stop')
+      await runGatewayStop({ agentId: parsed.agentId })
+      return
+    }
+    case 'restart': {
+      const { runGatewayStop } = await import('./gateway-stop')
+      const { runGatewayStart } = await import('./gateway-start')
+      await runGatewayStop({ agentId: parsed.agentId })
+      await runGatewayStart({ agentId: parsed.agentId })
+      return
+    }
+    case 'status': {
+      const { runGatewayStatus } = await import('./gateway-status')
+      await runGatewayStatus({ agentId: parsed.agentId })
+      return
+    }
+    case 'logs': {
+      const { runGatewayLogs } = await import('./gateway-logs')
+      await runGatewayLogs({
+        agentId: parsed.agentId,
+        tail: parsed.tail ?? 100,
+        follow: parsed.follow ?? false,
+      })
+      return
+    }
+  }
+}

package/src/commands/init/cost.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'bun:test'
+import { parseEther } from 'viem'
+import {
+  SANDBOX_BURN_RATE_OG_PER_HOUR,
+  SANDBOX_DEFAULT_INITIAL_DEPOSIT_OG,
+  estimateCosts,
+  renderCostSummary,
+} from './cost'
+
+describe('estimateCosts (0G stack)', () => {
+  // NOTE: the 0G network path still exists in @promus/core but the display
+  // strings have been migrated to ETH / Arbitrum branding.
+  it('local target: zero sandbox fields', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: true,
+      deployTarget: 'local',
+      network: '0g-mainnet',
+    })
+    expect(c.sandboxInitialDepositTestnet).toBe(0n)
+    expect(c.sandboxBurnRatePerHourTestnet).toBe(0n)
+    expect(c.deployTarget).toBe('local')
+    expect(c.totalOperator).toBe(parseEther('3.115'))
+    expect(c.currency).toBe('0G')
+    expect(c.lean).toBe(false)
+  })
+
+  it('sandbox target: populates testnet fields', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: true,
+      deployTarget: 'sandbox',
+      network: '0g-mainnet',
+    })
+    expect(c.sandboxInitialDepositTestnet).toBe(
+      parseEther(String(SANDBOX_DEFAULT_INITIAL_DEPOSIT_OG)),
+    )
+    expect(c.sandboxBurnRatePerHourTestnet).toBe(parseEther(String(SANDBOX_BURN_RATE_OG_PER_HOUR)))
+    expect(c.deployTarget).toBe('sandbox')
+    // mainnet totalOperator UNCHANGED by deploy target (testnet is a separate pool)
+    expect(c.totalOperator).toBe(parseEther('3.115'))
+  })
+
+  it('burn rate equals topup.ts canonical 0.09 0G/hour', () => {
+    expect(SANDBOX_BURN_RATE_OG_PER_HOUR).toBe(0.09)
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: false,
+      deployTarget: 'sandbox',
+      network: '0g-mainnet',
+    })
+    expect(c.sandboxBurnRatePerHourTestnet).toBe(parseEther('0.09'))
+  })
+})
+
+describe('estimateCosts (lean stack: Arbitrum/Claude/IPFS)', () => {
+  it('only real L2 gas: mint + small ETH agent float, no ledger or subname', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 0,
+      withSubname: false,
+      deployTarget: 'local',
+      network: 'arbitrum-sepolia',
+    })
+    expect(c.lean).toBe(true)
+    expect(c.currency).toBe('ETH')
+    expect(c.agentFloat).toBeGreaterThan(0n) // small ETH float for the agent EOA
+    expect(c.computeLedgerDeposit).toBe(0n)
+    expect(c.subnameAndRecords).toBe(0n)
+    expect(c.storageUploadGas).toBe(0n) // anchor paid from the agent float
+    expect(c.sandboxInitialDepositTestnet).toBe(0n)
+    // mint + agent float only — well under a faucet-funded testnet wallet
+    expect(c.totalOperator).toBe(c.mintAndApproveGas + c.agentFloat)
+    expect(c.totalOperator).toBeLessThan(parseEther('0.002'))
+  })
+
+  it('Robinhood Orbit L2 is also lean / ETH', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 10,
+      withSubname: true,
+      deployTarget: 'local',
+      network: 'robinhood-testnet',
+    })
+    expect(c.lean).toBe(true)
+    expect(c.currency).toBe('ETH')
+    // ledger size + subname requests are ignored on the lean stack
+    expect(c.computeLedgerDeposit).toBe(0n)
+    expect(c.subnameAndRecords).toBe(0n)
+  })
+})
+
+describe('renderCostSummary (0G stack)', () => {
+  it('local target: omits sandbox section', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: true,
+      deployTarget: 'local',
+      network: '0g-mainnet',
+    })
+    const out = renderCostSummary(c)
+    expect(out).toContain('operator spend (Arbitrum mainnet)')
+    expect(out).toContain('mint + setApprovalForAll')
+    expect(out).toContain('compute ledger deposit')
+    expect(out).not.toContain('sandbox spend')
+    expect(out).not.toContain('Galileo testnet')
+    expect(out).not.toContain('faucet')
+  })
+
+  it('sandbox target: includes Galileo testnet section with runway + faucet', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: true,
+      deployTarget: 'sandbox',
+      network: '0g-mainnet',
+    })
+    const out = renderCostSummary(c)
+    expect(out).toContain('sandbox spend (Arbitrum testnet, free via faucet):')
+    expect(out).toContain('initial provider deposit')
+    expect(out).toContain('runtime burn')
+    expect(out).toContain('1 ETH')
+    expect(out).toContain('0.09 ETH/h')
+    expect(out).toContain('auto-topup')
+    expect(out).toContain('runway')
+  })
+
+  it('sandbox target: runway expressed in hours for ~1 0G default', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: false,
+      deployTarget: 'sandbox',
+      network: '0g-mainnet',
+    })
+    const out = renderCostSummary(c)
+    // 1 ETH / 0.09 ETH/h = 11.11h
+    expect(out).toMatch(/~11\.[0-9]h runway/)
+  })
+
+  it('still shows USD $0.00 for testnet line', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 3,
+      withSubname: false,
+      deployTarget: 'sandbox',
+      network: '0g-mainnet',
+    })
+    const out = renderCostSummary(c)
+    // Testnet ETH is free — USD col should read ($0.00)
+    expect(out).toMatch(/initial provider deposit\s+1 ETH\s+\(\$0\.00\)/)
+    expect(out).not.toMatch(/initial provider deposit\s+1 ETH\s+\(\$0\.50\)/)
+  })
+})
+
+describe('renderCostSummary (lean stack)', () => {
+  it('ETH gas only: no economy lines', () => {
+    const c = estimateCosts({
+      ledgerSizeOg: 0,
+      withSubname: false,
+      deployTarget: 'local',
+      network: 'arbitrum-sepolia',
+    })
+    const out = renderCostSummary(c)
+    expect(out).toContain('operator spend (ETH L2 gas)')
+    expect(out).toContain('mint + setApprovalForAll')
+    expect(out).toContain('agent gas float')
+    expect(out).toContain('total operator spend')
+    expect(out).not.toContain('0G')
+    expect(out).not.toContain('agent infra float')
+    expect(out).not.toContain('compute ledger deposit')
+    expect(out).not.toContain('sandbox spend')
+  })
+})

package/src/commands/init/cost.ts

@@ -0,0 +1,154 @@
+import {
+  type PromusNetwork,
+  NETWORK_CURRENCY,
+  SANDBOX_BURN_RATE_OG_PER_HOUR,
+  SANDBOX_DEFAULT_INITIAL_DEPOSIT_OG,
+  isOgNetwork,
+} from '@promus/core'
+import { formatEther } from 'viem'
+
+export { SANDBOX_BURN_RATE_OG_PER_HOUR, SANDBOX_DEFAULT_INITIAL_DEPOSIT_OG }
+
+/** ETH spot price used for USD estimates. Not authoritative, just a hint. */
+const ETH_USD = 3500
+
+export type DeployTarget = 'local' | 'sandbox'
+
+export interface CostBreakdown {
+  mintAndApproveGas: bigint
+  agentFloat: bigint
+  computeLedgerDeposit: bigint
+  storageUploadGas: bigint
+  subnameAndRecords: bigint
+  totalOperator: bigint
+  /** Galileo testnet — present only when deployTarget === 'sandbox'. */
+  sandboxInitialDepositTestnet: bigint
+  /** Galileo testnet burn rate per hour, in wei. */
+  sandboxBurnRatePerHourTestnet: bigint
+  deployTarget: DeployTarget
+  /** Native gas-token symbol for the chosen network ('ETH'). */
+  currency: string
+  /** Lean stack = Claude brain + IPFS memory + local runtime. */
+  lean: boolean
+}
+
+export function estimateCosts(opts: {
+  ledgerSizeOg: number
+  withSubname: boolean
+  deployTarget: DeployTarget
+  network: PromusNetwork
+}): CostBreakdown {
+  const currency = NETWORK_CURRENCY[opts.network]
+  const lean = !isOgNetwork(opts.network)
+
+  if (lean) {
+    // Arbitrum-family: only real L2 gas, in ETH. Memory is IPFS (off-chain) and
+    // the brain is Claude (off-chain API key), so there is no compute ledger or
+    // storage cost, and no subname. The operator pays the mint, then seeds a
+    // small ETH float to the agent EOA — the agent spends it on its own
+    // keystore-CID anchor and the per-turn memory-sync anchors. Both numbers
+    // are generous L2 buffers that stay well under a faucet-funded testnet wallet.
+    const mintAndApproveGas = 200_000_000_000_000n // ~0.0002 ETH (mint + setApprovalForAll; ~6x the real L2 cost)
+    const agentFloat = 300_000_000_000_000n // ~0.0003 ETH — agent EOA gas for anchors + ~60 memory syncs
+    const totalOperator = mintAndApproveGas + agentFloat
+    return {
+      mintAndApproveGas,
+      agentFloat,
+      computeLedgerDeposit: 0n,
+      storageUploadGas: 0n,
+      subnameAndRecords: 0n,
+      totalOperator,
+      sandboxInitialDepositTestnet: 0n,
+      sandboxBurnRatePerHourTestnet: 0n,
+      deployTarget: opts.deployTarget,
+      currency,
+      lean,
+    }
+  }
+
+  const mintAndApproveGas = 10_000_000_000_000_000n // ~0.01 ETH (mint + setApprovalForAll bundle)
+  const agentFloat = 100_000_000_000_000_000n // 0.1 ETH — infra float for the agent
+  const computeLedgerDeposit = BigInt(Math.round(opts.ledgerSizeOg * 1e18))
+  const storageUploadGas = 5_000_000_000_000_000n // ~0.005 ETH (storage anchor tx)
+  const subnameAndRecords = opts.withSubname
+    ? 30_000_000_000_000_000n // ~0.03 ETH (claim + 2 text records, paid from agent float)
+    : 0n
+  const totalOperator = mintAndApproveGas + agentFloat + computeLedgerDeposit + storageUploadGas
+  const sandboxInitialDepositTestnet =
+    opts.deployTarget === 'sandbox'
+      ? BigInt(Math.round(SANDBOX_DEFAULT_INITIAL_DEPOSIT_OG * 1e18))
+      : 0n
+  const sandboxBurnRatePerHourTestnet =
+    opts.deployTarget === 'sandbox' ? BigInt(Math.round(SANDBOX_BURN_RATE_OG_PER_HOUR * 1e18)) : 0n
+  return {
+    mintAndApproveGas,
+    agentFloat,
+    computeLedgerDeposit,
+    storageUploadGas,
+    subnameAndRecords,
+    totalOperator,
+    sandboxInitialDepositTestnet,
+    sandboxBurnRatePerHourTestnet,
+    deployTarget: opts.deployTarget,
+    currency,
+    lean,
+  }
+}
+
+export function formatUsd(valueWei: bigint): string {
+  const eth = Number(formatEther(valueWei))
+  return `$${(eth * ETH_USD).toFixed(2)}`
+}
+
+function formatRunway(depositWei: bigint, burnPerHourWei: bigint): string {
+  if (burnPerHourWei === 0n) return ''
+  const hours = Number(depositWei) / Number(burnPerHourWei)
+  if (hours < 1) return `${Math.round(hours * 60)} min runway`
+  if (hours < 48) return `~${hours.toFixed(1)}h runway`
+  const days = hours / 24
+  return `~${days.toFixed(1)}d runway`
+}
+
+export function renderCostSummary(c: CostBreakdown): string {
+  // On the lean stack the gas token is testnet ETH (no market price) — show $0.00.
+  const usd = (wei: bigint): string => (c.lean ? '$0.00' : formatUsd(wei))
+  const line = (label: string, wei: bigint): string =>
+    `    ${label.padEnd(32)}${formatEther(wei).padStart(8)} ${c.currency}  (${usd(wei)})`
+
+  if (c.lean) {
+    // Claude + IPFS + local: operator pays the mint, then seeds the agent EOA
+    // float that covers the keystore-CID anchor + per-turn memory-sync anchors.
+    return [
+      `  operator spend (${c.currency} L2 gas):`,
+      line('mint + setApprovalForAll', c.mintAndApproveGas),
+      line('agent gas float', c.agentFloat),
+      `    ${'─'.repeat(32)}${'─'.repeat(18)}`,
+      line('total operator spend', c.totalOperator),
+    ].join('\n')
+  }
+
+  const lines = [
+    '  operator spend (Arbitrum mainnet):',
+    line('mint + setApprovalForAll', c.mintAndApproveGas),
+    line('storage upload (keystore)', c.storageUploadGas),
+    line('agent infra float', c.agentFloat),
+    line('compute ledger deposit', c.computeLedgerDeposit),
+    `    ${'─'.repeat(32)}${'─'.repeat(18)}`,
+    line('total operator spend', c.totalOperator),
+    '',
+    '  agent spend (from the float):',
+    line('subname + text records', c.subnameAndRecords),
+  ]
+  if (c.deployTarget === 'sandbox') {
+    const runway = formatRunway(c.sandboxInitialDepositTestnet, c.sandboxBurnRatePerHourTestnet)
+    lines.push(
+      '',
+      '  sandbox spend (Arbitrum testnet, free via faucet):',
+      `    ${'initial provider deposit'.padEnd(32)}${formatEther(c.sandboxInitialDepositTestnet).padStart(8)} ETH   ($0.00)`,
+      `    ${'runtime burn'.padEnd(32)}${formatEther(c.sandboxBurnRatePerHourTestnet).padStart(8)} ETH/h (${runway})`,
+      '    fund via       faucet → paste operator address',
+      '    auto-topup     agent EOA refills sandbox billing from compute ledger',
+    )
+  }
+  return lines.join('\n')
+}