@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/pipeline/scripts/uninstall.mjs

@@ -35,9 +35,20 @@
  * @module pipeline/scripts/runtime/uninstall
  */
 
-import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
 import { execFileSync } from "child_process";
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
 import { createInterface } from "readline";
@@ -100,6 +111,43 @@ const adapterTarget = (() => {
   return raw ? raw.slice("--target=".length) : process.cwd();
 })();
 
+/**
+ * tmp + rename, preserving a symlinked target and the existing file mode.
+ *
+ * Duplicated from install/_common.mjs rather than imported: this script runs
+ * standalone from ~/.claude/scripts, where the install tree does not exist.
+ * A plain writeFileSync could leave the host's settings.json truncated on a
+ * crash; a naive rename would replace a dotfiles symlink with a regular file
+ * and reset a 0600 file to 0644.
+ *
+ * @param {string} path
+ * @param {string} content
+ */
+function atomicWrite(path, content) {
+  let target = path;
+  try {
+    if (lstatSync(path).isSymbolicLink()) target = realpathSync(path);
+  } catch {
+    // Missing file: nothing to preserve.
+  }
+  let mode;
+  try {
+    mode = statSync(target).mode & 0o777;
+  } catch {
+    mode = undefined;
+  }
+  const tmp = `${target}.tmp-${process.pid}`;
+  writeFileSync(tmp, content);
+  if (mode !== undefined) {
+    try {
+      chmodSync(tmp, mode);
+    } catch {
+      // Best effort: a failed chmod must not lose the write.
+    }
+  }
+  renameSync(tmp, target);
+}
+
 /**
  * Report a planned action. Always logged; in --dry-run mode, no side effects
  * are performed.
@@ -197,10 +245,7 @@ function deregisterCodexMcpServer() {
  */
 function deregisterClaudeMcpServer() {
   const localBin = join(homedir(), ".local", "bin", "claude");
-  deregisterMcpServer("claude", existsSync(localBin) ? localBin : undefined, [
-    "--scope",
-    "user",
-  ]);
+  deregisterMcpServer("claude", existsSync(localBin) ? localBin : undefined, ["--scope", "user"]);
 }
 
 /**
@@ -220,6 +265,106 @@ function deregisterCopilotMcpServer() {
  * @param {string} parent
  * @param {(name: string) => boolean} predicate
  */
