@0dai-dev/cli 4.3.4 → 4.3.5

package/README.md

@@ -1,6 +1,6 @@
 # 0dai
 
-One config layer for <!-- canonical-count:agent_clis_total -->6<!-- /canonical-count --> AI agent CLIs — Claude Code, Codex, OpenCode, Gemini, Aider, Qoder.
+One config layer for <!-- canonical-count:agent_clis_total -->7<!-- /canonical-count --> AI agent CLIs — Claude Code, Codex, OpenCode, Gemini, Aider, Qoder, Cursor.
 
 ## Install
 
@@ -8,22 +8,85 @@ One config layer for <!-- canonical-count:agent_clis_total -->6<!-- /canonical-c
 npm install -g @0dai-dev/cli
 ```
 
-## Usage
+## Five commands that matter
 
 ```bash
 cd your-project
-0dai init       # guides OAuth/device auth + activation, then generates ai/ layer
-0dai init --auth-code <browser-code> --code <TEAM-CODE>
-0dai auth login # sign in separately when needed
-0dai activate code <TEAM-CODE>
-0dai sync       # update after changes
-0dai detect     # show detected stack
-0dai doctor     # check health
-0dai status     # maturity, swarm tasks, session
-0dai feedback retry # retry queued feedback after an API failure
-0dai persona-simulate "topic"  # run synthetic focus-group simulation
+0dai init      # create ai/ layer, auth, and MCP bootstrap
+0dai status    # maturity, swarm tasks, and session state
+0dai sync      # refresh ai/ after repo or server changes
+0dai run "…"   # split a backlog item into agent tasks
+0dai doctor    # health check for credentials, drift, and env
 ```
 
+## All commands
+
+Start (first 5 minutes):
+
+```bash
+0dai init                           # create ai/ layer + MCP [--local] [--dry-run] [--minimal]
+0dai init --auth-code <code> --code <TEAM-CODE>   # non-interactive auth + activation
+0dai doctor                         # check health, credentials, and drift [--drift]
+0dai status                         # maturity, swarm, and session state [--json]
+0dai quickstart                     # auth, init, doctor, and status in one pass
+0dai detect                         # show detected stack
+0dai auth login                     # OAuth/device flow [--device] [--no-browser] [--code CODE] [--mcp]
+0dai auth mcp                       # store MCP token from current auth or device code
+0dai auth status                    # account and usage
+0dai activate free                  # claim free activation license
+```
+
+Daily (regular work):
+
+```bash
+0dai sync                           # update ai/ after repo or server changes [--dry-run] [--yes] [--quiet] [--force]
+0dai run <goal>                     # split a backlog item into agent tasks [--dry-run] [--dry-cost] [--agent claude|codex|gemini]
+0dai swarm status                   # show queued, active, and done tasks
+0dai swarm add                      # queue one task [--task '...' --to agent]
+0dai swarm-run                      # add, dispatch, and wait for one swarm task as JSON
+0dai harvest                        # convert experience events into candidate lessons
+0dai watch                          # live task monitor [--interval N]
+0dai reflect                        # session reflection: delivered, delegation, blockers
+0dai standup                        # morning voice briefing about overnight agent work
+0dai feedback push                  # send feedback to 0dai
+0dai feedback retry                 # retry queued feedback after a failed push
+0dai persona-simulate "topic"       # focus-group report and optional issue drafts
+```
+
+Pro / advanced:
+
+```bash
+0dai init-existing                  # existing-repo setup alias for init
+0dai project bind                   # bind repository to your 0dai account [--json]
+0dai project status                 # local project binding and health [--json]
+0dai graph push                     # upload local graph (Pro: edges, Free: nodes)
+0dai graph pull                     # download server graph and merge locally
+0dai graph status                   # local graph stats and sync state
+0dai ci                             # portable CI pipelines and AI-MQ [list|plan|mq-status]
+0dai heatmap                        # repo treemap: LOC × agent-edit intensity
+0dai session save                   # save session for roaming
+0dai provider                       # local provider profiles and direct invoke
+0dai models                         # model ratings (--fast/--balanced/--deep/--available)
+0dai quota                          # agent subscription usage [--refresh] [--json]
+0dai usage                          # local token, task, and USD ledger [status|daily|monthly]
+0dai workspace                      # tmux workspace sessions (init|up|status)
+0dai runner                         # runner/host architecture and queues [--json]
+0dai report                         # privacy-safe project reports (preview|push|status)
+0dai compliance                     # SOC2/ISO evidence and ADR audit-trail export
+0dai experience                     # structured experience events (list|stats|sync|warnings|dismiss)
+0dai receipt                        # session receipt PNG [--last|--active|--session ID]
+0dai boneyard                       # weekly digest of worst agent moves [--week YYYY-WW|current]
+0dai gh branch-protection           # GitHub branch protection [print|apply|install]
+0dai import claude-code-agents      # import .claude/agents/*.md as personas [--dry-run]
+0dai auth logout                    # remove credentials
+0dai activate code <TEAM-CODE>      # redeem Pro/Team activation code
+0dai activate status                # activation and bound-project status
+0dai redeem <CODE>                  # redeem a plan upgrade code
+0dai upgrade                        # open pricing page (browser or printed URL)
+```
+
+Global flags: `--target PATH`, `--version`, `--help`, `--json`, `--quiet`. See `0dai --help` for the full surface.
+
 ## What it does
 
 `0dai init` and `0dai sync` are activation-first. `init` can complete auth and plan activation in one run: browser/OAuth exchange code via `--auth-code`, Team/Pro activation code via `--code` or `--activation-code`, or the interactive OAuth/device-code prompt. After that it binds the project and sends only allowlisted project metadata (file names + package/build manifests) to the API and generates:

package/bin/0dai.js

@@ -102,6 +102,7 @@ const { cmdAudit } = require("../lib/commands/audit");
 const { cmdDoctor } = require("../lib/commands/doctor");
 const { cmdValidate } = require("../lib/commands/validate");
 const { cmdUpdate } = require("../lib/commands/update");
+const { cmdUpgrade } = require("../lib/commands/upgrade");
 const { cmdReflect } = require("../lib/commands/reflect");
 const { cmdMetrics } = require("../lib/commands/metrics");
 const { cmdHeatmap } = require("../lib/commands/heatmap");
@@ -128,6 +129,7 @@ const { cmdPaste } = require("../lib/commands/paste");
 const { cmdReceipt } = require("../lib/commands/receipt");
 const { cmdBoneyard } = require("../lib/commands/boneyard");
 const { cmdQuota } = require("../lib/commands/quota");
+const { cmdUsage } = require("../lib/commands/usage");
 const { cmdGh } = require("../lib/commands/gh");
 const { cmdLoop } = require("../lib/commands/loop");
 const { cmdImportClaudeCodeAgents } = require("../lib/commands/import_claude_code_agents");
@@ -150,7 +152,7 @@ function printHelp() {
   console.log("");
   console.log("Daily (regular work):");
   console.log("  sync           Update ai/ layer after repo or server changes [--dry-run] [--yes] [--quiet] [--force]");
-  console.log("  run <goal>     Split a backlog item into agent tasks [--dry-run] [--agent claude|codex|gemini] [--provider X]");
+  console.log("  run <goal>     Split a backlog item into agent tasks [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider X]");
   console.log("  swarm status   Show queued, active, and done tasks");
   console.log("  swarm add      Queue one task for an agent [--task '...' --to agent]");
   console.log("  swarm-run      Add, dispatch, and wait for one swarm task as JSON");
@@ -174,6 +176,7 @@ function printHelp() {
   console.log("  provider       Local provider profiles, bindings, and direct invoke");
   console.log("  models         Show model ratings (--fast/--balanced/--deep/--available)");
   console.log("  quota          Agent subscription usage table [--refresh] [--json]");
+  console.log("  usage          Local token, task, and USD usage ledger [status|daily|monthly]");
   console.log("  workspace      Manage tmux workspace sessions (init|up|status)");
   console.log("  runner         Show runner/project-host architecture, queues, labels, and burst routing [status|plan|queue-status|label-audit|route-dry-run] [--json]");
   console.log("  report         Privacy-safe project reports (preview|push|status)");
@@ -206,6 +209,8 @@ const SYNC_ALLOWED_FLAGS = new Set([
   "--force",
   "--no-diff",
   "--no-mcp-auth",
+  "--skip-link-check",
+  "--strict-links",
 ]);
 
 function printSyncHelp() {
@@ -220,6 +225,8 @@ function printSyncHelp() {
   console.log("  --force        Also overwrite native config files from managed ai/ sources");
   console.log("  --no-diff      Hide unified diff output in previews/prompts");
   console.log("  --no-mcp-auth  Skip MCP cloud-token bootstrap during sync");
+  console.log("  --skip-link-check  Skip the SPEC-028 doc cross-link scan after sync");
+  console.log("  --strict-links Fail sync if doc_link_check reports broken or closed refs");
   console.log("  --target PATH  Run sync against another project path");
   console.log("");
 }
@@ -352,6 +359,7 @@ async function main() {
     case "validate": cmdValidate(target); break;
     case "reflect": cmdReflect(target, args); break;
     case "update": cmdUpdate(args); break;
+    case "upgrade": cmdUpgrade(); break;
     case "metrics": cmdMetrics(target); break;
     case "heatmap": cmdHeatmap(target, args.slice(1)); break;
     case "portfolio": cmdPortfolio(); break;
@@ -408,6 +416,7 @@ async function main() {
     case "receipt": cmdReceipt(target, args.slice(1)); break;
     case "boneyard": cmdBoneyard(target, args.slice(1)); break;
     case "quota": case "quotas": cmdQuota(target, args.slice(1)); break;
+    case "usage": cmdUsage(target, args.slice(1)); break;
     case "gh": await cmdGh(target, sub, args); break;
     case "loop": cmdLoop(target, sub, args); break;
     case "import": {

package/lib/commands/auth.js

@@ -133,16 +133,19 @@ async function loginWithExchangeCode(code) {
   if (!exchanged || exchanged.error || !exchanged.access_token) {
     throw new Error(exchanged && exchanged.error ? exchanged.error : "invalid or expired auth code");
   }
+  const status = await fetchAuthStatus(exchanged.access_token);
+  if (!status || status.error || !status.email) {
+    throw new Error(status && status.error ? status.error : "cloud validation failed after auth exchange");
+  }
   saveAuthState({
     access_token: exchanged.access_token,
-    email: exchanged.email || "",
-    name: exchanged.name || "",
+    email: status.email,
+    plan: status.plan || "free",
+    name: status.name || exchanged.name || "",
+    license: status.license || {},
+    plan_expires_at: status.plan_expires_at || "",
     authenticated_at: new Date().toISOString(),
   });
-  const status = await fetchAuthStatus();
-  if (!status || status.error || !status.email) {
-    throw new Error(status && status.error ? status.error : "cloud validation failed after auth exchange");
-  }
   return status;
 }
 

package/lib/commands/doctor.js

@@ -2,6 +2,25 @@
 const shared = require("../shared");
 const { log, T, R, D, fs, path, spawnSync, findRepoScript, SUPPORTED_CLIS, recordExperienceEvent } = shared;
 
+function nodePtyProbe() {
+  try {
+    require.resolve("node-pty");
+    return {
+      name: "node-pty",
+      present: true,
+      sev: "ok",
+      hint: "node-pty available for terminal session spawn",
+    };
+  } catch {
+    return {
+      name: "node-pty",
+      present: false,
+      sev: "warn",
+      hint: "install node-pty for terminal sessions: npm i -g node-pty",
+    };
+  }
+}
+
 function ghostAuthStatus(home = process.env.HOME || process.env.USERPROFILE || "") {
   const customApiEnv = home ? path.join(home, ".custom-api", "custom-api.env") : "";
   const legacyAnthropicEnv = home ? path.join(home, ".claude-api-isolated", "anthropic.env") : "";
@@ -256,4 +275,4 @@ function cmdDoctor(target, options = {}) {
   }
 }
 
-module.exports = { cmdDoctor, ghostAuthStatus };
+module.exports = { cmdDoctor, ghostAuthStatus, nodePtyProbe };

package/lib/commands/init.js

@@ -15,6 +15,7 @@ const { cmdAuthLogin, ensureAccountForActivation, parseActivationArgs } = requir
 const { ensureGithubFlowPolicy, warnHooksPathDrift } = require("./gh");
 const { renderFileMapDiff, confirmOrExit, shouldAutoYes } = require("../utils/diff-preview");
 const { bootstrapMcp } = require("../utils/mcp-auth");
+const { recordActivationInit } = require("../utils/activation_telemetry");
 
 const ensureAuthenticated = makeEnsureAuthenticated(cmdAuthLogin);
 const SYNC_FULL_CONTENT_LIMIT = 10000;
@@ -463,6 +464,8 @@ async function cmdInit(target, args = []) {
   // First-run proof gate (issue #342). All 4 gates pass once we reach here:
   // license active (line above), project bound, ai/ layer written, heartbeat sent.
   // Idempotent — only fires once per project. See docs/first-run.md.
+  recordActivationInit(target, boundProject.project_id || identity.project_id);
+
   const firstRun = logFirstRunSuccess(target, {
     license: true,
     project_bound: true,
@@ -557,6 +560,60 @@ function normalizeEnvironmentManifest(target) {
   return { path: filePath, changed: true };
 }
 
+// runDocLinkCheck — SPEC-028 Phase 2 (#2689). After the managed layer has been
+// written, run scripts/doc_link_check.py to surface broken/closed cross-refs
+// in ai/ and docs/. Warn-only by default so a flaky reference never blocks an
+// otherwise successful sync; --strict-links promotes failures to a non-zero
+// exit, and --skip-link-check bypasses the hook entirely.
+//
+// The hook intentionally stays silent when the script is missing (Phase 1 may
+// not have shipped to a downstream project) and when python3 is unavailable.
+// Output is streamed inline via stdio: "inherit" so authors see exact paths.
+function runDocLinkCheck(target, args = [], options = {}) {
+  if (args.includes("--skip-link-check")) {
+    return { skipped: true, reason: "flag" };
+  }
+  const script = path.join(target, "scripts", "doc_link_check.py");
+  if (!fs.existsSync(script)) {
+    return { skipped: true, reason: "missing-script" };
+  }
+  const quiet = !!options.quiet;
+  const strict = args.includes("--strict-links");
+  const { spawnSync } = require("child_process");
+  if (!quiet) log("doc-link-check: scanning ai/**/*.md docs/**/*.md");
+  const result = spawnSync(
+    "python3",
+    [
+      script,
+      "--repo-root",
+      target,
+      "--paths",
+      "ai/**/*.md",
+      "docs/**/*.md",
+      "--format",
+      "md",
+      "--fail-on",
+      "broken,closed",
+    ],
+    { stdio: "inherit", cwd: target },
+  );
+  if (result.error && result.error.code === "ENOENT") {
+    if (!quiet) console.log(`  ${D}doc-link-check skipped: python3 not found${R}`);
+    return { skipped: true, reason: "no-python" };
+  }
+  const status = typeof result.status === "number" ? result.status : 0;
+  if (status !== 0) {
+    if (strict) {
+      log(`${W}doc-link-check failed (exit ${status}); --strict-links is set${R}`);
+      process.exit(status);
+    }
+    if (!quiet) log(`${W}doc-link-check found issues (exit ${status}); warn-only (pass --strict-links to fail sync)${R}`);
+    return { ran: true, status, strict, broken: true };
+  }
+  if (!quiet) log("doc-link-check: clean");
+  return { ran: true, status: 0, strict, broken: false };
+}
+
 async function cmdSync(target, args = []) {
   const dryRun = args.includes("--dry-run");
   const quiet = args.includes("--quiet") || args.includes("-q");
@@ -669,6 +726,12 @@ async function cmdSync(target, args = []) {
   } else {
     log("already up to date");
   }
+
+  // SPEC-028 Phase 2 (#2689) — scan managed docs for broken cross-refs after
+  // the layer is on disk. Warn-only unless --strict-links; --skip-link-check
+  // bypasses. Runs even when no files changed so stale local refs surface on
+  // every sync.
+  runDocLinkCheck(target, args, { quiet });
   const envManifest = normalizeEnvironmentManifest(target);
   if (!quiet && envManifest.changed) {
     log("environment manifest target normalized: ai/manifest/environment.yaml");
@@ -823,5 +886,6 @@ module.exports = {
   hashFile,
   detectRegistryDrift,
   guardRegistryDrift,
+  runDocLinkCheck,
   SYNC_FULL_CONTENT_LIMIT,
 };

package/lib/commands/run.js

@@ -1,26 +1,43 @@
 "use strict";
 const shared = require("../shared");
 const { log, T, R, D, fs, path, apiCall } = shared;
+const {
+  estimateRunCost,
+  formatTokens,
+  formatUsd,
+  formatUsdPer1k,
+} = require("../utils/run_cost");
+const { recordActivationFirstTask } = require("../utils/activation_telemetry");
 
 async function cmdRun(goal, target, args = []) {
   if (!goal) {
-    console.log(`Usage: 0dai run <goal> [--dry-run] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
+    console.log(`Usage: 0dai run <goal> [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
     console.log(`  Example: 0dai run "add dark mode to settings page"`);
+    console.log(`  Example: 0dai run "fix login bug" --dry-cost`);
+    console.log(`  Example: 0dai run "refactor auth" --max-cost 0.50`);
     return;
   }
 
   const dryRun = args.includes("--dry-run");
+  const dryCost = args.includes("--dry-cost");
   const agentIdx = args.indexOf("--agent");
   const agentOverride = agentIdx >= 0 ? args[agentIdx + 1] : null;
   const providerIdx = args.indexOf("--provider");
   const providerOverride = providerIdx >= 0 ? normalizeProvider(args[providerIdx + 1] || "") : null;
   const providerModelIdx = args.indexOf("--provider-model");
   const providerModel = providerModelIdx >= 0 ? (args[providerModelIdx + 1] || "") : "";
+  const maxCostIdx = args.indexOf("--max-cost");
+  const maxCostRaw = maxCostIdx >= 0 ? args[maxCostIdx + 1] : null;
+  const maxCost = maxCostRaw != null ? parseFloat(maxCostRaw) : null;
 
   if (providerIdx >= 0 && !providerOverride) {
     log("error: unsupported provider. Supported: deepseek, gemini-direct, codex, claude-opus, claude-sonnet");
     return;
   }
+  if (maxCostIdx >= 0 && (maxCostRaw == null || Number.isNaN(maxCost) || maxCost < 0)) {
+    log("error: --max-cost requires a non-negative number");
+    process.exit(1);
+  }
 
   // Read project context
   let stack = "generic", agents = ["claude"], commands = {};
@@ -30,9 +47,9 @@ async function cmdRun(goal, target, args = []) {
     agents = disc.selected_agents || ["claude"];
   } catch {}
 
-  if (!dryRun) process.stdout.write(`${T}[0dai]${R} decomposing goal...`);
+  if (!dryRun && !dryCost) process.stdout.write(`${T}[0dai]${R} decomposing goal...`);
   const result = await apiCall("/v1/run", { goal, context: { stack, agents, commands } });
-  if (!dryRun) process.stdout.write("\r" + " ".repeat(40) + "\r");
+  if (!dryRun && !dryCost) process.stdout.write("\r" + " ".repeat(40) + "\r");
 
   if (result.error) { log(`error: ${result.error}`); return; }
 
@@ -50,6 +67,23 @@ async function cmdRun(goal, target, args = []) {
     console.log(`     ${D}→ ${agent}${providerText}  [${t.model_tier}]${t.description ? "  " + t.description : ""}${R}`);
   }
 
+  const costEstimate = estimateRunCost(tasks, {
+    providerOverride,
+    resolveAgent: (task) => agentOverride || providerAgent(providerOverride) || task.assigned_to,
+  });
+
+  if (dryCost) {
+    printCostPreview(costEstimate);
+    console.log(`\n  ${D}[dry-cost] estimate only — no tasks queued${R}\n`);
+    return;
+  }
+
+  if (maxCost != null && costEstimate.totalUsd > maxCost) {
+    log(`error: estimated cost ${formatUsd(costEstimate.totalUsd)} exceeds --max-cost ${formatUsd(maxCost)}`);
+    console.log(`  ${D}Re-run with --dry-cost to inspect the breakdown, or raise --max-cost${R}`);
+    process.exit(1);
+  }
+
   if (dryRun) {
     console.log(`\n  ${D}[dry-run] would create ${tasks.length} task(s) in swarm queue${R}\n`);
     return;
@@ -88,6 +122,29 @@ async function cmdRun(goal, target, args = []) {
 
   console.log(`\n  ${T}✓${R} ${created.length} task${created.length === 1 ? "" : "s"} added to swarm queue`);
   console.log(`  ${D}Monitor: 0dai watch  |  Queue: 0dai swarm status${R}\n`);
+
+  if (created.length > 0) {
+    const identity = shared.buildProjectIdentity(target, shared.collectMetadata(target));
+    recordActivationFirstTask(target, identity.project_id);
+  }
+}
+
+function printCostPreview(costEstimate) {
+  console.log(`\n  ${T}Cost preview${R} (estimate):\n`);
+  costEstimate.tasks.forEach((row, index) => {
+    console.log(
+      `  ${T}${index + 1}.${R} ${row.title || "task"}`
+      + `\n     ${D}→ ${row.agent} [${row.tier}]`
+      + `  ~${formatTokens(row.tokens)} tokens`
+      + `  ~${formatUsd(row.estimatedUsd)}`
+      + `  (${formatUsdPer1k(row.usdPer1k)})${R}`,
+    );
+  });
+  console.log(
+    `\n  ${T}Total:${R} ~${formatTokens(costEstimate.totalTokens)} tokens`
+    + `  ~${formatUsd(costEstimate.totalUsd)}`
+    + `  (blended ${formatUsdPer1k(costEstimate.blendedUsdPer1k)})`,
+  );
 }
 
 function normalizeProvider(provider) {
@@ -114,4 +171,4 @@ function providerAgent(provider) {
   return null;
 }
 
-module.exports = { cmdRun };
+module.exports = { cmdRun, printCostPreview };

package/lib/commands/status.js

@@ -4,6 +4,7 @@ const {
   log, T, R, D, fs, path, spawnSync, findRepoScript,
   getSwarmQuotaLocal, _detectPlanLocal, PLAN_LEVELS, loadAuthState,
 } = shared;
+const { getActivationDurationStats, printActivationStats } = require("../utils/activation_telemetry");
 
 function countJson(dir) {
   try { return fs.readdirSync(dir).filter(f => f.endsWith(".json")).length; } catch { return 0; }
@@ -116,6 +117,7 @@ function collectStatusPayload(target) {
       detected: driftDetected,
     },
     warnings: warningCount,
+    activation_ttfv: getActivationDurationStats(target),
   };
 }
 
@@ -158,6 +160,8 @@ function cmdStatus(target, options = {}) {
     console.log(`  drift: config changes detected — run: 0dai doctor --drift`);
   }
 
+  printActivationStats(target);
+
   return payload;
 }
 

package/lib/commands/upgrade.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+const { buildUpgradeUrl } = require("../utils/plan");
+
+function isInteractive() {
+  return !!(process.stdin && process.stdin.isTTY && process.stdout && process.stdout.isTTY);
+}
+
+function isBrowserDisabled(env = process.env) {
+  const browser = env.BROWSER;
+  if (browser == null) return false;
+  const normalized = String(browser).trim().toLowerCase();
+  return normalized === "" || normalized === "0" || normalized === "false" || normalized === "none";
+}
+
+function openBrowser(url, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  const platform = deps.platform || process.platform;
+  let command;
+  let args;
+  if (platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+  const result = spawn(command, args, { stdio: "ignore", timeout: 5000 });
+  return result.status === 0;
+}
+
+function cmdUpgrade(options = {}) {
+  const writeLine = typeof options.writeLine === "function" ? options.writeLine : (msg) => console.log(msg);
+  const url = buildUpgradeUrl(options.params);
+  const interactive = typeof options.isInteractive === "function"
+    ? options.isInteractive()
+    : isInteractive();
+  const browserDisabled = isBrowserDisabled(options.env || process.env);
+
+  if (interactive && !browserDisabled) {
+    const opened = openBrowser(url, options);
+    if (!opened) writeLine(url);
+    return;
+  }
+
+  writeLine(url);
+}
+
+module.exports = {
+  cmdUpgrade,
+  openBrowser,
+  isInteractive,
+  isBrowserDisabled,
+};

package/lib/utils/activation_telemetry.js

@@ -0,0 +1,156 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+function activationPath(target) {
+  return path.join(target, "ai", "meta", "telemetry", "activation.jsonl");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readEvents(target) {
+  const file = activationPath(target);
+  if (!fs.existsSync(file)) return [];
+  const lines = fs.readFileSync(file, "utf8").trim().split("\n").filter(Boolean);
+  const events = [];
+  for (const ln of lines) {
+    try {
+      const row = JSON.parse(ln);
+      if (row && row.event) events.push(row);
+    } catch { /* ignore malformed lines */ }
+  }
+  return events;
+}
+
+function appendEvent(target, entry) {
+  const file = activationPath(target);
+  try {
+    ensureDir(file);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n", "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasEvent(events, eventName, projectId) {
+  return events.some((e) => e.event === eventName && e.project_id === projectId);
+}
+
+function findInitTs(events, projectId) {
+  const init = events.find((e) => e.event === "init" && e.project_id === projectId);
+  return init && init.ts ? init.ts : null;
+}
+
+function parseTs(ts) {
+  const ms = Date.parse(ts);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+// Idempotently append `{event:"init", ts, project_id}` on successful init.
+function recordActivationInit(target, projectId) {
+  try {
+    if (!projectId) return { fired: false };
+    const events = readEvents(target);
+    if (hasEvent(events, "init", projectId)) return { fired: false };
+    const entry = { event: "init", ts: nowIso(), project_id: projectId };
+    return { fired: appendEvent(target, entry) };
+  } catch {
+    return { fired: false };
+  }
+}
+
+// Idempotently append first_task with duration_ms = first_task.ts - init.ts.
+function recordActivationFirstTask(target, projectId) {
+  try {
+    if (!projectId) return { fired: false, durationMs: null };
+    const events = readEvents(target);
+    if (hasEvent(events, "first_task", projectId)) {
+      return { fired: false, durationMs: null };
+    }
+
+    const initTs = findInitTs(events, projectId);
+    const ts = nowIso();
+    let durationMs = null;
+    if (initTs) {
+      const initMs = parseTs(initTs);
+      const taskMs = parseTs(ts);
+      if (initMs != null && taskMs != null) {
+        durationMs = Math.max(0, taskMs - initMs);
+      }
+    }
+
+    const entry = {
+      event: "first_task",
+      ts,
+      project_id: projectId,
+      duration_ms: durationMs,
+    };
+    const fired = appendEvent(target, entry);
+    return { fired, durationMs };
+  } catch {
+    return { fired: false, durationMs: null };
+  }
+}
+
+function percentile(sorted, p) {
+  if (!sorted.length) return null;
+  if (sorted.length === 1) return sorted[0];
+  const idx = (sorted.length - 1) * p;
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sorted[lo];
+  const weight = idx - lo;
+  return Math.round(sorted[lo] * (1 - weight) + sorted[hi] * weight);
+}
+
+function getActivationDurationStats(target) {
+  const events = readEvents(target);
+  const durations = events
+    .filter((e) => e.event === "first_task"
+      && typeof e.duration_ms === "number"
+      && Number.isFinite(e.duration_ms))
+    .map((e) => e.duration_ms)
+    .sort((a, b) => a - b);
+
+  return {
+    count: durations.length,
+    p50_ms: percentile(durations, 0.5),
+    p90_ms: percentile(durations, 0.9),
+  };
+}
+
+function formatDurationMs(ms) {
+  if (ms == null) return "?";
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+function printActivationStats(target) {
+  const stats = getActivationDurationStats(target);
+  if (stats.count === 0) return stats;
+  console.log(
+    `  activation TTFV: p50 ${formatDurationMs(stats.p50_ms)}`
+    + ` / p90 ${formatDurationMs(stats.p90_ms)}`
+    + ` (${stats.count} sample${stats.count === 1 ? "" : "s"})`,
+  );
+  return stats;
+}
+
+module.exports = {
+  activationPath,
+  readEvents,
+  recordActivationInit,
+  recordActivationFirstTask,
+  getActivationDurationStats,
+  printActivationStats,
+  formatDurationMs,
+};