@mmerterden/multi-agent-pipeline 20.22.0 → 20.23.0

package/pipeline/scripts/usage-register.mjs

@@ -18,10 +18,12 @@
  * - 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 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:
+ * - It registers the GitHub account on this machine that can read the
+ *   pipeline repository (usage-identity.mjs: gh, the git credential helper, or
+ *   an SSH key). With no such account it registers only a name the person
+ *   typed (`--login`, kept as `usageLog.declaredLogin`), as a declared claim
+ *   the server accepts for a collaborator and marks `claimed`. Otherwise 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
@@ -37,11 +39,14 @@
  *   is coarse metadata only.
  *
  * Usage:
- *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback] [--refresh]
+ *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback] [--refresh] [--login <name>]
  *
  * `--refresh` re-checks which GitHub account on this machine can read the
  * pipeline repository instead of using the cached `usageLog.login`.
  *
+ * `--login <name>` records the person's GitHub username, for a machine that
+ * proves no account (a work machine), and implies `--refresh`.
+ *
  * Exit: always 0. `--json` says what happened; the shell does not need to care.
  *
  * @module pipeline/scripts/usage-register
@@ -49,12 +54,14 @@
 
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 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 {
+  LOGIN_RE,
   SSH_TIMEOUT_MS,
   credentialToken,
   displayPath,
@@ -82,8 +89,11 @@ function readJson(file) {
  * 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 });
