@miphamai/cli 0.81.5 → 0.81.7

package/src/daemon/launch.ts

@@ -0,0 +1,287 @@
+/**
+ * Launching the daemon as a detached process.
+ *
+ * The daemon must be started by *the same program* the user invoked:
+ *  - source mode (`bun run bin/mipham.ts`): argv[0] is bun, argv[1] the script
+ *  - compiled binary (`dist/mipham`): argv[0] is the binary itself
+ *
+ * The previous implementation hardcoded `spawn('bun', ['run', <path>])`, which
+ * broke both ways in a compiled binary: `bun` is not on PATH (that is the whole
+ * point of shipping a binary), and `import.meta.url` resolves to a `$bunfs`
+ * path that no freshly spawned interpreter can read.
+ */
+
+import { spawn, type SpawnOptions } from 'node:child_process'
+import { closeSync, mkdirSync, openSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+/** argv sentinel that re-enters this program as a daemon. Not user-facing. */
+export const DAEMON_ENTRY = '__daemon'
+
+const DEFAULT_LOG_FILE = join(homedir(), '.mipham', 'daemon.log')
+
+/**
+ * argv prefix that re-runs *this* program.
+ *
+ * Is an interpreter sitting in front of this program? That — and only that —
+ * is what decides whether the re-exec has to re-pass a script path. Measured on
+ * bun 1.3.14; these are the shapes bun actually produces:
+ *
+ *   bun run bin/mipham.ts daemon start
+ *     argv     = ["<…>/bun.exe", "<abs>/bin/mipham.ts", "daemon", "start"]
+ *     execPath = "<…>/bun.exe"           ← argv[0] IS the interpreter
+ *   dist/mipham daemon start
+ *     argv     = ["bun", "/$bunfs/root/mipham", "daemon", "start"]
+ *     execPath = "<…>/dist/mipham"       ← argv[0] is not; the entry lives inside
+ *
+ * Both shapes put exactly TWO entries in front of the user's own arguments,
+ * which is why the rest of bin/mipham.ts parses with `process.argv.slice(2)`
+ * in either mode. Only the re-exec prefix has to tell the two apart — and the
+ * compiled entry is a `$bunfs` path that exists only inside the binary, so no
+ * re-exec can ever name it: the artifact re-runs `execPath` with no script.
+ *
+ * (Until this was measured the discriminator was "does argv[1] end in .ts/.js",
+ * so it read the compiled `$bunfs` entry as the first *user argument* — and the
+ * `__daemon` branch became unreachable in the artifact while source mode, where
+ * the heuristic happens to be right, stayed green.)
+ */
+export function selfArgvPrefix(
+  argv0: string | undefined,
+  argv1: string | undefined,
+  execPath: string,
+): string[] {
+  return argv0 === execPath && typeof argv1 === 'string' ? [execPath, resolve(argv1)] : [execPath]
+}
+
+/**
+ * The user-facing arguments, with the interpreter/script prefix stripped.
+ *
+ * Always two, in both modes — same model as the `process.argv.slice(2)` used
+ * throughout bin/mipham.ts. See `selfArgvPrefix` for the measured shapes.
+ */
+export function userArgs(argv: readonly string[]): string[] {
+  return argv.slice(2)
+}
+
+export interface SpawnPlan {
+  command: string
+  args: string[]
+  options: SpawnOptions
+  logPath: string
+}
+
+/**
+ * Pure: computes the spawn call without performing it, so the shape (argv[0],
+ * missing cwd, detached) is assertable in a unit test that runs under the
+ * source tree — where the original bug does *not* reproduce.
+ *
+ * `argv0`/`argv1` default to the real `process.argv[0]`/`process.argv[1]` and
+ * `execPath` to the real `process.execPath`. The branch is
+ * `argv0 === execPath && typeof argv1 === 'string'` — *both* conjuncts, and the
+ * second is reachable without passing `argv0`: `planDaemonSpawn({ argv1:
+ * undefined })` keeps the default equality (true whenever the calling process is
+ * in source mode) and fails the `typeof`, so it gets the *compiled* shape.
+ * Both satisfied ⇒ the *source* shape (an interpreter in front of a script path,
+ * so the script element is re-sent); otherwise ⇒ the bare `[execPath]` of the
+ * *compiled* shape. To force the compiled shape, pass `argv0` as well.
+ */
+export function planDaemonSpawn(
+  opts: {
+    argv0?: string | undefined
+    argv1?: string | undefined
+    execPath?: string
+    extraArgs?: string[]
+    logPath?: string
+  } = {},
+): SpawnPlan {
+  const argv0 = 'argv0' in opts ? opts.argv0 : process.argv[0]
+  const argv1 = 'argv1' in opts ? opts.argv1 : process.argv[1]
+  const execPath = opts.execPath ?? process.execPath
+  return {
+    command: execPath,
+    // `selfArgvPrefix` returns the child's *argv*, so it starts with argv[0] —
+    // but spawn() sets argv[0] from `command` itself, so that element has to be
+    // dropped here. Keeping it puts `execPath` at argv[1], where the runtime
+    // reads it as *the script to execute*: node/bun then parse the interpreter's
+    // own binary as source and die with `error: Unexpected <binary>` before the
+    // script ever runs. Verified identical on node v24 and bun 1.3.14.
+    args: [
+      ...selfArgvPrefix(argv0, argv1, execPath).slice(1),
+      DAEMON_ENTRY,
+      ...(opts.extraArgs ?? []),
+    ],
+    // No `cwd`: the child must inherit this process's working directory.
+    // `daemonRoot = process.cwd()` is the daemon's path allowlist boundary.
+    options: { detached: true, env: { ...process.env } },
+    logPath: opts.logPath ?? DEFAULT_LOG_FILE,
+  }
+}
+
+export interface DaemonLaunch {
+  ok: boolean
+  pid?: number
+  port?: number
+  reason?: string
+}
+
+interface DaemonStatusLike {
+  pid: number
+  port: number
+}
+
+/** Injection seam: real implementations by default, fakes in unit tests. */
+export interface LaunchDeps {
+  spawnFn?: typeof spawn
+  getStatus?: () => DaemonStatusLike | null
+  sleep?: (ms: number) => Promise<void>
+}
+
+const READY_TIMEOUT_MS = 10_000
+const POLL_INTERVAL_MS = 100
+/** How long `restart` waits for the *old* daemon to go before refusing. */
+const OLD_DAEMON_EXIT_TIMEOUT_MS = 10_000
+
+async function defaultGetStatus(): Promise<DaemonStatusLike | null> {
+  const { getDaemonStatus } = await import('./index')
+  return getDaemonStatus()
+}
+
+function tailLog(logPath: string, maxBytes = 800): string {
+  try {
+    const size = statSync(logPath).size
+    const start = Math.max(0, size - maxBytes)
+    return readFileSync(logPath, 'utf-8').slice(start).trim()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Start the daemon detached and *wait until it is actually up*.
+ *
+ * Never reports success on an unknown child: the previous implementation
+ * printed "Daemon started (PID unknown …)" and exited 0 whenever the pid file
+ * was missing, which turned every launch failure into a silent one.
+ */
+export async function startDetachedDaemon(
+  opts: { timeoutMs?: number; pollMs?: number; deps?: LaunchDeps } = {},
+): Promise<DaemonLaunch> {
+  const deps = opts.deps ?? {}
+  const spawnFn = deps.spawnFn ?? spawn
+  const getStatus = deps.getStatus ?? defaultGetStatus
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)))
+
+  const already = await getStatus()
+  if (already) return { ok: true, pid: already.pid, port: already.port }
+
+  const plan = planDaemonSpawn()
+  mkdirSync(dirname(plan.logPath), { recursive: true, mode: 0o700 })
+
+  let spawnError: Error | null = null
+  let exitCode: number | null = null
+  // The child inherits this fd; closing ours does not close theirs.
+  const logFd = openSync(plan.logPath, 'a', 0o600)
+  let child: ReturnType<typeof spawn>
+  try {
+    child = spawnFn(plan.command, plan.args, {
+      ...plan.options,
+      stdio: ['ignore', 'ignore', logFd],
+    })
+  } finally {
+    closeSync(logFd)
+  }
+  child.on('error', (err: Error) => {
+    spawnError = err
+  })
+  child.on('exit', (code: number | null) => {
+    exitCode = code ?? -1
+  })
+  child.unref()
+
+  const deadline = Date.now() + (opts.timeoutMs ?? READY_TIMEOUT_MS)
+  const pollMs = opts.pollMs ?? POLL_INTERVAL_MS
+  while (Date.now() < deadline) {
+    await sleep(pollMs)
+    if (spawnError) {
+      const err: Error = spawnError
+      return { ok: false, reason: `daemon failed to spawn: ${err.message}` }
+    }
+    const status = await getStatus()
+    if (status) return { ok: true, pid: status.pid, port: status.port }
+    if (exitCode !== null) {
+      const tail = tailLog(plan.logPath)
+      return {
+        ok: false,
+        reason: `daemon exited with code ${exitCode}${tail ? `:\n${tail}` : ''}`,
+      }
+    }
+  }
+  return {
+    ok: false,
+    reason: `daemon did not become ready within ${opts.timeoutMs ?? READY_TIMEOUT_MS}ms (log: ${plan.logPath})`,
+  }
+}
+
+/**
+ * Wait until the daemon we just signalled is *gone*.
+ *
+ * `restart` used to SIGTERM and then sleep a fixed 500 ms. That is a guess, and
+ * the guess is load-bearing: `startDetachedDaemon()` opens with a probe of
+ * `getStatus()` and returns whatever pid/port it finds there. A pid file the old
+ * daemon has not unlinked yet therefore reads as "already running" — `restart`
+ * then reports `Daemon restarted (PID: <old>)` and exits 0 having started
+ * nothing, and the old daemon finishes exiting afterwards, leaving none. That is
+ * the same "reports success with no daemon behind it" failure this module exists
+ * to remove, reintroduced on a new write point.
+ *
+ * Returns true once `getStatus()` goes null, false if it never does before the
+ * deadline. `false` is a refusal, not a warning: the caller must not start.
+ */
+export async function waitForDaemonExit(
+  opts: { timeoutMs?: number; pollMs?: number; deps?: LaunchDeps } = {},
+): Promise<boolean> {
+  const deps = opts.deps ?? {}
+  const getStatus = deps.getStatus ?? defaultGetStatus
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)))
+  const deadline = Date.now() + (opts.timeoutMs ?? OLD_DAEMON_EXIT_TIMEOUT_MS)
+  const pollMs = opts.pollMs ?? POLL_INTERVAL_MS
+
+  for (;;) {
+    const status = await getStatus()
+    if (!status) return true
+    if (Date.now() >= deadline) return false
+    await sleep(pollMs)
+  }
+}
+
+/**
+ * The daemon process body, shared by the `__daemon` branch of the compiled
+ * binary and by `bin/daemon.ts` (source mode). One implementation, two entry
+ * points — a second copy is how "two render paths, only one wired" starts.
+ *
+ * The two callers pass *different* argv slices and that is deliberate: the
+ * compiled binary is `[binary, '__daemon', ...]` while the source entry is
+ * `[bun, 'bin/daemon.ts', ...]`, so the `__daemon` branch strips the sentinel
+ * (and `bin/daemon.ts` relies on the default) rather than either of them
+ * handing over a raw `process.argv` tail.
+ */
+export async function runDaemonProcess(argv: string[] = process.argv.slice(2)): Promise<void> {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--port' && argv[i + 1]) process.env.MIPHAM_PORT = argv[i + 1]
+    if (argv[i] === '--bind' && argv[i + 1]) process.env.MIPHAM_BIND = argv[i + 1]
+  }
+
+  const { startDaemon, stopDaemon } = await import('./index')
+  const { port } = await startDaemon()
+
+  console.log(`Daemon running on http://127.0.0.1:${port}`)
+  console.log(`PID: ${process.pid}`)
+
+  const shutdown = async (): Promise<void> => {
+    await stopDaemon(true)
+    process.exit(0)
+  }
+  process.on('SIGTERM', () => void shutdown())
+  process.on('SIGINT', () => void shutdown())
+}

