@promus/cli 0.24.17

package/src/util/ref-resolver.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'bun:test'
+import { resolvePromusRef } from './ref-resolver'
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+const latestFetch = (tagName: string) =>
+  (() =>
+    Promise.resolve(
+      jsonResponse(200, {
+        tag_name: tagName,
+        published_at: '2026-05-03T04:00:00Z',
+        html_url: `https://github.com/JemIIahh/promus/releases/tag/${tagName}`,
+      }),
+    )) as unknown as typeof fetch
+
+describe('resolvePromusRef', () => {
+  it('defaults to latest when rawRef + env both unset', async () => {
+    const r = await resolvePromusRef(undefined, { fetchImpl: latestFetch('v0.17.8'), env: {} })
+    expect(r.ref).toBe('v0.17.8')
+    expect(r.isTag).toBe(true)
+    expect(r.resolvedFromLatest).toBe(true)
+  })
+  it('resolves explicit "latest" keyword', async () => {
+    const r = await resolvePromusRef('latest', { fetchImpl: latestFetch('v0.17.9'), env: {} })
+    expect(r.ref).toBe('v0.17.9')
+    expect(r.resolvedFromLatest).toBe(true)
+  })
+  it('passes through tag-shaped ref without API call', async () => {
+    let called = false
+    const fetchImpl = (() => {
+      called = true
+      return Promise.resolve(jsonResponse(200, {}))
+    }) as unknown as typeof fetch
+    const r = await resolvePromusRef('v0.17.8', { fetchImpl, env: {} })
+    expect(r.ref).toBe('v0.17.8')
+    expect(r.isTag).toBe(true)
+    expect(r.resolvedFromLatest).toBe(false)
+    expect(called).toBe(false)
+  })
+  it('passes through branch refs as non-tag', async () => {
+    const r = await resolvePromusRef('main', { env: {} })
+    expect(r.ref).toBe('main')
+    expect(r.isTag).toBe(false)
+    expect(r.resolvedFromLatest).toBe(false)
+  })
+  it('passes through SHA refs as non-tag', async () => {
+    const r = await resolvePromusRef('3d6d10f', { env: {} })
+    expect(r.ref).toBe('3d6d10f')
+    expect(r.isTag).toBe(false)
+  })
+  it('respects PROMUS_BOOTSTRAP_REF env override', async () => {
+    let called = false
+    const fetchImpl = (() => {
+      called = true
+      return Promise.resolve(jsonResponse(200, {}))
+    }) as unknown as typeof fetch
+    const r = await resolvePromusRef(undefined, {
+      fetchImpl,
+      env: { PROMUS_BOOTSTRAP_REF: 'main' },
+    })
+    expect(r.ref).toBe('main')
+    expect(r.isTag).toBe(false)
+    expect(called).toBe(false)
+  })
+  it('rawRef takes priority over env', async () => {
+    const r = await resolvePromusRef('v0.17.8', {
+      env: { PROMUS_BOOTSTRAP_REF: 'main' },
+    })
+    expect(r.ref).toBe('v0.17.8')
+    expect(r.isTag).toBe(true)
+  })
+})

package/src/util/ref-resolver.ts

