@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.1

package/pipeline/scripts/usage-register.mjs

@@ -18,15 +18,19 @@
  * - It never registers when `usageLog.optOut` is true. That is permanent and
  *   checked before anything else, including any credential read (the
  *   credential store and gh).
- * - It never registers a name it has not checked: the login sent is the
- *   logged-in GitHub account that can read the pipeline repository
- *   (usage-identity.mjs). No such account, no registration. The request
- *   carries that account's gh token as `Authorization: Bearer` so the server
- *   can confirm the caller owns the login; the server pins the login to the
- *   token it issues.
- * - It never sends the gh token over plain http to anything but loopback, never
- *   follows a redirect with it, never prints it, and never puts it on an argv:
- *   gh prints it on its own stdout and it goes straight into the header.
+ * - It never registers a name it has not checked: the login sent is the GitHub
+ *   account on this machine that can read the pipeline repository
+ *   (usage-identity.mjs: gh, the git credential helper, or an SSH key). No such
+ *   account, no registration. The request proves the caller owns the login:
+ *   a gh or credential-helper token as `Authorization: Bearer`, or for an SSH
+ *   key a signature over a one-time server challenge
+ *   (`ssh-keygen -Y sign`), sent with no Authorization header at all. The
+ *   server pins the login to the token it issues.
+ * - It never sends a GitHub token over plain http to anything but loopback,
+ *   never follows a redirect with it, never prints it, never stores it, and
+ *   never puts it on an argv: gh or git prints it on its own stdout and it goes
+ *   straight into the header. The credential-helper token is read again at
+ *   registration rather than kept from the identity check.
  * - It never fails a caller. Offline, endpoint down, ingest disabled by the
  *   admin, no credential store: one status line, exit 0.
  * - It never reports run CONTENT. That is usage-report.mjs's contract, and it
@@ -35,22 +39,29 @@
  * Usage:
  *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback] [--refresh]
  *
- * `--refresh` re-checks which logged-in GitHub account can read the pipeline
- * repository instead of using the cached `usageLog.login`.
+ * `--refresh` re-checks which GitHub account on this machine can read the
+ * pipeline repository instead of using the cached `usageLog.login`.
  *
  * Exit: always 0. `--json` says what happened; the shell does not need to care.
  *
  * @module pipeline/scripts/usage-register
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
 import { join } from "node:path";
-import { homedir, hostname } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
 import { pathToFileURL } from "node:url";
 import { hostCommand } from "../lib/user-facing.mjs";
 import { canonicalEndpoint } from "../lib/usage-endpoint.mjs";
-import { ghTokenFor, resolveReportingLogin } from "./usage-identity.mjs";
+import {
+  SSH_TIMEOUT_MS,
+  credentialToken,
+  displayPath,
+  ghTokenFor,
+  resolveReportingLogin,
+  sshKeygenBin,
+} from "./usage-identity.mjs";
 import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
 
 const DEFAULT_ENDPOINT = "https://mmerterden.com/api/usage/ingest";