+/**
+ * Remove the pipeline's command namespace while preserving user-authored
+ * local-only alias wrappers (frontmatter `local-only: true`). Those wrappers
+ * exist ONLY under the host dir - install/claude.mjs snapshots them across its
+ * wipe for the same reason - so removing the namespace wholesale would destroy
+ * content a reinstall can never bring back.
+ * @param {string} cmdDir - e.g. ~/.claude/commands/multi-agent
+ * @returns {number} preserved wrapper dirs
+ */
+function rmCommandsPreservingLocalOnly(cmdDir) {
+  // An install interrupted between its wipe and its restore leaves wrappers in
+  // a hidden stash beside the namespace. Adopt them back before deciding what
+  // to preserve, or the "local-only wrappers preserved" promise below strands
+  // them in a dot-directory the user never sees.
+  const stashDir = join(dirname(cmdDir), ".multi-agent-wrapper-stash");
+  if (existsSync(stashDir) && !dryRun) {
+    for (const name of readdirSync(stashDir)) {
+      const to = join(cmdDir, name);
+      if (existsSync(to)) continue;
+      try {
+        renameSync(join(stashDir, name), to);
+        console.log(`    recovered stashed wrapper from an interrupted install: ${name}`);
+      } catch {
+        /* best effort - a failed recovery must not block the uninstall */
+      }
+    }
+    rmIfExists(stashDir);
+  }
+  if (!existsSync(cmdDir)) return 0;
+  const isLocalOnly = (dir) => {
+    const skill = join(dir, "SKILL.md");
+    try {
+      return existsSync(skill) && /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+    } catch {
+      return false;
+    }
+  };
+  const preserved = readdirSync(cmdDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isLocalOnly(join(cmdDir, e.name)))
+    .map((e) => e.name);
+  if (preserved.length === 0) {
+    rmIfExists(cmdDir);
+    return 0;
+  }
+  for (const entry of readdirSync(cmdDir)) {
+    if (preserved.includes(entry)) continue;
+    rmIfExists(join(cmdDir, entry));
+  }
+  console.log(
+    `    preserved ${preserved.length} local-only alias wrapper(s): ${preserved.join(", ")}`,
+  );
+  return preserved.length;
+}
+
+/** Written by install/_platform-filter.mjs beside the skills it delivered. */
+const EXTERNAL_SKILLS_MANIFEST = ".external-skills-manifest.json";
+
+/**
+ * Remove the external skill catalog THIS install delivered, read from the
+ * manifest the installer wrote beside it.
+ *
+ * Deliberately not derived from `.skills-index.json`: that file is the shipped
+ * catalog copied verbatim, so it lists platform-filtered skills that were never
+ * installed, and it says nothing about which package version's tree is on disk.
+ * Either gap would delete a user-authored skill dir that happens to share a
+ * catalog name. Same contract as `.plugin-skills-manifest.json`.
+ *
+ * No manifest (a pre-manifest install) means ours and theirs are
+ * indistinguishable, so nothing is removed and the user is told why.
+ *
+ * @param {string} skillsDir
+ * @returns {number} dirs removed
+ */
+function rmExternalDeliveredSkills(skillsDir) {
+  if (!existsSync(skillsDir)) return 0;
+  const manifestPath = join(skillsDir, EXTERNAL_SKILLS_MANIFEST);
+  let names = null;
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+      if (Array.isArray(parsed)) names = new Set(parsed);
+    } catch {
+      names = null;
+    }
+  }
+  if (!names) {
+    console.log(
+      `    note: no ${EXTERNAL_SKILLS_MANIFEST} under ${skillsDir} - external skill dirs left in ` +
+        `place (cannot tell pipeline-delivered from user-authored; ` +
+        `node install.js --claude prunes copies identical to the shipped catalog, ` +
+        `--prune-external removes the rest)`,
+    );
+    return 0;
+  }
+  let n = rmMatchingDirs(skillsDir, (name) => names.has(name));
+  n += rmMatchingFiles(skillsDir, (name) => /^NOTICE-.*\.md$/.test(name));
+  rmIfExists(manifestPath);
+  return n;
+}
+
 function rmMatchingDirs(parent, predicate) {
   if (!existsSync(parent)) return 0;
   let count = 0;
@@ -364,7 +509,7 @@ function stripManagedBlock(filePath) {
           rmSync(filePath, { force: true });
           console.log(`    removed (was pipeline-only): ${filePath}`);
         } else {
-          writeFileSync(filePath, remaining + "\n");
+          atomicWrite(filePath, remaining + "\n");
           console.log(`    cleaned pipeline section: ${filePath}`);
         }
         return true;
@@ -381,7 +526,7 @@ function stripManagedBlock(filePath) {
     rmSync(filePath, { force: true });
     console.log(`    removed (was pipeline-only): ${filePath}`);
   } else {
-    writeFileSync(filePath, cleaned + "\n");
+    atomicWrite(filePath, cleaned + "\n");
     console.log(`    cleaned pipeline block from: ${filePath}`);
   }
   return true;
@@ -424,7 +569,8 @@ function cleanClaudeSettings(settingsPath) {
           (h.matcher === "Bash" || h.matcher === "Bash(git commit:*)") &&
           h.hooks?.some(
             (sub) =>
-              sub.command?.includes("pre-commit-check.sh") || sub.command?.includes("agent-guard.sh"),
+              sub.command?.includes("pre-commit-check.sh") ||
+              sub.command?.includes("agent-guard.sh"),
           )
         ),
     );
@@ -437,7 +583,7 @@ function cleanClaudeSettings(settingsPath) {
     if (dryRun) {
       report("would update", settingsPath);
     } else {
-      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      atomicWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
       console.log(`    cleaned pipeline hook + env from: ${settingsPath}`);
     }
   }