@@ -0,0 +1,55 @@
+import { type GitHubFetchOpts, resolveLatestRelease } from './github-releases'
+
+/** Canonical Promus repo. Override via {@link ResolvePromusRefOpts.repoUrl}. */
+export const PROMUS_REPO_URL = 'https://github.com/JemIIahh/promus.git'
+
+/** Magic ref keyword that triggers GitHub `releases/latest` resolution. */
+export const LATEST_KEYWORD = 'latest'
+
+export interface ResolvedRef {
+  ref: string
+  /** True if `ref` looks like `vX.Y.Z`. Drives pre/post-flight version verification. */
+  isTag: boolean
+  /** True if user said `latest` and we resolved via API — caller skips pre-flight (already source of truth). */
+  resolvedFromLatest: boolean
+}
+
+export interface ResolvePromusRefOpts extends GitHubFetchOpts {
+  repoUrl?: string
+  /** Test seam. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+}
+
+const TAG_RE = /^v\d+\.\d+\.\d+/
+
+/**
+ * Resolve user ref. Priority: rawRef → PROMUS_BOOTSTRAP_REF env → `latest`.
+ * Tag-shaped refs pass through. Branch / SHA refs return isTag=false (no
+ * version verification possible).
+ */
+export async function resolvePromusRef(
+  rawRef: string | undefined,
+  opts: ResolvePromusRefOpts = {},
+): Promise<ResolvedRef> {
+  const env = opts.env ?? process.env
+  const arg = rawRef ?? env.PROMUS_BOOTSTRAP_REF ?? LATEST_KEYWORD
+
+  if (arg === LATEST_KEYWORD) {
+    const release = await resolveLatestRelease(opts.repoUrl ?? PROMUS_REPO_URL, opts)
+    return { ref: release.tagName, isTag: true, resolvedFromLatest: true }
+  }
+  if (TAG_RE.test(arg)) {
+    return { ref: arg, isTag: true, resolvedFromLatest: false }
+  }
+  return { ref: arg, isTag: false, resolvedFromLatest: false }
+}
+
+/** Pretty form of a ResolvedRef for prompts and outros. Adds `(resolved from latest)` suffix when applicable. */
+export function formatResolvedRef(resolved: ResolvedRef): string {
+  return resolved.resolvedFromLatest ? `${resolved.ref} (resolved from latest)` : resolved.ref
+}
+
+/** Expected `package.json` version for a ResolvedRef, or null when no strict expectation (branch / SHA). */
+export function expectedVersionFromRef(resolved: ResolvedRef): string | null {
+  return resolved.isTag ? resolved.ref.replace(/^v/, '') : null
+}

package/src/util/silence-console.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { withSilencedConsole } from './silence-console'
+
+describe('withSilencedConsole', () => {
+  let writes: string[] = []
+  let originalWrite: typeof process.stdout.write
+  beforeEach(() => {
+    writes = []
+    originalWrite = process.stdout.write
+    process.stdout.write = ((chunk: unknown) => {
+      writes.push(typeof chunk === 'string' ? chunk : (chunk?.toString?.() ?? ''))
+      return true
+    }) as typeof process.stdout.write
+  })
+  afterEach(() => {
+    process.stdout.write = originalWrite
+  })
+
+  test('mutes console.log/info/warn/error/debug for the duration of fn', async () => {
+    await withSilencedConsole(async () => {
+      console.log('SHOULD_BE_MUTED_LOG')
+      console.info('SHOULD_BE_MUTED_INFO')
+      console.warn('SHOULD_BE_MUTED_WARN')
+      console.error('SHOULD_BE_MUTED_ERROR')
+      console.debug('SHOULD_BE_MUTED_DEBUG')
+    })
+    expect(writes.join('')).not.toContain('SHOULD_BE_MUTED')
+  })
+
+  test('restores originals after fn resolves', async () => {
+    const before = console.log
+    await withSilencedConsole(async () => {})
+    expect(console.log).toBe(before)
+  })
+
+  test('restores originals after fn throws', async () => {
+    const before = console.log
+    await expect(
+      withSilencedConsole(async () => {
+        throw new Error('boom')
+      }),
+    ).rejects.toThrow('boom')
+    expect(console.log).toBe(before)
+  })
+
+  test('returns the value produced by fn', async () => {
+    const result = await withSilencedConsole(async () => {
+      console.log('noise')
+      return 42
+    })
+    expect(result).toBe(42)
+  })
+})

package/src/util/silence-console.ts

@@ -0,0 +1,40 @@
+/**
+ * Run `fn` with `console.log/info/warn/error/debug` swapped for no-ops so they
+ * cannot interleave with clack's in-place spinner re-render. Originals are
+ * restored even if `fn` throws.
+ *
+ * Why: 0G Storage SDK and 0G Compute broker SDK both `console.log` directly
+ * during their work (selected nodes, upload progress, broker tx hashes, etc).
+ * When a clack spinner is running, every leaked log line pushes the spinner
+ * down and the next animation frame draws a new spinner row, creating the
+ * "100x stacked spinner" visual we saw on the WC init test. Suppressing these
+ * during the spinner-active phases keeps the wizard output clean.
+ *
+ * Note: `chat.tsx` does its own process-lifetime console redirect to a chat
+ * log file. That cannot use this helper because its lifetime is the whole
+ * session, not a scoped wrap. Keep the two pathways separate.
+ */
+export async function withSilencedConsole<T>(fn: () => Promise<T>): Promise<T> {
+  const orig = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+  }
+  const noop = (() => {}) as (...args: unknown[]) => void
+  console.log = noop as typeof console.log
+  console.info = noop as typeof console.info
+  console.warn = noop as typeof console.warn
+  console.error = noop as typeof console.error
+  console.debug = noop as typeof console.debug
+  try {
+    return await fn()
+  } finally {
+    console.log = orig.log
+    console.info = orig.info
+    console.warn = orig.warn
+    console.error = orig.error
+    console.debug = orig.debug
+  }
+}