package/src/daemon/remote-engine.ts

@@ -227,6 +227,9 @@ export class RemoteEngine {
   /** No-op: reasoning effort is managed by the daemon session. */
   setEffort(_level: string): void {}
 
+  /** No-op: file-read tracking lives with the daemon's own engine. */
+  resetFileTracking(): void {}
+
   /** Remote mode has no local agent registry. */
   getAgentRegistry(): undefined {
     return undefined
@@ -384,6 +387,8 @@ export class RemoteEngine {
           type: 'tool_result',
           tool_use_id: msg.toolId,
           content: msg.content,
+          // 回程也要带上，否则字段出了 WS 就回不来 —— 接远端 daemon 的 CLI 依旧失明。
+          isError: msg.isError,
         }
       }
 

package/src/daemon/server.ts

@@ -38,6 +38,7 @@ import { createDingtalkAdapter } from './dingtalk/adapter.js'
 import { createDingtalkApi } from './dingtalk/api.js'
 import type { DingtalkConfig } from './dingtalk/types.js'
 import { startHeartbeat } from './heartbeat'
+import { wireDaemonEngine } from './engine-capabilities'
 
 interface ServerConfig {
   db: DaemonDatabase
@@ -236,6 +237,14 @@ export function createServer(config: ServerConfig): Server<WsData> {
     )
     const engine = new QueryEngine(sharedRegistry, context, sharedTools, permission)
     engine.setSessionId(sessionId)
+    // Same engine capabilities as the interactive CLI — see engine-capabilities.ts.
+    // Must stay immediately after setSessionId and before the cache insert, so no
+    // path can obtain a half-wired engine.
+    wireDaemonEngine(engine, {
+      cwd,
+      registry: sharedRegistry,
+      skillsPaths: daemonConfig.skills?.paths,
+    })
     engineCache.set(sessionId, engine)
     return engine
   }

package/src/daemon/session-worker.ts

@@ -152,10 +152,12 @@ export class SessionWorker {
           if (chunk.outputTokens) totalOutputTokens += chunk.outputTokens
         }
 
-        // Stop signal from engine — includes 'stop' and 'error' types
-        if (chunk.type === 'stop') {
-          break
-        }
+        // Deliberately NO break on 'stop' — the chunk type is overloaded here.
+        // Providers emit a provider-level 'stop' unconditionally at the end of
+        // EVERY LLM stream, including tool-call turns; the engine still has to
+        // execute those tools and run the continuation turns after it. The
+        // engine's own terminal 'stop' is always followed by `return`, so
+        // letting the generator run out is the only correct termination.
       }
     } catch (err) {
       stopReason = 'error'
@@ -326,6 +328,7 @@ export class SessionWorker {
           sessionId: this.session.id,
           toolId: chunk.tool_use_id ?? 'unknown',
           content: chunk.content ?? '',
+          isError: chunk.isError ?? false,
         }
         return msg
       }