@@ -497,6 +643,7 @@ export async function main() {
   );
   console.log("    - ~/.claude/CLAUDE.md (your customizations)");
   console.log("    - ~/.claude/rules/ (user-owned; installed write-if-missing, never overwritten)");
+  console.log("    - Local-only alias wrappers under commands/multi-agent/ (user-authored)");
   if (!allData) console.log("    - ~/.claude/multi-agent-preferences.json (your settings)");
   console.log("    - Your own content in copilot-instructions.md above the pipeline section");
   console.log("");
@@ -511,7 +658,7 @@ export async function main() {
     console.log("  [Claude Code] Removing...");
     deregisterClaudeMcpServer();
     const CLAUDE = join(HOME, ".claude");
-    rmIfExists(join(CLAUDE, "commands", "multi-agent"));
+    rmCommandsPreservingLocalOnly(join(CLAUDE, "commands", "multi-agent"));
     rmIfExists(join(CLAUDE, "scripts"));
     // Pipeline-managed trees the installer lays down alongside scripts/.
     rmIfExists(join(CLAUDE, "multi-agent-refs"));
@@ -538,6 +685,7 @@ export async function main() {
         name === "figma-to-component",
     );
     n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
+    n += rmExternalDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));
@@ -573,6 +721,7 @@ export async function main() {
     );
     n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     n += rmPluginDeliveredSkills(skills);
+    n += rmExternalDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));

package/pipeline/scripts/usage-report.mjs