package/src/util/telegram-secrets.test.ts

@@ -0,0 +1,227 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  OPERATOR_BLOB_SCOPES,
+  RawPrivkeyOperatorSigner,
+  agentPaths,
+  deriveBlobKey,
+  iNFTAgentId,
+} from '@promus/core'
+import { type Address, generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import {
+  loadTelegramHandoffSecrets,
+  looksLikeBotToken,
+  parseAllowedUserIds,
+  saveTelegramSecrets,
+  telegramSecretsPath,
+} from './telegram-secrets'
+
+describe('looksLikeBotToken', () => {
+  it('accepts a real-shaped token', () => {
+    expect(looksLikeBotToken('8776805236:AAGgfvp2AwYBvDc3COYfjC9m8w2s0e4t4hw')).toBe(true)
+  })
+
+  it('rejects empty / wrong delimiters', () => {
+    expect(looksLikeBotToken('')).toBe(false)
+    expect(looksLikeBotToken('8776805236-AAGgfvp2AwYBvDc3COYfjC9m8w2s0e4t4hw')).toBe(false)
+    expect(looksLikeBotToken('AAGgfvp2AwYBvDc3COYfjC9m8w2s0e4t4hw')).toBe(false)
+  })
+
+  it('rejects too-short secret half', () => {
+    expect(looksLikeBotToken('1234567890:short')).toBe(false)
+  })
+
+  it('trims surrounding whitespace before checking', () => {
+    expect(looksLikeBotToken('  8731160904:AAH8FQ3CLrE8-WAfZtDeOTqmpVgOFLg8GyU\n')).toBe(true)
+  })
+})
+
+describe('parseAllowedUserIds', () => {
+  it('returns empty list for blank input', () => {
+    const r = parseAllowedUserIds('')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ids).toEqual([])
+  })
+
+  it('parses a comma-separated list', () => {
+    const r = parseAllowedUserIds('123, 456, 789')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ids).toEqual([123, 456, 789])
+  })
+
+  it('parses whitespace-only delimiters', () => {
+    const r = parseAllowedUserIds('123  456\t789')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ids).toEqual([123, 456, 789])
+  })
+
+  it('dedupes preserving first-seen order', () => {
+    const r = parseAllowedUserIds('123, 456, 123')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ids).toEqual([123, 456])
+  })
+
+  it('rejects non-numeric ids', () => {
+    const r = parseAllowedUserIds('123, abc')
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.reason).toContain('abc')
+  })
+
+  it('rejects negative ids', () => {
+    const r = parseAllowedUserIds('-123')
+    expect(r.ok).toBe(false)
+  })
+
+  it('rejects zero', () => {
+    const r = parseAllowedUserIds('0')
+    expect(r.ok).toBe(false)
+  })
+})
+
+describe('loadTelegramHandoffSecrets', () => {
+  // Each test gets a fresh PROMUS_ROOT tmpdir so `agentPaths.agent(id).dir`
+  // resolves somewhere isolated, and `afterEach` cleans it up even on failure.
+  const TEST_CONTRACT = '0x9e71d79f06f956d4d2666b5c93dafab721c84721' as Address
+  const TEST_TOKEN_ID = 6n
+  const TEST_AGENT_ID = iNFTAgentId({
+    contractAddress: TEST_CONTRACT,
+    tokenId: TEST_TOKEN_ID,
+  })
+
+  let prevPromusRoot: string | undefined
+  let tmpRoot: string
+
+  beforeAll(() => {
+    prevPromusRoot = process.env.PROMUS_ROOT
+  })
+  afterAll(() => {
+    if (prevPromusRoot === undefined) Reflect.deleteProperty(process.env, 'PROMUS_ROOT')
+    else process.env.PROMUS_ROOT = prevPromusRoot
+  })
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'promus-tg-secrets-test-'))
+    process.env.PROMUS_ROOT = tmpRoot
+  })
+  afterEach(() => {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  })
+
+  it('returns undefined when no blob exists on disk', async () => {
+    const operatorPrivkey = generatePrivateKey()
+    const signer = new RawPrivkeyOperatorSigner({ privkey: operatorPrivkey })
+    const agentAddress = privateKeyToAccount(generatePrivateKey()).address
+    let notices = 0
+    const result = await loadTelegramHandoffSecrets({
+      signer,
+      agentAddress,
+      contractAddress: TEST_CONTRACT,
+      tokenId: TEST_TOKEN_ID,
+      onNotice: () => {
+        notices += 1
+      },
+    })
+    expect(result).toBeUndefined()
+    expect(notices).toBe(0)
+  })
+
+  it('round-trips through saveTelegramSecrets and returns handoff subset', async () => {
+    const operatorPrivkey = generatePrivateKey()
+    const signer = new RawPrivkeyOperatorSigner({ privkey: operatorPrivkey })
+    const agentAddress = privateKeyToAccount(generatePrivateKey()).address
+    await saveTelegramSecrets({
+      signer,
+      agentAddress,
+      agentId: TEST_AGENT_ID,
+      plaintext: {
+        botToken: '8731160904:AAH8FQ3CLrE8-WAfZtDeOTqmpVgOFLg8GyU',
+        botUsername: 'promus_test_bot',
+        botId: 8731160904,
+        allowedUserIds: [1140813034, 222333444],
+      },
+    })
+    expect(existsSync(telegramSecretsPath(TEST_AGENT_ID))).toBe(true)
+
+    const result = await loadTelegramHandoffSecrets({
+      signer,
+      agentAddress,
+      contractAddress: TEST_CONTRACT,
+      tokenId: TEST_TOKEN_ID,
+    })
+    expect(result).toEqual({
+      botToken: '8731160904:AAH8FQ3CLrE8-WAfZtDeOTqmpVgOFLg8GyU',
+      allowedUserIds: [1140813034, 222333444],
+    })
+  })
+
+  it('swallows decrypt errors via onNotice and returns undefined', async () => {
+    const operatorPrivkey = generatePrivateKey()
+    const signer = new RawPrivkeyOperatorSigner({ privkey: operatorPrivkey })
+    const agentAddress = privateKeyToAccount(generatePrivateKey()).address
+    // Write a malformed blob: file exists but contents fail decode.
+    const path = telegramSecretsPath(TEST_AGENT_ID)
+    const agentDir = agentPaths.agent(TEST_AGENT_ID).dir
+    mkdirSync(agentDir, { recursive: true })
+    writeFileSync(path, 'not-a-valid-operator-blob-payload')
+
+    const notices: string[] = []
+    const result = await loadTelegramHandoffSecrets({
+      signer,
+      agentAddress,
+      contractAddress: TEST_CONTRACT,
+      tokenId: TEST_TOKEN_ID,
+      onNotice: msg => {
+        notices.push(msg)
+      },
+    })
+    expect(result).toBeUndefined()
+    expect(notices.length).toBe(1)
+    expect(notices[0]).toMatch(/telegram secrets read failed:/)
+  })
+
+  // v0.24.3: precomputedKey path — used by init wizard so the derived TELEGRAM
+  // scope key can be passed to saveTelegramSecrets AND stashed in
+  // `.operator-session` in a single derive. Without this, the daemon
+  // fail-louds at boot ("telegram secrets present but no telegram scope key").
+  it('round-trips with precomputedKey (init-wizard fast path)', async () => {
+    const operatorPrivkey = generatePrivateKey()
+    const signer = new RawPrivkeyOperatorSigner({ privkey: operatorPrivkey })
+    const agentAddress = privateKeyToAccount(generatePrivateKey()).address
+    // Derive the TELEGRAM scope key explicitly (mirrors what runTelegramStep
+    // does so it can both encrypt AND stash the key in operator-session).
+    const tgKey = await deriveBlobKey(signer, agentAddress, OPERATOR_BLOB_SCOPES.TELEGRAM)
+    expect(tgKey.length).toBe(32)
+
+    await saveTelegramSecrets({
+      signer,
+      agentAddress,
+      agentId: TEST_AGENT_ID,
+      plaintext: {
+        botToken: '8152506307:AAFbXSJ0qnfJNbLWkxbmzYEM9fc74uaznJs',
+        botUsername: 'promus_init_test_bot',
+        botId: 8152506307,
+        allowedUserIds: [1140813034],
+      },
+      precomputedKey: tgKey,
+    })
+    expect(existsSync(telegramSecretsPath(TEST_AGENT_ID))).toBe(true)
+
+    const result = await loadTelegramHandoffSecrets({
+      signer,
+      agentAddress,
+      contractAddress: TEST_CONTRACT,
+      tokenId: TEST_TOKEN_ID,
+    })
+    expect(result).toEqual({
+      botToken: '8152506307:AAFbXSJ0qnfJNbLWkxbmzYEM9fc74uaznJs',
+      allowedUserIds: [1140813034],
+    })
+
+    // Independent re-derive must produce the SAME 32-byte key (deterministic
+    // HKDF output). This is what lets the daemon load the cached key from
+    // `.operator-session` and successfully decrypt the blob the wizard wrote.
+    const tgKey2 = await deriveBlobKey(signer, agentAddress, OPERATOR_BLOB_SCOPES.TELEGRAM)
+    expect(Buffer.compare(tgKey, tgKey2)).toBe(0)
+  })
+})

