@uniquedivine/tg-sai 0.0.5 → 0.1.0

package/main.ts

@@ -1,5 +1,4 @@
 #!/usr/bin/env bun
-import { appendFileSync } from "node:fs"
 import {
   mkdir,
   mkdtemp,
@@ -17,7 +16,7 @@ import { Command } from "commander"
 import { addProvisionCommands } from "./provisioningCli"
 import { addCustodyWorkerCommands } from "./custodyWorkerCli"
 import type { BatchLogger } from "./actionExecutor"
-import { withFloodWaitRetry } from "./actionExecutor"
+import { runChatBatch, runTelegramAction } from "./actionExecutor"
 import type {
   ChatAuditInput,
   ChatMemberData,
@@ -27,6 +26,17 @@ import { planAdminBootstrap } from "./adminAudit"
 import { saiBot, USERS } from "./cfg"
 import { runHealthCheck } from "./health"
 import { addRuntimeHealthCommands } from "./runtimeHealthCli"
+import { HOLD_ACCOUNT_UNKNOWN, holdErrorSeconds } from "./state/guard"
+import { stateDbPath } from "./state/db"
+import { registerEventsCommand } from "./telemetry/cli"
+import { registerHoldsCommand } from "./state/cli"
+import type { TelemetrySubsystem } from "./telemetry/db"
+import {
+  activeTelemetryRun,
+  BOOTSTRAP_FLOOD_MAX_WAIT_MS,
+  floodMaxWaitMs,
+  startTelemetryRun,
+} from "./telemetry/run"
 import {
   addTargetToChat,
   createMtcuteClient,
@@ -53,7 +63,7 @@ import {
   readConfig,
   redactedProfile,
   removeProfile,
-  resolveTelegramCredentials,
+  resolveTelegramCredentialSource,
   setActiveProfile,
 } from "./profiles"
 import type {
@@ -120,12 +130,15 @@ interface SaiBootstrapOptions {
   targetUser?: number | string
 }
 
-
 interface TelegramEnv {
   apiId: number
   apiHash: string
   session: string
   password: string | null
+  /** Saved account user ID, when the profile records one. */
+  userId: number | null
+  /** Selected profile label, for telemetry. */
+  profileName: string | null
 }
 
 interface ProfileAddOptions {
@@ -185,17 +198,14 @@ const ownerTargetAdminRights = {
 }
 
 const DEFAULT_INTER_CHAT_DELAY_MS = 1000
-let activeJsonLogPath: string | null = null
 
 /**
- * Emits one structured JSON object to stdout and the active JSONL log, if set.
+ * Emits one structured JSON object to stdout. Durable records live in the
+ * telemetry DB (`tg-sai events`); stdout is for the operator.
  */
 function emitJsonObject(fields: Record<string, unknown>): void {
-  const line = JSON.stringify({ ts: new Date().toISOString(), ...fields })
-  console.log(line)
-  if (activeJsonLogPath) {
-    appendFileSync(activeJsonLogPath, `${line}\n`, "utf8")
-  }
+  const object = { ts: new Date().toISOString(), ...fields }
+  console.log(JSON.stringify(object))
 }
 
 /**
@@ -218,15 +228,13 @@ function sleep(ms: number): Promise<void> {
 }
 
 /**
- * Builds the default retry dependencies for live Telegram actions.
+ * Progress-logging dependencies for live Telegram actions. Flood waits are
+ * handled by mtcute's flood waiter, not here.
  */
 function actionExecutorDeps(logger: BatchLogger = consoleBatchLogger) {
   return {
     logger,
-    sleep,
     now: () => Date.now(),
-    maxRetries: 3,
-    bufferMs: 2000,
   }
 }
 
@@ -249,19 +257,21 @@ function printJsonEvent(type: string, fields: Record<string, unknown>): void {
 }
 
 /**
- * Returns the directory for durable tg-sai run and discovery logs.
+ * Directory for `ops sai-find` chat files. These are command output (chat
+ * lists for `ops sai-bootstrap --file`), not logs; logs live in the
+ * telemetry DB.
  */
-function logsDir(): string {
+function chatFilesDir(): string {
   return join(configDir(), "logs")
 }
 
 /**
- * Chooses the next numbered JSONL log path for a named command prefix.
+ * Chooses the next numbered chat file path for a named command prefix.
  *
  * Example output paths are `sai-find-00.jsonl`, `sai-find-01.jsonl`, and so on.
  */
-async function nextJsonlLogPath(prefix: string): Promise<string> {
-  const dir = logsDir()
+async function nextChatFilePath(prefix: string): Promise<string> {
+  const dir = chatFilesDir()
   await mkdir(dir, { recursive: true, mode: 0o700 })
 
   const files = await readdir(dir).catch((error) => {
@@ -288,7 +298,8 @@ async function nextJsonlLogPath(prefix: string): Promise<string> {
 }
 
 async function getTelegramEnv(profileName?: string): Promise<TelegramEnv> {
-  const credentials = await resolveTelegramCredentials(profileName)
+  const { credentials, source } =
+    await resolveTelegramCredentialSource(profileName)
   const config = await readConfig()
   const profile = getProfile(config, profileName)
   return {
@@ -296,9 +307,20 @@ async function getTelegramEnv(profileName?: string): Promise<TelegramEnv> {
     apiHash: credentials.apiHash,
     session: credentials.sessionString,
     password: process.env.TELEGRAM_PASSWORD ?? profile?.password ?? null,
+    // TELEGRAM_* or credential-file sessions may act as another account.
+    userId: source === "profile" ? (profile?.userId ?? null) : null,
+    profileName: profile?.name || profileName || null,
   }
 }
 
+/** Telegram telemetry for the current CLI run, if one was started. */
+function cliTelemetry(identity: {
+  accountId?: number | null
+  profile?: string | null
+} = {}) {
+  return activeTelemetryRun()?.client(identity)
+}
+
 async function selectedProfileName(
   profileName?: string,
 ): Promise<string | null> {
@@ -373,11 +395,16 @@ async function withClient<T>(
   ) => Promise<T>,
 ): Promise<T> {
   const env = await getTelegramEnv(profileName)
-  const client = await createMtcuteClient({
-    apiId: env.apiId,
-    apiHash: env.apiHash,
-    session: env.session,
-  })
+  // No `accountId`: the flood guard keys holds by the account this session's
+  // own getMe reports, never by profile metadata.
+  const client = await createMtcuteClient(
+    {
+      apiId: env.apiId,
+      apiHash: env.apiHash,
+      session: env.session,
+    },
+    cliTelemetry({ accountId: env.userId, profile: env.profileName }),
+  )
 
   try {
     return await fn(client, env)
@@ -397,13 +424,19 @@ async function runAudit(options: BaseCliOptions): Promise<void> {
 }
 
 async function runHealth(): Promise<void> {
+  // runHealthCheck connects as the active (first) profile. Its saved
+  // userId only labels telemetry; the flood guard keys by the session's getMe.
+  const accountId = (await readConfig()).profiles[0]?.userId ?? null
   const result = await runHealthCheck({
     createClient: async (credentials) =>
-      createMtcuteClient({
-        apiId: credentials.apiId,
-        apiHash: credentials.apiHash,
-        session: credentials.sessionString,
-      }),
+      createMtcuteClient(
+        {
+          apiId: credentials.apiId,
+          apiHash: credentials.apiHash,
+          session: credentials.sessionString,
+        },
+        cliTelemetry({ accountId }),
+      ),
   })
   for (const line of result.lines) {
     console.log(line)
@@ -591,13 +624,13 @@ async function runSaiFind(options: SaiFindOptions): Promise<void> {
     })
     const lines = records.map(formatSaiChatJsonLine)
     const contents = `${lines.join("\n")}\n`
-    const logPath = await nextJsonlLogPath("sai-find")
+    const chatFilePath = await nextChatFilePath("sai-find")
 
-    await writeFile(logPath, contents, {
+    await writeFile(chatFilePath, contents, {
       encoding: "utf8",
       mode: 0o600,
     })
-    console.log(`wrote_chat_file: ${logPath}`)
+    console.log(`wrote_chat_file: ${chatFilePath}`)
     if (options.out) {
       await writeFile(options.out, contents, {
         encoding: "utf8",
@@ -659,7 +692,7 @@ async function applyTargetPlan(params: {
 
   const deps = actionExecutorDeps(actorBatchLogger(params.actorUsername))
   if (shouldRunAction(beforePlan.proposedActions, "add target user")) {
-    await withFloodWaitRetry(
+    await runTelegramAction(
       {
         chatId: params.chat.chatId,
         action: `${params.actionPrefix}_add`,
@@ -676,7 +709,7 @@ async function applyTargetPlan(params: {
   if (
     shouldRunAction(beforePlan.proposedActions, "promote target user admin")
   ) {
-    await withFloodWaitRetry(
+    await runTelegramAction(
       {
         chatId: params.chat.chatId,
         action: `${params.actionPrefix}_promote_admin`,
@@ -751,7 +784,7 @@ async function maybeTransferOwner(params: {
     return
   }
 
-  await withFloodWaitRetry(
+  await runTelegramAction(
     {
       chatId: params.chat.chatId,
       action: "transfer_owner",
@@ -771,7 +804,11 @@ async function maybeTransferOwner(params: {
  *
  * The command is dry-run by default. In execution mode, it applies the Sai bot
  * update and owner-target update for each chat, logs per-chat failures, and
- * continues to the next chat.
+ * continues to the next chat. A `PEER_FLOOD` or a flood wait longer than the
+ * run's threshold stops the batch with a `flood_stop` event and exit code 1.
+ * A refusal by the local flood guard (a saved hold, unreadable hold state,
+ * or an unverified session account) stops it the same way with exit 75.
+ * `SLOWMODE_WAIT_X` only fails that chat.
  */
 async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
   const contents = await readFile(options.file, "utf8")
@@ -780,24 +817,20 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
   if (!Number.isFinite(delayMs) || delayMs < 0) {
     throw new Error("--delay-ms must be a non-negative number")
   }
-  const logPath = await nextJsonlLogPath("sai-bootstrap")
-  await writeFile(logPath, "", {
-    encoding: "utf8",
-    mode: 0o600,
-  })
+  // Telegram calls are in the telemetry DB under this run id.
+  const runId = activeTelemetryRun()?.context.runId ?? null
 
   await withClient(options.profile, async (client, env) => {
-    activeJsonLogPath = logPath
     const actor = normalizeUser(await client.getMe())
     const actorUsername = actor.username ?? ""
     const profileName = await selectedProfileName(options.profile)
     const ownerTarget = resolveBootstrapTarget(options.targetUser)
     const ownershipTransferEnabled =
       options.transferOwner !== false && env.password !== null
-    console.log(`wrote_run_log: ${logPath}`)
+    if (runId) console.log(`telemetry_run_id: ${runId}`)
     printJsonEvent("run_start", {
       file: options.file,
-      logPath,
+      runId,
       profileName,
       actor,
       chatCount: chats.length,
@@ -809,8 +842,12 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
       targetBot: saiBot.id,
     })
 
-    try {
-      for (const [i, chat] of chats.entries()) {
+    const maxWaitMs =
+      activeTelemetryRun()?.floodMaxWaitMs ??
+      floodMaxWaitMs("cli", process.env, BOOTSTRAP_FLOOD_MAX_WAIT_MS)
+    const { floodStop } = await runChatBatch(chats, {
+      maxWaitMs,
+      processItem: async (chat, i) => {
         printJsonEvent("chat_start", {
           index: i + 1,
           total: chats.length,
@@ -818,69 +855,84 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
           title: chat.title,
           actorUsername,
         })
+        await applyTargetPlan({
+          client,
+          chat,
+          actorUsername,
+          targetUserId: saiBot.id,
+          targetPeer: saiBot.handle,
+          rights: saiBotAdminRights,
+          actionPrefix: "bot",
+          run: options.run === true,
+        })
+        await applyTargetPlan({
+          client,
+          chat,
+          actorUsername,
+          targetUserId: ownerTarget,
+          targetPeer: ownerTarget,
+          rights: ownerTargetAdminRights,
+          actionPrefix: "owner_target",
+          run: options.run === true,
+        })
+        await maybeTransferOwner({
+          client,
+          env,
+          chat,
+          actorUsername,
+          targetUser: ownerTarget,
+          enabled: ownershipTransferEnabled,
+          run: options.run === true,
+        })
+        printJsonEvent("chat_complete", {
+          chatId: chat.chatId,
+          actorUsername,
+        })
+      },
+      onItemError: (chat, error) => {
+        printJsonEvent("chat_error", {
+          chatId: chat.chatId,
+          actorUsername,
+          errorName: error instanceof Error ? error.name : "UnknownError",
+          errorMessage:
+            error instanceof Error ? error.message : String(error),
+        })
+      },
+      betweenItems: async (chat) => {
+        if (delayMs <= 0) return
+        printJsonEvent("chat_delay", {
+          chatId: chat.chatId,
+          actorUsername,
+          delayMs,
+        })
+        await sleep(delayMs)
+      },
+    })
 
-        try {
-          await applyTargetPlan({
-            client,
-            chat,
-            actorUsername,
-            targetUserId: saiBot.id,
-            targetPeer: saiBot.handle,
-            rights: saiBotAdminRights,
-            actionPrefix: "bot",
-            run: options.run === true,
-          })
-          await applyTargetPlan({
-            client,
-            chat,
-            actorUsername,
-            targetUserId: ownerTarget,
-            targetPeer: ownerTarget,
-            rights: ownerTargetAdminRights,
-            actionPrefix: "owner_target",
-            run: options.run === true,
-          })
-          await maybeTransferOwner({
-            client,
-            env,
-            chat,
-            actorUsername,
-            targetUser: ownerTarget,
-            enabled: ownershipTransferEnabled,
-            run: options.run === true,
-          })
-          printJsonEvent("chat_complete", {
-            chatId: chat.chatId,
-            actorUsername,
-          })
-        } catch (error) {
-          printJsonEvent("chat_error", {
-            chatId: chat.chatId,
-            actorUsername,
-            errorName: error instanceof Error ? error.name : "UnknownError",
-            errorMessage:
-              error instanceof Error ? error.message : String(error),
-          })
-        }
-
-        if (delayMs > 0 && i < chats.length - 1) {
-          printJsonEvent("chat_delay", {
-            chatId: chat.chatId,
-            actorUsername,
-            delayMs,
-          })
-          await sleep(delayMs)
-        }
-      }
-
-      printJsonEvent("run_complete", {
-        file: options.file,
-        logPath,
-        chatCount: chats.length,
+    if (floodStop) {
+      // The rest of the batch would hit the same account-wide limit.
+      printJsonEvent("flood_stop", {
+        chatId: floodStop.item.chatId,
+        actorUsername,
+        index: floodStop.index + 1,
+        total: chats.length,
+        remaining: floodStop.remaining,
+        code: floodStop.code,
+        waitS: floodStop.waitS,
+        resumeAt: floodStop.resumeAt,
+        hold: floodStop.hold,
       })
-    } finally {
-      activeJsonLogPath = null
+      // A saved hold is a retry-later stop (75); Telegram's own long wait
+      // or PEER_FLOOD keeps exit 1.
+      process.exitCode = floodStop.hold ? HOLD_EXIT_CODE : 1
+      return
     }
+
+    printJsonEvent("run_complete", {
+      file: options.file,
+      runId,
+      chatCount: chats.length,
+    })
   })
 }
 
@@ -1253,16 +1305,24 @@ async function inputFromProfileAddOptions(
     }
   }
 
+  const knownUserId =
+    options.userId && /^\d+$/.test(options.userId)
+      ? Number(options.userId)
+      : undefined
   const completeProfileFields: TelegramCredentials = {
     apiId: profileFields.apiId,
     apiHash: profileFields.apiHash,
     sessionString: profileFields.sessionString,
   }
-  const client = await createMtcuteClient({
-    apiId: completeProfileFields.apiId,
-    apiHash: completeProfileFields.apiHash,
-    session: completeProfileFields.sessionString,
-  })
+  const client = await createMtcuteClient(
+    {
+      apiId: completeProfileFields.apiId,
+      apiHash: completeProfileFields.apiHash,
+      session: completeProfileFields.sessionString,
+      // --user-id is unverified, so the guard keys by the session's getMe.
+    },
+    cliTelemetry({ accountId: knownUserId ?? null, profile: options.name ?? null }),
+  )
   try {
     const self = await client.getMe()
     return profileInputFromUser(
@@ -1462,6 +1522,10 @@ export function createProgram(): Command {
     program.help({ error: false })
   })
 
+  program.hook("preAction", (_root, actionCommand) => {
+    startCliTelemetryRun(actionCommand)
+  })
+
   addRuntimeHealthCommands(program, runHealth)
 
   program
@@ -1677,12 +1741,252 @@ If apiId/apiHash are missing, create a Telegram API app at:
 
   addProvisionCommands(program)
   addCustodyWorkerCommands(program)
+  registerEventsCommand(program)
+  registerHoldsCommand(program)
+  installBareHelp(program)
   return program
 }
 
-createProgram()
-  .parseAsync()
-  .catch((error) => {
-    console.error(error)
-    process.exit(1)
+/** Space-joined subcommand path below the root, e.g. `ops sai-find`. */
+function commandPath(command: Command): string {
+  const names: string[] = []
+  for (let c: Command | null = command; c?.parent; c = c.parent) {
+    names.unshift(c.name())
+  }
+  return names.join(" ")
+}
+
+/** Telemetry subsystem for a subcommand path. */
+function subsystemFor(path: string): TelemetrySubsystem {
+  if (path === "worker") return "worker"
+  if (path === "health") return "health"
+  return "cli"
+}
+
+/** Commands that only read telemetry; they do not record runs of their own. */
+function skipsTelemetry(path: string): boolean {
+  return path === "" || path === "events" || path.startsWith("events ")
+}
+
+/** Exit code for a run stopped by SIGINT/SIGTERM (128 + SIGINT). */
+const SIGNAL_EXIT_CODE = 130
+
+/**
+ * Ends the run as aborted on the first SIGINT/SIGTERM, then exits. The
+ * `worker` command installs its own handlers for a graceful stop.
+ */
+function endRunOnSignal(path: string): void {
+  if (path === "worker") return
+  const onSignal = () => {
+    process.removeListener("SIGINT", onSignal)
+    process.removeListener("SIGTERM", onSignal)
+    activeTelemetryRun()?.end({
+      exitCode: SIGNAL_EXIT_CODE,
+      outcome: "aborted",
+    })
+    process.exit(SIGNAL_EXIT_CODE)
+  }
+  process.once("SIGINT", onSignal)
+  process.once("SIGTERM", onSignal)
+}
+
+function startCliTelemetryRun(actionCommand: Command): void {
+  const path = commandPath(actionCommand)
+  if (helpOnlyCommands.has(actionCommand)) return
+  if (skipsTelemetry(path) || activeTelemetryRun()) return
+  startTelemetryRun({
+    subsystem: subsystemFor(path),
+    command: path,
+    argv: process.argv.slice(2),
+    version: packageJson.version,
+    ...(path === "ops sai-bootstrap"
+      ? { floodMaxWaitMs: BOOTSTRAP_FLOOD_MAX_WAIT_MS }
+      : {}),
+  })
+  endRunOnSignal(path)
+}
+
+// ---------------------------------------------------------------------------
+// Bare commands print help
+
+/** Groups whose only action prints help; they record no telemetry run. */
+const helpOnlyCommands = new WeakSet<Command>()
+
+/** Commander keeps the action handler private; read it without casting. */
+function hasAction(command: Command): boolean {
+  return (command as unknown as { _actionHandler?: unknown })._actionHandler
+    ? true
+    : false
+}
+
+/**
+ * Makes every command group without an action print its help when called
+ * bare, with exit code 0 (commander's default is help on stderr, exit 1).
+ */
+export function installBareHelp(command: Command): void {
+  for (const sub of command.commands) installBareHelp(sub)
+  if (command.commands.length === 0 || hasAction(command)) return
+  helpOnlyCommands.add(command)
+  command.action(() => {
+    command.help({ error: false })
   })
+}
+
+/** True when the command has a required argument or mandatory option. */
+export function hasRequiredInput(command: Command): boolean {
+  return (
+    command.registeredArguments.some((arg) => arg.required) ||
+    command.options.some((option) => option.mandatory)
+  )
+}
+
+/**
+ * The leaf command `args` name when it has required input and `args` hold
+ * nothing past its name, e.g. `tg-sai audit`. Such a call prints that
+ * command's help instead of a missing-option error. Any extra token, even a
+ * wrong one, returns null so commander reports the usual error.
+ */
+export function bareHelpTarget(
+  program: Command,
+  args: readonly string[],
+): Command | null {
+  let command = program
+  for (const arg of args) {
+    const next = command.commands.find(
+      (sub) => sub.name() === arg || sub.aliases().includes(arg),
+    )
+    if (!next) return null
+    command = next
+  }
+  if (command === program || command.commands.length > 0) return null
+  return hasRequiredInput(command) ? command : null
+}
+
+// ---------------------------------------------------------------------------
+// Exit codes
+
+/** `EX_TEMPFAIL`: retry later. Used while Telegram limits the account. */
+export const HOLD_EXIT_CODE = 75
+const HOLD_STATE_UNAVAILABLE = "TG_SAI_HOLD_STATE_UNAVAILABLE"
+
+export interface HoldExit {
+  exitCode: typeof HOLD_EXIT_CODE
+  /** One line for stderr. */
+  message: string
+}
+
+interface HoldLike {
+  code?: unknown
+  text?: unknown
+  message?: unknown
+  untilMs?: unknown
+  grp?: unknown
+  cause?: unknown
+}
+
+function holdText(error: HoldLike): string | null {
+  if (typeof error.text === "string") return error.text
+  if (typeof error.message === "string") return error.message
+  return null
+}
+
+function holdLike(value: unknown): HoldLike | null {
+  return typeof value === "object" && value !== null
+    ? (value as HoldLike)
+    : null
+}
+
+/** UTC timestamp without milliseconds, e.g. `2026-11-06T16:20:05Z`. */
+function utcSeconds(ms: number): string {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
+}
+
+/** `4h 16m`, `12m 5s`, or `40s`. */
+export function shortDuration(totalS: number): string {
+  const s = Math.max(0, Math.round(totalS))
+  const h = Math.floor(s / 3600)
+  const m = Math.floor((s % 3600) / 60)
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m ${s % 60}s`
+  return `${s}s`
+}
+
+/**
+ * Maps a saved flood hold (`HoldError`, `TG_SAI_HOLD_<s>`, code 420), an
+ * unreadable `state.db` (`TG_SAI_HOLD_STATE_UNAVAILABLE`), or an unverified
+ * session account (`TG_SAI_HOLD_ACCOUNT_UNKNOWN`) to exit 75 with a
+ * one-line message. Looks through `error.cause` chains. Returns null for
+ * every other error.
+ */
+export function holdExitFor(
+  error: unknown,
+  nowMs: number = Date.now(),
+): HoldExit | null {
+  let current = holdLike(error)
+  for (let depth = 0; current && depth < 8; depth += 1) {
+    const text = holdText(current)
+    if (text === HOLD_STATE_UNAVAILABLE) {
+      return {
+        exitCode: HOLD_EXIT_CODE,
+        message:
+          "tg-sai: cannot read saved Telegram limits in " +
+          `${stateDbPath()}; invite/create calls stay blocked and nothing ` +
+          "was sent. Fix the file, then retry.",
+      }
+    }
+    if (text === HOLD_ACCOUNT_UNKNOWN) {
+      return {
+        exitCode: HOLD_EXIT_CODE,
+        message:
+          "tg-sai: could not confirm which Telegram account this session " +
+          "acts as, so its saved limits cannot be checked; invite/create " +
+          "calls stay blocked and nothing was sent. Retry once getMe works.",
+      }
+    }
+    const seconds = holdErrorSeconds(text)
+    const codeOk = current.code === undefined || current.code === 420
+    if (seconds !== null && codeOk) {
+      const untilMs =
+        typeof current.untilMs === "number" && Number.isFinite(current.untilMs)
+          ? current.untilMs
+          : nowMs + seconds * 1000
+      const grp = typeof current.grp === "string" ? current.grp : "this"
+      const waitS = Math.max(0, Math.ceil((untilMs - nowMs) / 1000))
+      return {
+        exitCode: HOLD_EXIT_CODE,
+        message:
+          `tg-sai: Telegram is limiting ${grp} calls for this account; ` +
+          `nothing was sent. Resume after ${utcSeconds(untilMs)} ` +
+          `(in ${shortDuration(waitS)}).`,
+      }
+    }
+    current = holdLike(current.cause)
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+
+async function main(): Promise<void> {
+  const program = createProgram()
+  const args = process.argv.slice(2)
+  const helpTarget = bareHelpTarget(program, args)
+  if (helpTarget) {
+    helpTarget.outputHelp()
+    return
+  }
+  try {
+    await program.parseAsync()
+  } catch (error) {
+    const hold = holdExitFor(error)
+    const exitCode = hold?.exitCode ?? 1
+    activeTelemetryRun()?.end({ exitCode, error })
+    if (hold) console.error(hold.message)
+    else console.error(error)
+    process.exit(exitCode)
+  }
+  activeTelemetryRun()?.end({ exitCode: Number(process.exitCode ?? 0) })
+}
+
+if (import.meta.main) await main()