@@ -66,10 +77,10 @@ function readJson(file) {
 }
 
 /**
- * The name this machine registers under: the logged-in GitHub account that can
- * read the pipeline repository (usage-identity.mjs), or null when none can.
- * Never the git identity, never the OS user, never the account gh merely has
- * active.
+ * The name this machine registers under: the GitHub account on this machine
+ * that can read the pipeline repository (usage-identity.mjs), with the method
+ * it was found by, or login null when none can. Never the git identity, never
+ * the OS user, never the account gh merely has active.
  */
 export function reportingUser(prefsPath, { env = process.env, refresh = false } = {}) {
   return resolveReportingLogin({ prefsPath, env, refresh });
@@ -82,6 +93,12 @@ export function reportingUser(prefsPath, { env = process.env, refresh = false }
  * them, and "you opted out" and "we could not reach the endpoint" are different
  * facts about the same silence.
  */
+function pinned(u) {
+  return (
+    typeof u.registeredAs === "string" && u.registeredAs !== "" && u.registeredFallback !== true
+  );
+}
+
 export function decideRegistration(
   prefs,
   {
@@ -102,8 +119,18 @@ export function decideRegistration(
   if (env.MULTI_AGENT_USAGE_TOKEN) return { act: false, reason: "token in environment" };
   if (typeof u.token === "string" && u.token.trim())
     return { act: false, reason: "token in prefs" };
+  // A registered token stays pinned to its login whatever this machine holds
+  // later, so an account verified once keeps naming the runs after it is logged
+  // out. A registration marked `registeredFallback` (20.17.0) was made with an
+  // account that cannot read the repository, so it is not pinned.
+  if (hasStoredToken && login === null && pinned(u)) {
+    return { act: false, reason: "token already onboarded" };
+  }
   if (login === null) {
-    return { act: false, reason: loginReason || "no logged-in GitHub account has access" };
+    return { act: false, reason: loginReason || "no GitHub account on this machine has access" };
+  }
+  if (hasStoredToken && login && u.registeredFallback === true) {
+    return { act: true, reason: `replacing a fallback registration with ${login}` };
   }
   // The server pins a token to the login it was issued for. A token issued to a
   // different login, or before the login was verified, reports under the wrong
@@ -150,56 +177,148 @@ export function registerUrlAllowed(url, trustedHosts = []) {
   return trusted.has(u.hostname.toLowerCase());
 }
 
-async function requestToken(url, body, proof) {
+async function postJson(url, body, bearer = null) {
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  const headers = { "Content-Type": "application/json" };
+  if (bearer) headers.Authorization = `Bearer ${bearer}`;
   try {
     const res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${proof}` },
+      headers,
       body: JSON.stringify(body),
       redirect: "error",
       signal: ctrl.signal,
     });
     const json = await res.json().catch(() => null);
-    if (!res.ok) {
-      const detail = typeof json?.error === "string" ? `: ${json.error.slice(0, 120)}` : "";
-      if (json?.code === "login_mismatch") {
-        return {
-          token: null,
-          why: `the gh token does not belong to ${body.u}; run \`gh auth status\` and retry with --refresh`,
-        };
-      }
-      if (res.status === 401) {
-        return {
-          token: null,
-          why:
-            `endpoint answered ${res.status}${detail} - GitHub did not accept the token for ${body.u}; ` +
-            `check \`gh auth status\` lists that account, then retry with --refresh`,
-        };
-      }
-      if (res.status === 403) {
-        return {
-          token: null,
-          why: `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository`,
-        };
-      }
-      return { token: null, why: `endpoint answered ${res.status}${detail}` };
-    }
-    if (json?.accepted === false)
-      return { token: null, declined: true, why: "the endpoint declined this login" };
-    const token = typeof json?.token === "string" ? json.token.trim() : "";
-    return token ? { token, why: null } : { token: null, why: "endpoint returned no token" };
+    return { res, json, failure: null };
   } catch (e) {
     return {
-      token: null,
-      why: e?.name === "AbortError" ? "endpoint timed out" : "endpoint unreachable",
+      res: null,
+      json: null,
+      failure: e?.name === "AbortError" ? "endpoint timed out" : "endpoint unreachable",
     };
   } finally {
     clearTimeout(timer);
   }
 }
 
+const SSH_REFUSALS = {
+  ssh_signature_invalid: (u) =>
+    `the server could not verify the SSH signature for ${u}; retry with --refresh`,
+  ssh_key_not_on_account: (u) =>
+    `the SSH key is not on ${u}'s GitHub account; add its .pub under GitHub Settings > SSH keys, then retry with --refresh`,
+  ssh_key_unsupported: (u) =>
+    `the server does not accept this SSH key type for ${u}; put an ed25519, rsa or ecdsa-p256 key on that account, then retry with --refresh`,
+};
+
+function refusal(status, json, body, method) {
+  const detail = typeof json?.error === "string" ? `: ${json.error.slice(0, 120)}` : "";
+  const code = typeof json?.code === "string" ? json.code : "";
+  if (SSH_REFUSALS[code]) return `endpoint answered ${status} - ${SSH_REFUSALS[code](body.u)}`;
+  if (code === "login_mismatch") {
+    return method === "gh"
+      ? `the gh token does not belong to ${body.u}; run \`gh auth status\` and retry with --refresh`
+      : `the proof does not belong to ${body.u}; retry with --refresh`;
+  }
+  if (status === 401) {
+    const fix =
+      method === "gh"
+        ? "check `gh auth status` lists that account, then retry with --refresh"
+        : "retry with --refresh";
+    return `endpoint answered ${status}${detail} - GitHub did not accept the proof for ${body.u}; ${fix}`;
+  }
+  if (status === 403) {
+    return (
+      `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository; ` +
+      "log in the account that has it (`gh auth login`, or add its SSH key), then rerun with --refresh"
+    );
+  }
+  return `endpoint answered ${status}${detail}`;
+}
+
+async function requestToken(url, body, proof, method) {
+  const { res, json, failure } = await postJson(url, body, proof);
+  if (failure) return { token: null, why: failure };
+  if (!res.ok) return { token: null, why: refusal(res.status, json, body, method) };
+  if (json?.accepted === false)
+    return { token: null, declined: true, why: "the endpoint declined this login" };
+  const token = typeof json?.token === "string" ? json.token.trim() : "";
+  const pinnedLogin = typeof json?.u === "string" && json.u.trim() ? json.u.trim() : null;
+  return token
+    ? { token, why: null, login: pinnedLogin }
+    : { token: null, why: "endpoint returned no token" };
+}
+
+/**
+ * Sign `challenge` with the SSH key at `key` under `namespace`. The exact
+ * challenge bytes go into a 0600 file in a fresh temp dir that is removed
+ * afterwards. stdin is closed and askpass is disabled, so a key that needs a
+ * passphrase fails at once; the `.pub` is then tried, which signs through
+ * ssh-agent when the key is loaded there. Returns the armored signature or null.
+ */
+export function sshSign(key, namespace, challenge, env = process.env) {
+  let dir = null;
+  try {
+    dir = mkdtempSync(join(tmpdir(), "ma-usage-sign-"));
+    const file = join(dir, "challenge");
+    writeFileSync(file, challenge, { mode: 0o600 });
+    const tries = key.endsWith(".pub") ? [key] : [key, `${key}.pub`];
+    for (const f of tries) {
+      if (!existsSync(f)) continue;
+      rmSync(`${file}.sig`, { force: true });
+      const r = spawnSync(sshKeygenBin(env), ["-Y", "sign", "-f", f, "-n", namespace, file], {
+        encoding: "utf8",
+        timeout: SSH_TIMEOUT_MS,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: { ...env, SSH_ASKPASS_REQUIRE: "never" },
+      });
+      if (r.status === 0 && existsSync(`${file}.sig`)) {
+        const sig = readFileSync(`${file}.sig`, "utf8");
+        if (sig.includes("BEGIN SSH SIGNATURE")) return sig;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The challenge URL next to the register URL. */
+export function challengeUrl(url) {
+  return `${url.replace(/\/+$/, "")}/challenge`;
+}
+
+async function requestTokenWithSsh(url, body, key) {
+  const ch = await postJson(challengeUrl(url), { u: body.u });
+  if (ch.failure) return { token: null, why: ch.failure };
+  if (!ch.res.ok) {
+    if (ch.res.status === 404 || ch.res.status === 405) {
+      return {
+        token: null,
+        why: `the endpoint does not accept an SSH key as proof yet (challenge answered ${ch.res.status})`,
+      };
+    }
+    return { token: null, why: refusal(ch.res.status, ch.json, body, "ssh") };
+  }
+  const challenge = typeof ch.json?.challenge === "string" ? ch.json.challenge : "";
+  const namespace = typeof ch.json?.namespace === "string" ? ch.json.namespace : "";
+  if (!challenge || !/^[A-Za-z0-9@._-]{1,128}$/.test(namespace)) {
+    return { token: null, why: "the endpoint returned no usable SSH challenge" };
+  }
+  const signature = sshSign(key, namespace, challenge);
+  if (!signature) {
+    const shown = displayPath(key);
+    return {
+      token: null,
+      why: `could not sign with the SSH key ${shown} (it needs a passphrase and is not in ssh-agent); run \`ssh-add ${shown}\`, then retry with --refresh`,
+    };
+  }
+  return requestToken(url, { ...body, ssh: { challenge, signature } }, null, "ssh");
+}
+
 /**
  * Write the switch, and the credential-store ENTRY NAME when there is one.
  *
@@ -227,7 +346,11 @@ export function persistPrefs(
         }
         j.global.usageLog = j.global.usageLog || {};
         if (enableTelemetry) j.global.usageLog.enabled = true;
-        if (registeredAs) j.global.usageLog.registeredAs = registeredAs;
+        if (registeredAs) {
+          j.global.usageLog.registeredAs = registeredAs;
+          delete j.global.usageLog.registeredFallback;
+          j.global.usageLog.registeredAt = new Date().toISOString();
+        }
         return j;
       },
       { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
@@ -238,6 +361,62 @@ export function persistPrefs(
   }
 }
 
+/**
+ * True when this machine's runs are not pinned to a verified account AND no
+ * GitHub account on it can read the pipeline repository (no gh account, no
+ * credential-helper token and no SSH key with access). `login` is the identity
+ * check's answer when it ran; otherwise the cached `usageLog.login` stands in.
+ * Setup and update read it from `--json` and offer the fix once.
+ */
+export function personalAccountMissing(prefs, login = undefined, env = process.env) {
+  const u = prefs?.global?.usageLog || {};
+  if (u.optOut === true) return false;
+  if (env.MULTI_AGENT_USAGE_TOKEN) return false;
+  if (typeof u.token === "string" && u.token.trim()) return false;
+  if (pinned(u)) return false;
+  const found =
+    login !== undefined
+      ? login
+      : u.loginFallback === true || typeof u.login !== "string"
+        ? null
+        : u.login;
+  return !found;
+}
+
+/**
+ * Report the installed version when it changed since the last report, detached.
+ * A first install happens before registration and an update runs this call
+ * right after installing, so both are reported from here.
+ */
+function sendInstalledVersion(prefsPath) {
+  try {
+    spawn(process.execPath, [join(import.meta.dirname, "usage-report.mjs"), "--lifecycle"], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, MULTI_AGENT_PREFS: prefsPath },
+    }).unref();
+  } catch {
+    // reporting never fails the caller
+  }
+}
+
+const QUIET_REASONS = new Set([
+  "opted out",
+  "token in environment",
+  "token in prefs",
+  "token already onboarded",
+  "no prefs",
+]);
+
+/**
+ * Whether an outcome leaves a machine silent for a reason its user can fix.
+ * `--quiet` callers discard stdout, so this is the one line they still see.
+ */
+function reportingStaysOff(status, detail) {
+  if (status === "unavailable" || status === "declined") return true;
+  return status === "skipped" && !QUIET_REASONS.has(detail);
+}
+
 async function main(argv) {
   const opts = {
     quiet: false,
@@ -263,8 +442,15 @@ async function main(argv) {
   const say = (line) => {
     if (!opts.quiet) process.stdout.write(`${line}\n`);
   };
+  const identity = { login: undefined };
   const done = (status, detail) => {
-    if (opts.json) process.stdout.write(`${JSON.stringify({ status, detail })}\n`);
+    if (opts.json) {
+      const needsPersonalAccount = personalAccountMissing(readJson(prefsPath), identity.login);
+      process.stdout.write(`${JSON.stringify({ status, detail, needsPersonalAccount })}\n`);
+    }
+    if (opts.quiet && reportingStaysOff(status, detail)) {
+      process.stderr.write(`multi-agent: usage reporting is off - ${detail}\n`);
+    }
     return 0;
   };
 
@@ -289,6 +475,7 @@ async function main(argv) {
   const who = identityMatters
     ? reportingUser(prefsPath, { refresh: opts.refresh })
     : { login: undefined, reason: null };
+  identity.login = who.login;
   const current = readJson(prefsPath) || prefs;
   const decision = decideRegistration(current, {
     hasStoredToken: has,
@@ -305,12 +492,19 @@ async function main(argv) {
         const name = current.global?.keychainMapping?.usage_ingest || null;
         if (persistPrefs(prefsPath, name)) {
           say("  -> operational reporting: enabled (a token was already onboarded)");
+          sendInstalledVersion(prefsPath);
           return done("enabled", decision.reason);
         }
         say("  -> operational reporting: could not write preferences");
         return done("unavailable", "prefs write failed");
       }
     }
+    if (
+      decision.reason === "token already onboarded" &&
+      current.global?.usageLog?.enabled === true
+    ) {
+      sendInstalledVersion(prefsPath);
+    }
     say(`  -> operational reporting: unchanged (${decision.reason})`);
     return done("skipped", decision.reason);
   }
@@ -336,14 +530,22 @@ async function main(argv) {
     return done("dry-run", url);
   }
 
-  const proof = ghTokenFor(user);
-  if (!proof) {
-    const why = `gh has no token for ${user}; run \`gh auth login\` for that account`;
-    say(`  -> operational reporting left off (${why})`);
-    return done("unavailable", why);
+  let result;
+  if (who.method === "ssh") {
+    result = await requestTokenWithSsh(url, { u: user, c: host }, who.key);
+  } else {
+    const proof = who.method === "credential" ? credentialToken() : ghTokenFor(user);
+    if (!proof) {
+      const why =
+        who.method === "credential"
+          ? `the git credential helper no longer returns a GitHub token for ${user}; retry with --refresh`
+          : `gh has no token for ${user}; run \`gh auth login\` for that account`;
+      say(`  -> operational reporting left off (${why})`);
+      return done("unavailable", why);
+    }
+    result = await requestToken(url, { u: user, c: host }, proof, who.method || "gh");
   }
-
-  const { token, why, declined } = await requestToken(url, { u: user, c: host }, proof);
+  const { token, why, declined, login: pinnedLogin } = result;
   if (declined) {
     say(`  -> operational reporting left off (${why})`);
     return done("declined", why);
@@ -364,7 +566,10 @@ async function main(argv) {
     say("  -> operational reporting left off (the credential store refused the token)");
     return done("unavailable", "credential store write failed");
   }
-  persistPrefs(prefsPath, entry, { enableTelemetry: !optedOut, registeredAs: user });
+  persistPrefs(prefsPath, entry, {
+    enableTelemetry: !optedOut,
+    registeredAs: pinnedLogin || user,
+  });
   if (optedOut) {
     say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");
     return done("registered-feedback-only", entry);
@@ -373,6 +578,7 @@ async function main(argv) {
     "  -> operational reporting: registered this machine (write-only token in the credential store)",
   );
   say("     opt out any time: set global.usageLog.optOut=true in multi-agent-preferences.json");
+  sendInstalledVersion(prefsPath);
   return done("registered", entry);
 }
 

package/pipeline/scripts/usage-report.mjs

@@ -2,8 +2,9 @@
  * usage-report.mjs  -  optional, opt-in per-run operational reporting.
  *
  * Off by default; a no-op unless prefs.global.usageLog.enabled is true, a
- * token resolves, and a logged-in GitHub account can read the pipeline
- * repository (usage-identity.mjs). Emits one compact run record keyed by run
+ * token resolves, and a GitHub account on this machine (gh, the git
+ * credential helper or an SSH key) can read the pipeline repository
+ * (usage-identity.mjs). Emits one compact run record keyed by run
  * id (`taskId`), upserted at every phase transition and at completion, halt
  * and park, fire-and-forget - never throws, never delays a run.
  * Only coarse run metadata is included; never prompts, code, diffs, token
@@ -22,6 +23,7 @@
  *   node usage-report.mjs --state /path/to/agent-state.json [--event <kind>]
  *   node usage-report.mjs --task-id PROJ-123 [--phase N] [--event <kind>]
  *
+ *   node usage-report.mjs --lifecycle   (report the installed version when it changed)
  *   --event  phase | completed | halted | parked  (default: derived from state)
  *
  * @module pipeline/scripts/usage-report
@@ -44,11 +46,13 @@ import { execFileSync } from "child_process";
 import { createHash } from "crypto";
 import { costUsd } from "./_cost.mjs";
 import { defaultPrefsPath, resolveReportingLogin } from "./usage-identity.mjs";
+import { installedVersion, lifecycleEvent } from "../lib/usage-lifecycle.mjs";
+import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
 import { KNOWN_STACKS, pluginsForStacks } from "./_stack-routing.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ENDPOINT_DEFAULT = "https://mmerterden.com/api/usage/ingest";
-const TIMEOUT_MS = 2500;
+const TIMEOUT_MS = 6000;
 
 // The emitter ships verbatim into ~/.claude, ~/.copilot and ~/.codex, so it must
 // never hard-code one host's tree: a Copilot- or Codex-only install has no
@@ -71,6 +75,7 @@ function parseArgs(argv) {
     status: null,
     event: null,
     dryRun: false,
+    lifecycle: false,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -80,6 +85,7 @@ function parseArgs(argv) {
     else if (a === "--status") out.status = argv[++i];
     else if (a === "--event") out.event = argv[++i];
     else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--lifecycle") out.lifecycle = true;
   }
   return out;
 }
@@ -659,9 +665,9 @@ function appendErrorLedger(event) {
   }
 }
 
-// Telemetry identity is the GitHub account that can read the pipeline
-// repository (usage-identity.mjs), never the git identity.name and never the
-// account gh merely has active. The server replaces it with the login pinned to
+// Telemetry identity is the GitHub account on this machine that can read the
+// pipeline repository (usage-identity.mjs), never the git identity.name and
+// never the account gh merely has active. The server replaces it with the login pinned to
 // the ingest token, so this value is informational.
 function resolveUser(opts = {}) {
   return resolveReportingLogin(opts).login;
@@ -806,6 +812,43 @@ function endpointAllowed(endpoint) {
   return false;
 }
 
+/**
+ * Send an install or update record when the installed version (from the
+ * installer's stamp) is not the last one reported, and move
+ * `usageLog.reportedVersion` forward once the server accepted it.
+ */
+async function reportInstalledVersion(endpoint, token, login, usageLog) {
+  const e = lifecycleEvent({ installed: installedVersion(homedir()), usageLog });
+  if (!e) return;
+  const r = await post(endpoint, token, { ...e, u: login, os: detectOs(), cli: detectCli() });
+  if (r.outcome !== "accepted") return;
+  try {
+    updateJsonFileSync(
+      defaultPrefsPath(),
+      (j) => {
+        if (!j || typeof j !== "object" || Array.isArray(j)) return undefined;
+        j.global = j.global || {};
+        j.global.usageLog = { ...(j.global.usageLog || {}), reportedVersion: e.v };
+        return j;
+      },
+      { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
+    );
+  } catch {
+    // the next send reports the same version again, under the same id
+  }
+}
+
+/**
+ * The login a registered token is pinned to. The server reports every record
+ * under it whatever the client sends, so a machine that registered once needs
+ * no gh call to name its runs, and keeps the name after that account logs out.
+ */
+function registeredLogin(prefs) {
+  if (prefs?.registeredFallback === true) return null;
+  const login = typeof prefs?.registeredAs === "string" ? prefs.registeredAs.trim() : "";
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$/.test(login) ? { login, reason: "registered" } : null;
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (process.env.MULTI_AGENT_SMOKE && !args.dryRun) return;
@@ -829,6 +872,13 @@ async function main() {
     return;
   }
 
+  if (args.lifecycle) {
+    if (args.dryRun) return;
+    const who = registeredLogin(prefs) ?? resolveReportingLogin();
+    if (who.login) await reportInstalledVersion(endpoint, token, who.login, prefs);
+    return;
+  }
+
   const statePath = resolveStatePath(args);
   let state = statePath ? readJson(statePath) : null;
 
@@ -844,7 +894,7 @@ async function main() {
   if (args.status) state.status = args.status;
   const kind = EVENT_KINDS.includes(args.event) ? args.event : null;
 
-  const who = resolveReportingLogin();
+  const who = registeredLogin(prefs) ?? resolveReportingLogin();
   if (!who.login) {
     process.stderr.write(`usage-report: not sent - ${who.reason}\n`);
     if (!args.dryRun) {
@@ -863,6 +913,8 @@ async function main() {
   if (event.st !== "in_progress") appendErrorLedger(event);
   const result = await post(endpoint, token, event);
   recordSend({ id: event.id, ev: event.ev, host: hostOf(endpoint), ...result });
+  if (result.outcome === "accepted")
+    await reportInstalledVersion(endpoint, token, who.login, prefs);
   if (result.outcome !== "accepted") {
     const detail = result.status ?? result.reason;
     const where = result.location ? ` to ${result.location}` : "";