package/src/i18n-core/locales/en-US.json

@@ -286,7 +286,7 @@
       "list_fetching": "Fetching current task list...",
       "create_title": "── Create Task ──",
       "default_title": "── Task Management ──",
-      "default_body": "The AI manages task state via TaskCreate, TaskList, TaskUpdate, and TaskGet tools.\nTasks appear in the /tasks view and persist across the session."
+      "default_body": "The AI manages task state via the Task tool, using the \"create\", \"list\", \"update\", and \"get\" actions.\nTasks appear in the /tasks view and persist across the session."
     },
     "copy": {
       "confirmed": "✓ Copied {count} assistant response(s) to clipboard.",
@@ -304,8 +304,8 @@
     },
     "task_list": {
       "title": "── Background Tasks ──",
-      "detected": "{count} task operations detected in this session.\n\nUse Task tool (TaskCreate / TaskUpdate / TaskList) to manage structured task tracking.",
-      "no_tasks": "No tasks tracked yet. Use TaskCreate, TaskUpdate, and TaskList tools to manage structured tasks.",
+      "detected": "{count} task operations detected in this session.\n\nUse the Task tool (action \"create\" / \"update\" / \"list\") to manage structured task tracking.",
+      "no_tasks": "No tasks tracked yet. Use the Task tool with action \"create\", \"update\", or \"list\" to manage structured tasks.",
       "reference": "Quick reference:",
       "legacy_hint": "Type /todos for the legacy task interface."
     },
