@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.0

package/pipeline/scripts/uninstall.mjs

@@ -81,11 +81,15 @@ export const PIPELINE_AGENT_FILES = [
  * Non-multi-agent core skills the installer ships from
  * pipeline/skills/shared/core/ (the multi-agent* dirs are matched by prefix).
  */
-export const PIPELINE_CORE_SKILL_DIRS = [
-  "apple-archive-compliance",
-  "google-play-compliance",
-  "valven-rules",
-];
+export const PIPELINE_CORE_SKILL_DIRS = ["apple-archive-compliance", "google-play-compliance"];
+
+/**
+ * Skills an older install placed in the skills dir that now reach the host from
+ * a marketplace plugin (Claude Code) or the external catalog (Copilot, Codex).
+ * An install upgraded since then has already pruned them; one that was not
+ * still carries the old copy, so uninstall removes these names too.
+ */
+export const PIPELINE_RETIRED_SKILL_DIRS = ["valven-rules"];
 
 /**
  * Files the installer ships into ~/.claude/templates (install/templates/).
@@ -323,7 +327,7 @@ function rmManifestFiles(hostDir, keepInLib) {
  * @param {string} path
  */
 function rmIfExists(path) {
-  if (!existsSync(path)) return false;
+  if (!existsSync(path) && !isSymlink(path)) return false;
   if (dryRun) {
     report("would remove", path);
     return false;
@@ -538,6 +542,15 @@ function rmExternalDeliveredSkills(skillsDir) {
   return n;
 }
 
+/** True for a symlink, dangling or not; existsSync follows the link and misses a dangling one. */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 function rmMatchingDirs(parent, predicate) {
   if (!existsSync(parent)) return 0;
   let count = 0;
@@ -879,7 +892,11 @@ export async function main() {
         name === "figma-common" ||
         name === "figma-to-component",
     );
-    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
+    n += rmMatchingDirs(
+      skills,
+      (name) =>
+        PIPELINE_CORE_SKILL_DIRS.includes(name) || PIPELINE_RETIRED_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"));
@@ -914,7 +931,11 @@ export async function main() {
         name === "figma-common" ||
         name === "figma-to-component",
     );
-    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
+    n += rmMatchingDirs(
+      skills,
+      (name) =>
+        PIPELINE_CORE_SKILL_DIRS.includes(name) || PIPELINE_RETIRED_SKILL_DIRS.includes(name),
+    );
     n += rmPluginDeliveredSkills(skills);
     n += rmExternalDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);

package/pipeline/scripts/usage-identity.mjs

@@ -16,9 +16,16 @@
  * account's token in the child's environment (GH_TOKEN), never on argv and
  * never written anywhere. The first account that can read the repository wins.
  *
+ * When none can, the active account (else the first) is used as a fallback and
+ * marked so (`fallback: true`, `usageLog.loginFallback`). A work machine often
+ * has only an enterprise-managed account logged in, which can never be a
+ * collaborator of a personal repository; the server decides whether it accepts
+ * that login, and refuses it with a status line when it does not. A fallback is
+ * cached for NO_LOGIN_TTL_MS, so an account with access added later takes over.
+ *
  * The result is cached in prefs as `usageLog.login` + `usageLog.loginCheckedAt`
  * (and `usageLog.loginRepo`; `usageLog.loginReason` says why none qualified), re-checked after LOGIN_TTL_MS, or after
- * NO_LOGIN_TTL_MS when no account had access, or on `--refresh`.
+ * NO_LOGIN_TTL_MS when no account had access or the login is a fallback, or on `--refresh`.
  *
  * Usage:
  *   node usage-identity.mjs [--refresh] [--prefs <path>] [--json]
@@ -158,7 +165,8 @@ function orderCandidates(accounts, preferred) {
 
 /**
  * Check each logged-in account against the access repository, live.
- * Returns { login, reason } where login is null when no account has access.
+ * Returns { login, fallback, reason }: the first account with access, else the
+ * active (or first) account with `fallback: true`, else login null.
  */
 export function checkAccess({
   repo = ACCESS_REPO_DEFAULT,
@@ -169,16 +177,22 @@ export function checkAccess({
   if (accounts.length === 0) {
     return {
       login: null,
+      fallback: false,
       reason: `no GitHub account is logged in to gh, so ${repo} cannot be checked`,
     };
   }
-  for (const a of orderCandidates(accounts, preferred)) {
+  const ordered = orderCandidates(accounts, preferred);
+  for (const a of ordered) {
     const token = tokenFor(a.login, env);
-    if (token && canRead(repo, token, env)) return { login: a.login, reason: `can read ${repo}` };
+    if (token && canRead(repo, token, env)) {
+      return { login: a.login, fallback: false, reason: `can read ${repo}` };
+    }
   }
+  const fallback = accounts.find((a) => a.active) || accounts[0];
   return {
-    login: null,
-    reason: `none of the logged-in GitHub accounts (${accounts.map((a) => a.login).join(", ")}) can read ${repo}`,
+    login: fallback.login,
+    fallback: true,
+    reason: `none of the logged-in GitHub accounts (${accounts.map((a) => a.login).join(", ")}) can read ${repo}; the server decides whether it accepts ${fallback.login}`,
   };
 }
 
@@ -186,7 +200,7 @@ function cacheFresh(u, repo, now) {
   const at = Date.parse(u?.loginCheckedAt || "");
   if (Number.isNaN(at)) return false;
   if ((u.loginRepo || ACCESS_REPO_DEFAULT) !== repo) return false;
-  const ttl = u.login ? LOGIN_TTL_MS : NO_LOGIN_TTL_MS;
+  const ttl = u.login && u.loginFallback !== true ? LOGIN_TTL_MS : NO_LOGIN_TTL_MS;
   return now - at < ttl && now >= at;
 }
 
@@ -224,10 +238,19 @@ export function resolveReportingLogin({
   const repo = accessRepoOf(prefs);
   if (!refresh && cacheFresh(u, repo, now)) {
     if (typeof u.login === "string" && LOGIN_RE.test(u.login)) {
-      return { login: u.login, reason: `cached: can read ${repo}`, cached: true };
+      if (u.loginFallback === true) {
+        return {
+          login: u.login,
+          fallback: true,
+          reason: u.loginReason || `cached: no logged-in GitHub account can read ${repo}`,
+          cached: true,
+        };
+      }
+      return { login: u.login, fallback: false, reason: `cached: can read ${repo}`, cached: true };
     }
     return {
       login: null,
+      fallback: false,
       reason: u.loginReason || `cached: no logged-in GitHub account can read ${repo}`,
       cached: true,
     };
@@ -239,9 +262,10 @@ export function resolveReportingLogin({
       prefsPath,
       {
         login: result.login,
+        loginFallback: result.fallback,
         loginRepo: repo,
         loginCheckedAt: new Date(now).toISOString(),
-        loginReason: result.login ? null : result.reason,
+        loginReason: result.login && !result.fallback ? null : result.reason,
       },
       env,
     );
@@ -263,8 +287,10 @@ function main(argv) {
   });
   if (opts.json) {
     process.stdout.write(
-      `${JSON.stringify({ login: r.login, reason: r.reason, cached: r.cached })}\n`,
+      `${JSON.stringify({ login: r.login, fallback: r.fallback, reason: r.reason, cached: r.cached })}\n`,
     );
+  } else if (r.login && r.fallback) {
+    process.stdout.write(`usage identity: ${r.login} (fallback - ${r.reason})\n`);
   } else if (r.login) {
     process.stdout.write(`usage identity: ${r.login} (${r.reason})\n`);
   } else {

package/pipeline/scripts/usage-register.mjs

@@ -44,7 +44,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { homedir, hostname } from "node:os";
 import { pathToFileURL } from "node:url";
@@ -90,6 +90,7 @@ export function decideRegistration(
     forFeedback = false,
     login = undefined,
     loginReason = null,
+    fallback = false,
   } = {},
 ) {
   const g = prefs?.global || {};
@@ -105,6 +106,12 @@ export function decideRegistration(
   if (login === null) {
     return { act: false, reason: loginReason || "no logged-in GitHub account has access" };
   }
+  // A registered token stays pinned to its login whatever gh holds later: a
+  // fallback account never replaces it, so a personal account verified once
+  // keeps naming the runs after it is logged out.
+  if (hasStoredToken && fallback && u.registeredAs) {
+    return { act: false, reason: "token already onboarded" };
+  }
   // 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
   // name, so it is replaced.
@@ -181,7 +188,9 @@ async function requestToken(url, body, proof) {
       if (res.status === 403) {
         return {
           token: null,
-          why: `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository`,
+          why:
+            `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository; ` +
+            `add the account that has it with \`gh auth login\`, then rerun with --refresh`,
         };
       }
       return { token: null, why: `endpoint answered ${res.status}${detail}` };
@@ -189,7 +198,10 @@ async function requestToken(url, body, proof) {
     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" };
+    const pinned = typeof json?.u === "string" && json.u.trim() ? json.u.trim() : null;
+    return token
+      ? { token, why: null, login: pinned }
+      : { token: null, why: "endpoint returned no token" };
   } catch (e) {
     return {
       token: null,
@@ -213,7 +225,7 @@ async function requestToken(url, body, proof) {
 export function persistPrefs(
   prefsPath,
   entryName = null,
-  { enableTelemetry = true, registeredAs = null } = {},
+  { enableTelemetry = true, registeredAs = null, registeredFallback = false } = {},
 ) {
   try {
     const written = updateJsonFileSync(
@@ -227,7 +239,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;
+          j.global.usageLog.registeredFallback = registeredFallback === true;
+          j.global.usageLog.registeredAt = new Date().toISOString();
+        }
         return j;
       },
       { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
@@ -238,6 +254,53 @@ export function persistPrefs(
   }
 }
 
+/**
+ * True while this machine's runs are not pinned to an account that can read the
+ * pipeline repository: no registration, or one made with a fallback account.
+ * Setup and update read it from `--json` and offer to add that account once.
+ */
+export function personalAccountMissing(prefs) {
+  const u = prefs?.global?.usageLog || {};
+  if (u.optOut === true) return false;
+  if (process.env.MULTI_AGENT_USAGE_TOKEN) return false;
+  if (typeof u.token === "string" && u.token.trim()) return false;
+  return !(typeof u.registeredAs === "string" && u.registeredAs && u.registeredFallback !== true);
+}
+
+/**
+ * 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,
@@ -264,7 +327,13 @@ async function main(argv) {
     if (!opts.quiet) process.stdout.write(`${line}\n`);
   };
   const done = (status, detail) => {
-    if (opts.json) process.stdout.write(`${JSON.stringify({ status, detail })}\n`);
+    if (opts.json) {
+      const needsPersonalAccount = personalAccountMissing(readJson(prefsPath));
+      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;
   };
 
@@ -295,6 +364,7 @@ async function main(argv) {
     forFeedback: opts.feedback,
     login: who.login,
     loginReason: who.reason,
+    fallback: who.fallback === true,
   });
   if (!decision.act) {
     const repairable = ["token in environment", "token in prefs", "token already onboarded"];
@@ -305,12 +375,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);
   }
@@ -343,7 +420,12 @@ async function main(argv) {
     return done("unavailable", why);
   }
 
-  const { token, why, declined } = await requestToken(url, { u: user, c: host }, proof);
+  const {
+    token,
+    why,
+    declined,
+    login: pinnedLogin,
+  } = await requestToken(url, { u: user, c: host }, proof);
   if (declined) {
     say(`  -> operational reporting left off (${why})`);
     return done("declined", why);
@@ -364,7 +446,11 @@ 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,
+    registeredFallback: who.fallback === true,
+  });
   if (optedOut) {
     say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");
     return done("registered-feedback-only", entry);
@@ -373,6 +459,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

@@ -22,6 +22,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 +45,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 +74,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 +84,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;
 }
@@ -806,6 +811,42 @@ 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) {
+  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 +870,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 +892,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 +911,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}` : "";