@@ -0,0 +1,426 @@
+/**
+ * usage-report.mjs  -  usage ping (opt-in) for the private mission-control dashboard.
+ *
+ * Emits one compact activity event keyed by run id (`taskId`). Called at each
+ * phase boundary (status=running, via phase-tracker.sh) and once at the end
+ * (terminal status, from Phase 7 report or the halt path). The server upserts
+ * by run id, so per-phase calls update ONE record - it always reflects the last
+ * phase a run reached, including runs that halt before Phase 7. Fire-and-forget,
+ * never throws, never delays the run.
+ *
+ * Payload is activity metadata only  -  who, command, mode, input type, repo,
+ * phase, outcome, halt cause, review iterations, duration, token spend, cost,
+ * per-phase breakdown, language, stack, plugins, integrations, credential
+ * health, invoked skills, error tags, version. No prompts, code, diffs, token
+ * values, or absolute paths.
+ *
+ * Enable + configure via prefs.global.usageLog:
+ *   { "enabled": true,
+ *     "endpoint": "https://mmerterden.vercel.app/api/usage/ingest",
+ *     "token": "<shared ingest token>" }         // token may instead come from
+ *                                                 // env MULTI_AGENT_USAGE_TOKEN
+ * Nothing is sent when enabled is not true or no token resolves.
+ *
+ * Usage:
+ *   node usage-report.mjs --state /path/to/agent-state.json
+ *   node usage-report.mjs --task-id PROJ-123      # resolves the state path
+ *
+ * @module pipeline/scripts/usage-report
+ */
+
+import { readFileSync, existsSync, readdirSync, appendFileSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { costUsd } from "./_cost.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ENDPOINT_DEFAULT = "https://mmerterden.vercel.app/api/usage/ingest";
+const TIMEOUT_MS = 2500;
+
+function parseArgs(argv) {
+  const out = { state: null, taskId: null, phase: null, status: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--state") out.state = argv[++i];
+    else if (a === "--task-id") out.taskId = argv[++i];
+    else if (a === "--phase") out.phase = argv[++i];
+    else if (a === "--status") out.status = argv[++i];
+    else if (a === "--dry-run") out.dryRun = true;
+  }
+  return out;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function resolveGlobalPrefs() {
+  const path =
+    process.env.MULTI_AGENT_PREFS ||
+    join(homedir(), ".claude", "multi-agent-preferences.json");
+  return readJson(path)?.global ?? {};
+}
+
+function resolvePrefs() {
+  return resolveGlobalPrefs().usageLog ?? {};
+}
+
+function enabledPlugins(state) {
+  const root = state.projectRoot || process.cwd();
+  const settings = readJson(join(root, ".claude", "settings.json"));
+  const raw = settings?.enabledPlugins ?? settings?.plugins ?? [];
+  const list = Array.isArray(raw) ? raw : Object.keys(raw || {});
+  return list
+    .map((p) => (typeof p === "string" ? p.split("@")[0] : null))
+    .filter(Boolean)
+    .slice(0, 20);
+}
+
+function integrationTags(state) {
+  const apps = new Set();
+  if (state.jiraId) apps.add("jira");
+  if (state.remoteType) apps.add(String(state.remoteType).toLowerCase());
+  if (state.githubIssue) apps.add("github");
+  if (state.confluenceSpace) apps.add("confluence");
+  if (state.figmaAccess?.tier) apps.add("figma");
+  for (const call of state.telemetry?.mcpCalls ?? []) {
+    const tool = String(call?.tool || "");
+    const m = tool.match(/^mcp__([a-z0-9_]+?)__/i) || tool.match(/^mcp__([a-z0-9_]+)/i);
+    if (m) apps.add(m[1].replace(/_/g, "-").toLowerCase());
+  }
+  return Array.from(apps).slice(0, 20);
+}
+
+function credHealth() {
+  const g = resolveGlobalPrefs();
+  const mapping = g.keychainMapping ?? {};
+  const on = Object.entries(mapping)
+    .filter(([, v]) => typeof v === "string" && v.trim())
+    .map(([k]) => k)
+    .slice(0, 40);
+
+  const svc = {};
+  for (const [name, st] of Object.entries(g.serviceStatus ?? {})) {
+    const err = String(st?.error || "").toLowerCase();
+    const expired = /401|403|expired|unauthor|revoked|invalid.token/.test(err);
+    svc[name] = {
+      s: st?.ok ? "ok" : expired ? "expired" : "fail",
+      at: st?.checkedAt || null,
+    };
+  }
+  return { on, svc };
+}
+
+function invokedCalls(state) {
+  const names = new Set();
+  for (const c of state.telemetry?.skillCalls ?? []) {
+    if (c?.skill) names.add(String(c.skill));
+  }
+  return Array.from(names).slice(0, 30);
+}
+
+function detectOs() {
+  const p = platform();
+  if (p === "darwin") return "macos";
+  if (p === "win32") return "windows";
+  if (p === "linux") return "linux";
+  return p;
+}
+
+function detectCli() {
+  const e = process.env;
+  if (e.MULTI_AGENT_CLI) return String(e.MULTI_AGENT_CLI).toLowerCase();
+  if (e.CLAUDECODE || e.CLAUDE_CODE_ENTRYPOINT || e.ANTHROPIC_CLI) return "claude";
+  if (e.CODEX_HOME || e.CODEX_SANDBOX || e.CODEX_CLI) return "codex";
+  if (e.COPILOT_CLI || e.GITHUB_COPILOT_CLI || e.GH_COPILOT || e.COPILOT_AGENT_ID) {
+    return "copilot";
+  }
+  return null;
+}
+
+function deriveContext(state) {
+  return {
+    lang: resolveGlobalPrefs().outputLanguage ?? null,
+    os: detectOs(),
+    cli: detectCli(),
+    stack: Array.isArray(state.stacks)
+      ? state.stacks.slice(0, 10)
+      : state.stack
+        ? [String(state.stack)]
+        : [],
+    plug: enabledPlugins(state),
+    apps: integrationTags(state),
+    creds: credHealth(),
+    calls: invokedCalls(state),
+  };
+}
+
+function resolveStatePath({ state, taskId }) {
+  if (state) return state;
+  if (process.env.MULTI_AGENT_STATE_FILE && existsSync(process.env.MULTI_AGENT_STATE_FILE)) {
+    return process.env.MULTI_AGENT_STATE_FILE;
+  }
+  if (!taskId) return null;
+
+  const logRoot = join(homedir(), ".claude", "logs", "multi-agent");
+  const direct = [
+    join(logRoot, taskId, "agent-state.json"),
+    join(process.cwd(), ".worktrees", taskId, "agent-state.json"),
+    join(process.cwd(), "agent-state.json"),
+  ];
+  const hit = direct.find((p) => existsSync(p));
+  if (hit) return hit;
+
+  try {
+    for (const project of readdirSync(logRoot)) {
+      const p = join(logRoot, project, taskId, "agent-state.json");
+      if (existsSync(p)) return p;
+    }
+  } catch {
+    /* logs dir missing */
+  }
+  return null;
+}
+
+function packageVersion() {
+  const candidates = [
+    join(__dirname, "..", "..", "package.json"),
+    join(homedir(), ".claude", "multi-agent-pipeline", "package.json"),
+  ];
+  for (const p of candidates) {
+    const v = readJson(p)?.version;
+    if (v) return v;
+  }
+  return null;
+}
+
+function inputType(state) {
+  if (state.jiraId) return "jira";
+  if (state.githubIssue) return "github-issue";
+  return "free-text";
+}
+
+function commandOf(state) {
+  if (state.mode) return state.mode;
+  if (state.onlyDevelop) return "dev";
+  if (state.localMode) return "local";
+  return "full";
+}
+
+function resolveTracker(state) {
+  const id = state.taskId || state.shortId;
+  if (id == null) return null;
+  const root = join(homedir(), ".claude", "logs", "multi-agent");
+  const candidates = [
+    join(root, String(id), "tracker-state.json"),
+    state.artifactsPath ? join(state.artifactsPath, "tracker-state.json") : null,
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+function phaseDurationSec(p) {
+  if (Number.isFinite(Number(p?.duration_ms))) {
+    return Math.round(Number(p.duration_ms) / 1000);
+  }
+  const s = p?.startedAt || p?.started_at || p?.start;
+  const f = p?.finishedAt || p?.finished_at || p?.completed_at || p?.end;
+  const sm = s ? Date.parse(s) : NaN;
+  const fm = f ? Date.parse(f) : NaN;
+  if (Number.isNaN(sm) || Number.isNaN(fm) || fm < sm) return null;
+  return Math.round((fm - sm) / 1000);
+}
+
+function trackerSummary(state) {
+  const path = resolveTracker(state);
+  if (!path) return { tk: null, cost: null, phs: null, failed: [], models: [] };
+  const tracker = readJson(path);
+  if (!tracker?.phases) return { tk: null, cost: null, phs: null, failed: [], models: [] };
+
+  let tin = 0;
+  let tout = 0;
+  let tcache = 0;
+  const phs = [];
+  const failed = [];
+  const models = new Set();
+  for (const [id, p] of Object.entries(tracker.phases)) {
+    if (p?.status === "failed") failed.push(id);
+    if (p?.model) models.add(String(p.model));
+    const pin = Number(p?.tokens_in || 0);
+    const pout = Number(p?.tokens_out || 0);
+    const pcache = Number(p?.tokens_cached || 0);
+    tin += pin;
+    tout += pout;
+    tcache += pcache;
+    phs.push({
+      p: Number.isNaN(Number(id)) ? id : Number(id),
+      st: p?.status || null,
+      du: phaseDurationSec(p),
+      tk: pin + pout + pcache || null,
+    });
+  }
+  phs.sort((a, b) => Number(a.p) - Number(b.p));
+
+  const total = tin + tout + tcache;
+  const table = readJson(join(__dirname, "cost-table.json"));
+  const rate = table?.prices?.opus;
+  const cost =
+    total > 0 && rate ? Number(costUsd(rate, tin, tout, tcache).toFixed(4)) : null;
+  return {
+    tk: total || null,
+    cost,
+    phs: phs.length ? phs : null,
+    failed,
+    models: Array.from(models).slice(0, 10),
+  };
+}
+
+function deriveErrors(state, failedPhases) {
+  const errs = new Set();
+  if (state.haltReason) errs.add(String(state.haltReason));
+  for (const id of failedPhases ?? []) errs.add(`phase-${id}-failed`);
+  const s = String(state.status || "").toLowerCase();
+  if (s === "failed") errs.add("run-failed");
+  return Array.from(errs).slice(0, 20);
+}
+
+function durationSec(state) {
+  const s = state.startedAt ? Date.parse(state.startedAt) : NaN;
+  const f = state.finishedAt ? Date.parse(state.finishedAt) : NaN;
+  if (Number.isNaN(s) || Number.isNaN(f) || f < s) return null;
+  return Math.round((f - s) / 1000);
+}
+
+function runId(state) {
+  const base = state.taskId ?? state.shortId;
+  return base == null ? null : String(base);
+}
+
+function eventTimestamp(state) {
+  return state.finishedAt || state.updatedAt || new Date().toISOString();
+}
+
+const TERMINAL_STATUSES = ["complete", "completed", "failed", "paused", "halted", "error"];
+
+function isTerminalStatus(state) {
+  if (state.haltReason) return true;
+  return TERMINAL_STATUSES.includes(String(state.status || "").toLowerCase());
+}
+
+function appendErrorLedger(event) {
+  if (!event.errs || event.errs.length === 0) return;
+  const path = join(homedir(), ".claude", "logs", "multi-agent", "errors-ledger.jsonl");
+  const row = {
+    t: event.t,
+    id: event.id,
+    u: event.u,
+    c: event.c,
+    rp: event.rp,
+    ph: event.ph,
+    v: event.v,
+    errs: event.errs,
+  };
+  try {
+    appendFileSync(path, JSON.stringify(row) + "\n");
+  } catch {
+    /* logs dir missing or unwritable - never break the run */
+  }
+}
+
+function buildEvent(state) {
+  const spend = trackerSummary(state);
+  const ctx = deriveContext(state);
+  return {
+    id: runId(state),
+    t: eventTimestamp(state),
+    u: state.identity?.username || null,
+    c: commandOf(state),
+    m: state.mode || null,
+    ap: Boolean(state.autopilot),
+    lo: Boolean(state.localMode),
+    dev: Boolean(state.onlyDevelop),
+    in: inputType(state),
+    rp: state.project || null,
+    ph: typeof state.currentPhase === "number" ? state.currentPhase : null,
+    st: state.status || null,
+    hr: state.haltReason || null,
+    ri: Array.isArray(state.reviewIterations)
+      ? state.reviewIterations.length
+      : 0,
+    pr: Boolean(state.pr && (state.pr.url || state.pr.number)),
+    du: durationSec(state),
+    tk: spend.tk,
+    cost: spend.cost,
+    phs: spend.phs,
+    os: ctx.os,
+    cli: ctx.cli,
+    models: spend.models,
+    lang: ctx.lang,
+    stack: ctx.stack,
+    plug: ctx.plug,
+    apps: ctx.apps,
+    creds: ctx.creds,
+    calls: ctx.calls,
+    errs: deriveErrors(state, spend.failed),
+    v: packageVersion(),
+  };
+}
+
+async function post(endpoint, token, event) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Usage-Token": token,
+      },
+      body: JSON.stringify(event),
+      signal: ctrl.signal,
+    });
+  } catch {
+    /* never break the run on a telemetry failure */
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const prefs = resolvePrefs();
+  const token = process.env.MULTI_AGENT_USAGE_TOKEN || prefs.token || "";
+  const endpoint = prefs.endpoint || ENDPOINT_DEFAULT;
+
+  if (!args.dryRun && (prefs.enabled !== true || !token)) return;
+
+  const statePath = resolveStatePath(args);
+  let state = statePath ? readJson(statePath) : null;
+
+  if (!state) {
+    if (!args.taskId) return;
+    state = { taskId: args.taskId };
+  }
+
+  if (args.phase != null) {
+    const n = Number(args.phase);
+    state.currentPhase = Number.isNaN(n) ? args.phase : n;
+  }
+  if (args.status) state.status = args.status;
+
+  const event = buildEvent(state);
+
+  if (args.dryRun) {
+    process.stdout.write(JSON.stringify(event, null, 2) + "\n");
+    return;
+  }
+
+  if (isTerminalStatus(state)) appendErrorLedger(event);
+  await post(endpoint, token, event);
+}
+
+main().catch(() => process.exit(0));