@@ -985,10 +985,9 @@
     "mcp": { "name": "MCP", "description": "Manage MCP server connections" }
   },
   "errors": {
-    "tool_not_allowed": "Tool \"{name}\" requires user approval (permission: ask). The tool was not executed. Press Shift+Tab to switch permission mode, or run /permissions.",
-    "tool_denied_deny_rule": "Tool \"{name}\" blocked by a deny rule (\"{pattern}\"). Deny rules override permission mode — try a different approach.",
-    "tool_denied_ask_rule": "Tool \"{name}\" requires approval (ask rule: \"{pattern}\"). Approve when prompted, or adjust the rule via /permissions.",
-    "tool_denied_mode": "Tool \"{name}\" requires approval under \"{mode}\" mode. Press Shift+Tab to switch permission mode, or run /permissions.",
+    "tool_denied_deny_rule": "Tool \"{name}\" blocked by a deny rule (\"{pattern}\"). Deny rules override permission mode — try a different approach, or drop the rule with: /permissions remove \"{pattern}\"",
+    "tool_denied_ask_rule": "Tool \"{name}\" requires approval (ask rule: \"{pattern}\"). Approve when prompted, or stop being asked with: /permissions allow \"{pattern}\"",
+    "tool_denied_mode": "Tool \"{name}\" requires approval under \"{mode}\" mode. Press Shift+Tab to switch permission mode, or stop being asked with: /permissions allow \"{name}\" (or a narrower \"{name}(arg)\")",
     "tool_blocked": "Tool \"{name}\" blocked by hook",
     "user_input_blocked": "User input blocked by hook.",
     "dlp_blocked": "Request blocked by DLP policy.",

package/src/i18n-core/locales/zh-CN.json

@@ -286,7 +286,7 @@
       "list_fetching": "正在获取当前任务列表...",
       "create_title": "── 创建任务 ──",
       "default_title": "── 任务管理 ──",
-      "default_body": "AI 通过 TaskCreate、TaskList、TaskUpdate 和 TaskGet 工具管理任务状态。\n任务显示在 /tasks 视图中，并在会话期间保持。"
+      "default_body": "AI 通过 Task 工具的 \"create\"、\"list\"、\"update\" 和 \"get\" action 管理任务状态。\n任务显示在 /tasks 视图中，并在会话期间保持。"
     },
     "copy": {
       "confirmed": "✓ 已复制 {count} 条助手回复到剪贴板。",
@@ -304,8 +304,8 @@
     },
     "task_list": {
       "title": "── 后台任务 ──",
-      "detected": "在此会话中检测到 {count} 次任务操作。\n\n使用 Task 工具（TaskCreate / TaskUpdate / TaskList）管理结构化任务跟踪。",
-      "no_tasks": "尚未跟踪任何任务。使用 TaskCreate、TaskUpdate 和 TaskList 工具管理结构化任务。",
+      "detected": "在此会话中检测到 {count} 次任务操作。\n\n使用 Task 工具（action \"create\" / \"update\" / \"list\"）管理结构化任务跟踪。",
+      "no_tasks": "尚未跟踪任何任务。使用 Task 工具的 action \"create\"、\"update\" 或 \"list\" 管理结构化任务。",
       "reference": "快速参考:",
       "legacy_hint": "输入 /todos 使用旧版任务界面。"
     },