package/src/util/telegram-secrets.ts

@@ -0,0 +1,223 @@
+/**
+ * Local persistence for telegram bot secrets, encrypted via the operator's
+ * sign-derived AEAD key (scope `OPERATOR_BLOB_SCOPES.TELEGRAM`).
+ *
+ * On-disk file: `~/.promus/agents/<id>/telegram-secrets.encrypted`
+ *
+ *   {
+ *     version: 2,
+ *     scope: 'promus-telegram-v1',
+ *     blob: <base64(iv|tag|ciphertext)>,
+ *   }
+ *
+ * Plaintext shape inside the blob:
+ *
+ *   {
+ *     botToken: string,         // from @BotFather
+ *     botUsername?: string,     // cached at setup-time getMe
+ *     botId?: number,           // cached at setup-time getMe
+ *     allowedUserIds: number[],
+ *   }
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  OPERATOR_BLOB_SCOPES,
+  type OperatorEncryptedBlob,
+  type OperatorSigner,
+  agentPaths,
+  decodeOperatorBlobBytes,
+  decryptOperatorBlob,
+  encodeOperatorBlobBytes,
+  encryptOperatorBlob,
+  iNFTAgentId,
+} from '@promus/core'
+import type { Address } from 'viem'
+
+export interface TelegramSecretsPlaintext {
+  botToken: string
+  botUsername?: string
+  botId?: number
+  allowedUserIds: number[]
+}
+
+/**
+ * Subset of `TelegramSecretsPlaintext` that the CLI ships into the harness
+ * provision envelope on init / upgrade / resume. The harness doesn't need
+ * the operator-side metadata (`botUsername`, `botId`); it only needs the
+ * token + allowlist + optional pairing list. Centralising this as a named
+ * type avoids drift between the four CLI handoff sites that previously
+ * inlined the literal shape (init wizard, upgrade, resume, the
+ * `HandoffAgentToGateway` + `ResumeArchivedSandbox` interfaces).
+ */
+export interface TelegramHandoffSecrets {
+  botToken: string
+  allowedUserIds: number[]
+  pairingApproved?: number[]
+}
+
+export function telegramSecretsPath(agentId: string): string {
+  return join(agentPaths.agent(agentId).dir, 'telegram-secrets.encrypted')
+}
+
+export function telegramSecretsExist(agentId: string): boolean {
+  return existsSync(telegramSecretsPath(agentId))
+}
+
+export async function loadTelegramSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  agentId: string
+}): Promise<TelegramSecretsPlaintext | null> {
+  const path = telegramSecretsPath(opts.agentId)
+  if (!existsSync(path)) return null
+  const fileBytes = await readFile(path)
+  const blob: OperatorEncryptedBlob = decodeOperatorBlobBytes(new Uint8Array(fileBytes))
+  const ptBytes = await decryptOperatorBlob({
+    signer: opts.signer,
+    scope: OPERATOR_BLOB_SCOPES.TELEGRAM,
+    agentAddress: opts.agentAddress,
+    blob,
+  })
+  const parsed = JSON.parse(new TextDecoder().decode(ptBytes)) as TelegramSecretsPlaintext
+  if (typeof parsed.botToken !== 'string' || !Array.isArray(parsed.allowedUserIds)) {
+    throw new Error('telegram-secrets: malformed plaintext (missing botToken or allowedUserIds)')
+  }
+  return parsed
+}
+
+/**
+ * Load + project telegram secrets into the shape the gateway provision envelope
+ * expects. Used by every sandbox-handoff flow that ships TG (init/upgrade/
+ * resume/deploy/chat-sandbox auto-resume); centralises the try/decrypt/swallow
+ * pattern so future TG-secret schema changes touch one place.
+ *
+ * Errors are non-fatal: TG is opt-in. Failure fires `onNotice` (so the operator
+ * sees the reason in the spinner) and returns undefined.
+ *
+ * `chat.tsx` keeps its own loader because it needs the full plaintext (including
+ * `botUsername` for the unlock spinner UX).
+ */
+export async function loadTelegramHandoffSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  contractAddress: Address
+  tokenId: bigint
+  onNotice?: (msg: string) => void
+}): Promise<TelegramHandoffSecrets | undefined> {
+  const agentId = iNFTAgentId({
+    contractAddress: opts.contractAddress,
+    tokenId: opts.tokenId,
+  })
+  try {
+    const tg = await loadTelegramSecrets({
+      signer: opts.signer,
+      agentAddress: opts.agentAddress,
+      agentId,
+    })
+    if (!tg) return undefined
+    return { botToken: tg.botToken, allowedUserIds: tg.allowedUserIds }
+  } catch (err) {
+    opts.onNotice?.(`telegram secrets read failed: ${(err as Error).message.slice(0, 120)}`)
+    return undefined
+  }
+}
+
+export async function saveTelegramSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  agentId: string
+  plaintext: TelegramSecretsPlaintext
+  /**
+   * v0.24.3: pre-derived TELEGRAM scope key (32 bytes). The init wizard
+   * derives this once and passes it both here AND into `.operator-session`,
+   * so encryptOperatorBlob skips the redundant sign it would otherwise make.
+   * Threads through to encryptOperatorBlob; see that helper for fallback.
+   */
+  precomputedKey?: Buffer
+}): Promise<void> {
+  const path = telegramSecretsPath(opts.agentId)
+  await mkdir(dirname(path), { recursive: true })
+  const ptBytes = new TextEncoder().encode(JSON.stringify(opts.plaintext))
+  const blob = await encryptOperatorBlob({
+    signer: opts.signer,
+    scope: OPERATOR_BLOB_SCOPES.TELEGRAM,
+    agentAddress: opts.agentAddress,
+    plaintext: ptBytes,
+    precomputedKey: opts.precomputedKey,
+  })
+  await writeFile(path, encodeOperatorBlobBytes(blob))
+}
+
+export async function removeTelegramSecrets(agentId: string): Promise<boolean> {
+  const path = telegramSecretsPath(agentId)
+  if (!existsSync(path)) return false
+  await rm(path, { force: true })
+  return true
+}
+
+const BOT_TOKEN_RE = /^\d{6,15}:[A-Za-z0-9_-]{30,}$/
+
+export function looksLikeBotToken(s: string): boolean {
+  return BOT_TOKEN_RE.test(s.trim())
+}
+
+export interface ValidatedBotInfo {
+  id: number
+  username: string
+  firstName: string
+}
+
+/**
+ * Telegram Bot API getMe — cheap, free, no message side-effect. Used by
+ * `promus telegram setup` to validate the token before persisting it AND by
+ * `promus telegram status` to confirm the stored token still works.
+ *
+ * Throws on non-200 / `ok: false` with a clean error message; caller wraps
+ * the throw in a clack spinner.stop().
+ */
+export async function fetchBotInfo(
+  botToken: string,
+  opts?: { signal?: AbortSignal },
+): Promise<ValidatedBotInfo> {
+  const url = `https://api.telegram.org/bot${encodeURIComponent(botToken)}/getMe`
+  const res = await fetch(url, { signal: opts?.signal })
+  if (!res.ok) {
+    throw new Error(`getMe HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`)
+  }
+  const body = (await res.json()) as {
+    ok: boolean
+    description?: string
+    result?: { id: number; username?: string; first_name?: string }
+  }
+  if (!body.ok || !body.result) {
+    throw new Error(`getMe rejected: ${body.description ?? 'unknown error'}`)
+  }
+  if (!body.result.username) throw new Error('bot has no username; create one in @BotFather')
+  return {
+    id: body.result.id,
+    username: body.result.username,
+    firstName: body.result.first_name ?? body.result.username,
+  }
+}
+
+export function parseAllowedUserIds(
+  input: string,
+): { ok: true; ids: number[] } | { ok: false; reason: string } {
+  const trimmed = input.trim()
+  if (trimmed.length === 0) return { ok: true, ids: [] }
+  const parts = trimmed
+    .split(/[,\s]+/)
+    .map(p => p.trim())
+    .filter(p => p.length > 0)
+  const ids: number[] = []
+  for (const p of parts) {
+    if (!/^\d+$/.test(p)) return { ok: false, reason: `not a numeric id: "${p}"` }
+    const n = Number(p)
+    if (!Number.isFinite(n) || n <= 0) return { ok: false, reason: `not a positive id: "${p}"` }
+    ids.push(n)
+  }
+  // Dedupe, preserve first-seen order.
+  return { ok: true, ids: [...new Set(ids)] }
+}