@mmerterden/multi-agent-pipeline 20.17.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 { 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,
   {
@@ -90,7 +107,6 @@ export function decideRegistration(
     forFeedback = false,
     login = undefined,
     loginReason = null,
-    fallback = false,
   } = {},
 ) {
   const g = prefs?.global || {};
@@ -103,14 +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" };
   }
-  // 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" };
+  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
@@ -157,61 +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; ` +
-            `add the account that has it with \`gh auth login\`, then rerun with --refresh`,
-        };
-      }
-      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() : "";
-    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" };
+    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.
  *
@@ -225,7 +332,7 @@ async function requestToken(url, body, proof) {
 export function persistPrefs(
   prefsPath,
   entryName = null,
-  { enableTelemetry = true, registeredAs = null, registeredFallback = false } = {},
+  { enableTelemetry = true, registeredAs = null } = {},
 ) {
   try {
     const written = updateJsonFileSync(
@@ -241,7 +348,7 @@ export function persistPrefs(
         if (enableTelemetry) j.global.usageLog.enabled = true;
         if (registeredAs) {
           j.global.usageLog.registeredAs = registeredAs;
-          j.global.usageLog.registeredFallback = registeredFallback === true;
+          delete j.global.usageLog.registeredFallback;
           j.global.usageLog.registeredAt = new Date().toISOString();
         }
         return j;
@@ -255,16 +362,25 @@ 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.
+ * 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) {
+export function personalAccountMissing(prefs, login = undefined, env = process.env) {
   const u = prefs?.global?.usageLog || {};
   if (u.optOut === true) return false;
-  if (process.env.MULTI_AGENT_USAGE_TOKEN) return false;
+  if (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);
+  if (pinned(u)) return false;
+  const found =
+    login !== undefined
+      ? login
+      : u.loginFallback === true || typeof u.login !== "string"
+        ? null
+        : u.login;
+  return !found;
 }
 
 /**
@@ -326,9 +442,10 @@ 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) {
-      const needsPersonalAccount = personalAccountMissing(readJson(prefsPath));
+      const needsPersonalAccount = personalAccountMissing(readJson(prefsPath), identity.login);
       process.stdout.write(`${JSON.stringify({ status, detail, needsPersonalAccount })}\n`);
     }
     if (opts.quiet && reportingStaysOff(status, detail)) {
@@ -358,13 +475,13 @@ 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,
     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"];
@@ -413,19 +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,
-    login: pinnedLogin,
-  } = 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);
@@ -449,7 +569,6 @@ async function main(argv) {
   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)");

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
@@ -664,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;
@@ -843,6 +844,7 @@ async function reportInstalledVersion(endpoint, token, login, usageLog) {
  * 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;
 }

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-07T15:02:16Z",
+  "generatedAt": "2026-10-07T19:19:02Z",
   "skillCount": 223,
   "entries": [
     {
@@ -213,7 +213,7 @@
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "28c00a0a32b5d636240ced308983b4aaee919016693a686a18ccb0e1e9103ec3"
+      "sha256": "427df811e5130da1ab6e23ff78202eb9134fb76bcd601924fba5668cbd630158"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
@@ -265,7 +265,7 @@
     },
     {
       "path": "shared/core/multi-agent-update/SKILL.md",
-      "sha256": "37f5950dca1a09b1ca0c2e2b1b2d20de418f6398a8aed37b062917cf6d95b4a5"
+      "sha256": "013317432263490a01d081b657928b977012afb78f75a64d278d94d2daa8e894"
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -136,8 +136,8 @@ Then, **whether they pasted or skipped**, run:
 node "$HOME/.copilot/scripts/usage-register.mjs" --json
 ```
 
-If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
-the person's own GitHub account once (the "Personal account" step in
+If its JSON line says `"needsPersonalAccount":true`, offer once: `gh auth login`,
+or an SSH key on the personal account (the "Personal account" step in
 `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
 
 It maps whatever token exists and switches reporting on, and requests a

package/pipeline/skills/shared/core/multi-agent-update/SKILL.md

@@ -44,8 +44,8 @@ Update the pipeline with a single command. Preferences are preserved; only skill
    already onboarded, and permanently blocked by `usageLog.optOut: true`. Offline
    or endpoint down leaves reporting off with one line, never an error. Contract:
    `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
-   If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
-   the person's own GitHub account once (the "Personal account" step in
+   If its JSON line says `"needsPersonalAccount":true`, offer once: `gh auth login`,
+   or an SSH key on the personal account (the "Personal account" step in
    `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
 6. Show the new version + changelog
 7. Smoke test (schema + cross-cli)