@@ -985,10 +985,9 @@
     "mcp": { "name": "MCP", "description": "管理 MCP 服务器连接" }
   },
   "errors": {
-    "tool_not_allowed": "工具 \"{name}\" 需要用户批准（权限：ask），未执行。按 Shift+Tab 切换权限模式，或运行 /permissions。",
-    "tool_denied_deny_rule": "工具 \"{name}\" 被拒绝规则（\"{pattern}\"）阻止。拒绝规则优先于权限模式 — 请改用其他方式。",
-    "tool_denied_ask_rule": "工具 \"{name}\" 需要批准（ask 规则：\"{pattern}\"）。请在提示时批准，或通过 /permissions 调整规则。",
-    "tool_denied_mode": "工具 \"{name}\" 在 \"{mode}\" 模式下需要批准。按 Shift+Tab 切换权限模式，或运行 /permissions。",
+    "tool_denied_deny_rule": "工具 \"{name}\" 被拒绝规则（\"{pattern}\"）阻止。拒绝规则优先于权限模式 — 请改用其他方式，或移除该规则：/permissions remove \"{pattern}\"",
+    "tool_denied_ask_rule": "工具 \"{name}\" 需要批准（ask 规则：\"{pattern}\"）。请在提示时批准，或不再询问：/permissions allow \"{pattern}\"",
+    "tool_denied_mode": "工具 \"{name}\" 在 \"{mode}\" 模式下需要批准。按 Shift+Tab 切换权限模式，或不再询问：/permissions allow \"{name}\"（更窄的 \"{name}(arg)\" 亦可）",
     "tool_blocked": "工具 \"{name}\" 被钩子拦截",
     "user_input_blocked": "用户输入被钩子拦截。",
     "dlp_blocked": "请求被 DLP 策略阻止。",

package/src/index.tsx

@@ -49,6 +49,9 @@ import { HookEngine } from './core/hooks'
 import { loadHookConfigs } from './core/hooks-config'
 import { ArtifactServer } from './artifacts/server'
 import { getMetrics } from './core/metrics'
+import { initTelemetry, enableTelemetryNow } from './telemetry/index'
+import { wasPrompted, markPrompted, isInteractive, setTelemetryEnabled } from './telemetry/consent'
+import { officialEndpointHost } from './telemetry/endpoint'
 import { getWorkspaceTrust } from './core/workspace-trust'
 import { ARTIFACTS_DIR, ARTIFACT_PORT, MIPHAM_DIR } from './shared/constants'
 import { AgentViewManager } from './agent-view/agent-view-manager'
@@ -135,6 +138,72 @@ async function checkWorkspaceTrust(): Promise<void> {
   }
 }
 