+export function reportingUser(
+  prefsPath,
+  { env = process.env, refresh = false, write = true } = {},
+) {
+  return resolveReportingLogin({ prefsPath, env, refresh, write });
 }
 
 /**
@@ -107,6 +117,7 @@ export function decideRegistration(
     forFeedback = false,
     login = undefined,
     loginReason = null,
+    proven = true,
   } = {},
 ) {
   const g = prefs?.global || {};
@@ -129,13 +140,21 @@ export function decideRegistration(
   if (login === null) {
     return { act: false, reason: loginReason || "no GitHub account on this machine has access" };
   }
+  if (hasStoredToken && login && proven && u.registeredClaim === true) {
+    return { act: true, reason: `replacing a declared registration with a proof for ${login}` };
+  }
   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
   // name, so it is replaced.
-  if (hasStoredToken && login && u.registeredAs && u.registeredAs !== login) {
+  if (
+    hasStoredToken &&
+    login &&
+    u.registeredAs &&
+    u.registeredAs.toLowerCase() !== login.toLowerCase()
+  ) {
     return { act: true, reason: `reporting account changed to ${login}` };
   }
   if (hasStoredToken && login && !u.registeredAs) {
@@ -228,6 +247,14 @@ function refusal(status, json, body, method) {
         : "retry with --refresh";
     return `endpoint answered ${status}${detail} - GitHub did not accept the proof for ${body.u}; ${fix}`;
   }
+  if (code === "proof_required") {
+    return `${body.u} is the repository owner, which registers with a proof: log in with \`gh auth login\` or add its SSH key, then retry with --refresh`;
+  }
+  if (code === "not_collaborator") {
+    const rerun =
+      method === "claim" ? "rerun setup and enter the name again" : "rerun with --refresh";
+    return `${body.u} is not a collaborator of the pipeline repository; the repository owner adds it, then ${rerun}`;
+  }
   if (status === 403) {
     return (
       `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository; ` +
@@ -240,7 +267,10 @@ function refusal(status, json, body, method) {
 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 (!res.ok) {
+    const code = typeof json?.code === "string" ? json.code : null;
+    return { token: null, code, 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() : "";
@@ -319,6 +349,94 @@ async function requestTokenWithSsh(url, body, key) {
   return requestToken(url, { ...body, ssh: { challenge, signature } }, null, "ssh");
 }
 
+/** The account name the person typed at setup or update, when it is a GitHub login. */
+export function declaredLoginOf(prefs) {
+  const d = prefs?.global?.usageLog?.declaredLogin;
+  return typeof d === "string" && LOGIN_RE.test(d.trim()) ? d.trim() : null;
+}
+
+/**
+ * Keep a typed account name and prefer it as the account to report under (the
+ * reportAs it replaces is kept as `usageLog.reportAsBefore`), or
+ * forget it (name null) once the server says it is not a collaborator, so the
+ * next setup asks again instead of retrying a name that cannot register.
+ */
+function declareLogin(prefsPath, name) {
+  try {
+    const written = updateJsonFileSync(
+      prefsPath,
+      (j) => {
+        if (!j || typeof j !== "object" || Array.isArray(j)) return undefined;
+        j.global = j.global || {};
+        const u = { ...(j.global.usageLog || {}) };
+        if (name) {
+          if (u.reportAs && u.reportAs !== u.declaredLogin && u.reportAsBefore === undefined)
+            u.reportAsBefore = u.reportAs;
+          Object.assign(u, { declaredLogin: name, reportAs: name });
+          delete u.claimFailedAt;
+        } else if (u.declaredLogin) {
+          if (u.reportAs === u.declaredLogin) {
+            if (u.reportAsBefore) u.reportAs = u.reportAsBefore;
+            else delete u.reportAs;
+          }
+          delete u.reportAsBefore;
+          delete u.declaredLogin;
+        }
+        j.global.usageLog = u;
+        return j;
+      },
+      { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
+    );
+    return written !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/** Merge `fields` into `usageLog` (undefined removes a key). True when written. */
+function patchUsageLog(prefsPath, fields) {
+  try {
+    const written = updateJsonFileSync(
+      prefsPath,
+      (j) => {
+        if (!j || typeof j !== "object" || Array.isArray(j)) return undefined;
+        j.global = j.global || {};
+        const u = { ...(j.global.usageLog || {}) };
+        for (const [k, v] of Object.entries(fields)) {
+          if (v === undefined) delete u[k];
+          else u[k] = v;
+        }
+        j.global.usageLog = u;
+        return j;
+      },
+      { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
+    );
+    return written !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A declared claim that failed (`usageLog.claimFailedAt`) is not sent again for
+ * a day unless the person types the name again.
+ */
+const CLAIM_RETRY_MS = 24 * 3600 * 1000;
+
+/**
+ * The machine label a declared registration is sent with: the host name and a
+ * random suffix kept in prefs (`usageLog.claimNonce`). The server replaces a login's token for the same
+ * label, so a label nobody else can guess keeps a stranger from replacing it.
+ */
+function claimLabel(prefsPath, usageLog, host) {
+  let nonce = usageLog?.claimNonce;
+  if (typeof nonce !== "string" || !/^[0-9a-f]{8,32}$/.test(nonce)) {
+    nonce = randomBytes(6).toString("hex");
+    patchUsageLog(prefsPath, { claimNonce: nonce });
+  }
+  return `${host.slice(0, 30)}-${nonce}`;
+}
+
 /**
  * Write the switch, and the credential-store ENTRY NAME when there is one.
  *
@@ -332,7 +450,7 @@ async function requestTokenWithSsh(url, body, key) {
 export function persistPrefs(
   prefsPath,
   entryName = null,
-  { enableTelemetry = true, registeredAs = null } = {},
+  { enableTelemetry = true, registeredAs = null, claimed = false } = {},
 ) {
   try {
     const written = updateJsonFileSync(
@@ -349,6 +467,8 @@ export function persistPrefs(
         if (registeredAs) {
           j.global.usageLog.registeredAs = registeredAs;
           delete j.global.usageLog.registeredFallback;
+          if (claimed) j.global.usageLog.registeredClaim = true;
+          else delete j.global.usageLog.registeredClaim;
           j.global.usageLog.registeredAt = new Date().toISOString();
         }
         return j;
@@ -371,6 +491,7 @@ export function persistPrefs(
 export function personalAccountMissing(prefs, login = undefined, env = process.env) {
   const u = prefs?.global?.usageLog || {};
   if (u.optOut === true) return false;
+  if (declaredLoginOf(prefs)) 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;
@@ -425,6 +546,7 @@ async function main(argv) {
     prefs: null,
     feedback: false,
     refresh: false,
+    login: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -434,6 +556,7 @@ async function main(argv) {
     else if (a === "--feedback") opts.feedback = true;
     else if (a === "--refresh") opts.refresh = true;
     else if (a === "--prefs") opts.prefs = argv[++i];
+    else if (a === "--login") opts.login = argv[++i] ?? "";
   }
   const HOME = homedir();
   const prefsPath = opts.prefs || join(HOME, ".claude", "multi-agent-preferences.json");
@@ -464,6 +587,26 @@ async function main(argv) {
     return done("skipped", "no prefs");
   }
 
+  // A name the person typed: kept as `declaredLogin` and preferred as the
+  // account to report under. A proof for it is still used when this machine
+  // has one; without one it is registered as declared (see below).
+  if (opts.login !== null) {
+    if (prefs.global?.usageLog?.optOut === true && !opts.feedback) {
+      say("  -> operational reporting: unchanged (opted out)");
+      return done("skipped", "opted out");
+    }
+    const name = String(opts.login).trim();
+    if (!LOGIN_RE.test(name)) {
+      say(`  -> operational reporting: "${name.slice(0, 40)}" is not a GitHub login`);
+      return done("skipped", `"${name.slice(0, 40)}" is not a GitHub login`);
+    }
+    if (!opts.dryRun && !declareLogin(prefsPath, name)) {
+      say("  -> operational reporting: could not write preferences");
+      return done("unavailable", "prefs write failed");
+    }
+    opts.refresh = true;
+  }
+
   // Decided before any credential is read: an opted-out machine, or one whose
   // token is already in the environment or prefs, never touches the credential
   // store or gh.
@@ -472,16 +615,26 @@ async function main(argv) {
     pre.reason,
   );
   const has = identityMatters ? Boolean(storedToken(prefs, credStore)) : false;
-  const who = identityMatters
-    ? reportingUser(prefsPath, { refresh: opts.refresh })
+  let who = identityMatters
+    ? reportingUser(prefsPath, { refresh: opts.refresh, write: !opts.dryRun })
     : { login: undefined, reason: null };
-  identity.login = who.login;
   const current = readJson(prefsPath) || prefs;
+  const declared =
+    opts.dryRun && opts.login !== null ? String(opts.login).trim() : declaredLoginOf(current);
+  // A typed name is used only when this machine proves no account at all; a
+  // proof, for that name or another, is evidence and a declaration is not.
+  const cu = current.global?.usageLog || {};
+  const provenPin = has && pinned(cu) && cu.registeredClaim !== true;
+  if (identityMatters && declared && !who.login && !provenPin && !opts.feedback) {
+    who = { login: declared, method: "claim", key: null, reason: "declared by the person" };
+  }
+  identity.login = who.login;
   const decision = decideRegistration(current, {
     hasStoredToken: has,
     forFeedback: opts.feedback,
     login: who.login,
     loginReason: who.reason,
+    proven: who.method !== "claim",
   });
   if (!decision.act) {
     const repairable = ["token in environment", "token in prefs", "token already onboarded"];
@@ -531,7 +684,15 @@ async function main(argv) {
   }
 
   let result;
-  if (who.method === "ssh") {
+  if (who.method === "claim") {
+    const failedAt = Date.parse(current.global?.usageLog?.claimFailedAt ?? "");
+    if (opts.login === null && !Number.isNaN(failedAt) && Date.now() - failedAt < CLAIM_RETRY_MS) {
+      say("  -> operational reporting: unchanged (the declared name was refused in the last day)");
+      return done("skipped", "declared registration refused recently");
+    }
+    const label = claimLabel(prefsPath, current.global?.usageLog, host);
+    result = await requestToken(url, { u: user, c: label, claim: true }, null, "claim");
+  } else if (who.method === "ssh") {
     result = await requestTokenWithSsh(url, { u: user, c: host }, who.key);
   } else {
     const proof = who.method === "credential" ? credentialToken() : ghTokenFor(user);
@@ -545,7 +706,11 @@ async function main(argv) {
     }
     result = await requestToken(url, { u: user, c: host }, proof, who.method || "gh");
   }
-  const { token, why, declined, login: pinnedLogin } = result;
+  const { token, why, declined, code, login: pinnedLogin } = result;
+  if (who.method === "claim" && ["not_collaborator", "proof_required"].includes(code))
+    declareLogin(prefsPath, null);
+  else if (who.method === "claim" && !token && !declined)
+    patchUsageLog(prefsPath, { claimFailedAt: new Date().toISOString() });
   if (declined) {
     say(`  -> operational reporting left off (${why})`);
     return done("declined", why);
@@ -569,6 +734,7 @@ async function main(argv) {
   persistPrefs(prefsPath, entry, {
     enableTelemetry: !optedOut,
     registeredAs: pinnedLogin || user,
+    claimed: who.method === "claim",
   });
   if (optedOut) {
     say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");

package/pipeline/scripts/validate-code-graph.mjs

@@ -17,7 +17,7 @@ import { readFileSync } from "node:fs";
 
 const ALLOWED_STACK = new Set(["ios", "android", "node", "python", "go"]);
 const ALLOWED_NODE_KIND = new Set(["file", "symbol", "module"]);
-const ALLOWED_EDGE_KIND = new Set(["defines", "imports", "references"]);
+const ALLOWED_EDGE_KIND = new Set(["defines", "imports", "references", "inherits"]);
 const MAX_REPORTED_DANGLING = 5;
 
 function readInput() {
@@ -137,8 +137,8 @@ export function validate(obj) {
   if (typeof obj !== "object" || obj === null || Array.isArray(obj))
     return ["root must be an object"];
 
-  if (!["1.0.0", "1.1.0"].includes(obj.schemaVersion))
-    errors.push(`schemaVersion must be "1.0.0" or "1.1.0"`);
+  if (!["1.0.0", "1.1.0", "1.2.0"].includes(obj.schemaVersion))
+    errors.push(`schemaVersion must be "1.0.0", "1.1.0" or "1.2.0"`);
   if (!ALLOWED_STACK.has(obj.stack))
     errors.push(`stack must be one of ${[...ALLOWED_STACK].join(",")}`);
   if (typeof obj.root !== "string" || obj.root.length === 0)

package/pipeline/scripts/valven-gate.mjs

@@ -837,7 +837,15 @@ function measureRework(repo, mergeBase, range, human, windowDays, now) {
     if (f.deleted === 0 || f.binary) continue;
     const old = f.oldPath ?? f.path;
     if (f.untracked) continue;
-    const diff = git(repo, ["diff", "-U0", "-M", ...range, "--", old, f.path]);
+    const diff = git(repo, [
+      "diff",
+      "-U0",
+      "-M",
+      ...range,
+      "--",
+      `:(literal)${old}`,
+      `:(literal)${f.path}`,
+    ]);
     for (const [start, count] of removedRanges(diff)) {
       const porcelain = git(repo, [
         "blame",

package/pipeline/scripts/valven-port.mjs

@@ -75,6 +75,7 @@ function fail(msg) {
 }
 
 const lines = (out) => out.split("\n").filter(Boolean);
+const paths = (out) => out.split("\0").filter(Boolean);
 
 async function main() {
   let args;
@@ -93,9 +94,11 @@ async function main() {
     const headSha = git(repo, ["rev-parse", head]).trim();
     const baseSha = git(repo, ["rev-parse", args.base]).trim();
     const branch = args.branch ?? git(repo, ["rev-parse", "--abbrev-ref", head]).trim();
-    const changed = lines(git(repo, ["diff", "--name-only", "-M", mergeBase, headSha]));
+    const changed = paths(git(repo, ["diff", "-z", "--name-only", "-M", mergeBase, headSha]));
     if (!changed.length) return fail(`no change between ${args.base} and ${head}`);
-    const baseTouched = new Set(lines(git(repo, ["diff", "--name-only", mergeBase, baseSha])));
+    const baseTouched = new Set(
+      paths(git(repo, ["diff", "-z", "--name-only", mergeBase, baseSha])),
+    );
     const exists = (name) => git(repo, ["branch", "--list", name]).trim() !== "";
     const to = args.to ?? nextName(branch, exists);
     const subject =
@@ -139,7 +142,7 @@ async function main() {
         encoding: "utf-8",
       });
       if (r.status !== 0) {
-        const unmerged = lines(git(repo, ["diff", "--name-only", "--diff-filter=U"]));
+        const unmerged = paths(git(repo, ["diff", "-z", "--name-only", "--diff-filter=U"]));
         plan.conflicts = unmerged.length ? unmerged : lines(r.stderr).slice(0, 20);
         git(repo, ["reset", "-q", "--hard"]);
         git(repo, ["checkout", "-q", back]);
@@ -149,8 +152,16 @@ async function main() {
         git(repo, ["commit", "-q", "-m", plan.subject]);
         plan.applied = true;
         plan.portedSha = git(repo, ["rev-parse", "HEAD"]).trim();
-        plan.differsFromHead = lines(
-          git(repo, ["diff", "--name-only", plan.head, "HEAD", "--", ...plan.changedPaths]),
+        plan.differsFromHead = paths(
+          git(repo, [
+            "diff",
+            "-z",
+            "--name-only",
+            plan.head,
+            "HEAD",
+            "--",
+            ...plan.changedPaths.map((p) => `:(literal)${p}`),
+          ]),
         );
         git(repo, ["checkout", "-q", back]);
       }

package/pipeline/scripts/valven-split.mjs

@@ -320,12 +320,14 @@ async function main() {
         git(repo, ["commit", "-q", "--allow-empty", "-m", plan.slices[i].subject]);
         parent = name;
       }
-      const drift = git(repo, ["diff", "--name-only", parent, headSha]).trim();
+      const drift = git(repo, ["diff", "-z", "--name-only", parent, headSha])
+        .split("\0")
+        .filter(Boolean);
       git(repo, ["checkout", "-q", original === "HEAD" ? headSha : original]);
       plan.applied = true;
-      plan.topMatchesBranch = drift === "";
-      if (drift) {
-        plan.drift = drift.split("\n");
+      plan.topMatchesBranch = drift.length === 0;
+      if (drift.length) {
+        plan.drift = drift;
         process.exitCode = 1;
       }
     } catch (err) {

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-12T21:38:23Z",
+  "generatedAt": "2026-10-13T08:10:09Z",
   "skillCount": 228,
   "entries": [
     {
@@ -213,7 +213,7 @@
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "79a4afa655df12221a25bc386a32e61c38016d2de660dd618b404ca8bb0b28d3"
+      "sha256": "73a1d1d8484d32b6d83107632a84aeced2f230f8581b7d47cad5e2d14e13860a"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
@@ -265,7 +265,7 @@
     },
     {
       "path": "shared/core/multi-agent-update/SKILL.md",
-      "sha256": "013317432263490a01d081b657928b977012afb78f75a64d278d94d2daa8e894"
+      "sha256": "2f9e224e240e1c9053a59066678f869ae36f18c088482488f3bda8fd207148ea"
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",

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

@@ -140,9 +140,9 @@ Then, **whether they pasted or skipped**, run:
 node "$HOME/.copilot/scripts/usage-register.mjs" --json
 ```
 
-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`).
+If its JSON line says `"needsPersonalAccount":true`, ask once for the person's
+GitHub username (free text; Skip leaves reporting off) and run
+`node "$HOME/.copilot/scripts/usage-register.mjs" --login <name> --json`.
 
 It maps whatever token exists and switches reporting on, and requests a
 per-machine write-only one when none resolves. Setup is a registration entry point

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

@@ -44,9 +44,9 @@ 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 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`).
+   If its JSON line says `"needsPersonalAccount":true`, ask once for the person's
+   GitHub username (free text; Skip leaves reporting off) and run
+   `node "$HOME/.copilot/scripts/usage-register.mjs" --login <name> --json`.
 6. Show the new version + changelog
 7. Smoke test (schema + cross-cli)