+/**
+ * One-time telemetry opt-in.
+ *
+ * Asked once per machine and never again — including when the answer is "no",
+ * which is why the marker (`telemetry.promptedAt`) is separate from the consent
+ * itself: otherwise "asked and declined" and "never asked" would look identical
+ * and the question would reappear on every launch.
+ *
+ * Two ways this deliberately does *not* ask:
+ *   - when a marker already exists;
+ *   - when there is no TTY to answer on (piped stdin, daemon, CI) — a prompt
+ *     there would block forever on input that cannot arrive.
+ *
+ * In the second case the marker is left **unwritten**: burning it on a headless
+ * run would mean a user whose first invocation was `mipham -p "…"` is never
+ * offered the choice at all. Staying off by default costs nothing, and a later
+ * interactive run still asks.
+ */
+async function promptForTelemetryConsent(): Promise<void> {
+  if (wasPrompted()) return
+  if (!isInteractive()) return
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr, // stderr, so it cannot corrupt stdout rendering
+  })
+
+  try {
+    process.stderr.write('\n')
+    process.stderr.write('  Telemetry — optional, and off unless you say yes.\n')
+    process.stderr.write('\n')
+    process.stderr.write('  If enabled, Mipham Code sends counts of which commands and\n')
+    process.stderr.write('  tools you use, plus the app version, runtime and platform.\n')
+    // The destination, adjacent to what travels — consent is to an address,
+    // not to a category of data. Derived from the endpoint constant so a
+    // future move cannot leave this line naming the previous host.
+    process.stderr.write(`  They are sent to ${officialEndpointHost()}.\n`)
+    process.stderr.write('  It does not send your code, prompts, file contents, file\n')
+    process.stderr.write('  paths, project names or API keys.\n')
+    process.stderr.write('\n')
+    process.stderr.write('  Change it any time with /telemetry on or /telemetry off.\n')
+    process.stderr.write('\n')
+
+    const answer = await new Promise<string>((resolve) => {
+      rl.question('  Enable anonymous usage statistics? [y/N]: ', (a) =>
+        resolve(a.trim().toLowerCase()),
+      )
+    })
+
+    const accepted = answer === 'y' || answer === 'yes'
+    setTelemetryEnabled(accepted)
+    markPrompted()
+    if (accepted) {
+      // Take effect in this session, not the next one.
+      enableTelemetryNow()
+      process.stderr.write('  ✓ Telemetry enabled. Thank you.\n\n')
+    } else {
+      process.stderr.write('  ✓ Telemetry stays off.\n\n')
+    }
+  } catch {
+    // Never let a question about diagnostics stop the CLI from starting.
+  } finally {
+    rl.close()
+  }
+}
+
 // ── SetupGate: first-run wizard → App bridge ──
 
 interface SetupGateProps {
@@ -239,6 +308,11 @@ export async function runApp(options: RunOptions): Promise<void> {
   getMetrics().cliInvocations.inc()
   getMetrics().activeSessions.inc()
 
+  // Telemetry: resolve consent, install crash handlers, register the exit
+  // flush, and drain anything a previous session left queued. Does nothing
+  // observable when telemetry is off (the shipped default).
+  initTelemetry()
+
   // ── Workspace Trust Check ──
   await checkWorkspaceTrust()
 
@@ -717,6 +791,11 @@ export async function runApp(options: RunOptions): Promise<void> {
   const hasProjectConfig = existsSync(join(process.cwd(), '.mipham', 'config.yml'))
   const needsSetup = !hasUserConfig && !hasProjectConfig
 
+  // Only ask when the first-run wizard is *not* about to take over the
+  // terminal — two prompts queued at once is a worse first impression than a
+  // question asked on the second launch.
+  if (!needsSetup) await promptForTelemetryConsent()
+
   const { waitUntilExit } = render(
     React.createElement(I18nProvider, {
       locale,