@mmerterden/multi-agent-pipeline 17.5.0 → 17.6.0

package/pipeline/scripts/usage-register.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * usage-register.mjs  -  ask the reporting endpoint for this machine's token.
+ *
+ * WHY THIS EXISTS
+ *
+ * Operational reporting needs two things to work: `usageLog.enabled` true AND a
+ * token that resolves. Since v15.8.0 both are arranged automatically - but only
+ * inside `/multi-agent:update`, as forty lines of shell embedded in a skill. A
+ * new user installs the package, runs `/multi-agent:setup` (which explicitly
+ * says registration happens in update), works for weeks, and never registers.
+ * Their runs emit nothing, and the panel cannot tell that apart from nobody
+ * using the pipeline at all - which is exactly what it looked like.
+ *
+ * So the registration becomes one deterministic call that three places make:
+ * setup (onboarding), update (existing path), and the first run of a machine
+ * that reached neither.
+ *
+ * WHAT IT NEVER DOES
+ *
+ * - It never ships a secret: the token is REQUESTED, and it is write-only.
+ * - It never writes the token to a file. The credential store holds it; prefs
+ *   hold only the name of the entry.
+ * - It never registers when `usageLog.optOut` is true. That is permanent and
+ *   checked before anything else.
+ * - 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
+ *   is coarse metadata only.
+ *
+ * Usage:
+ *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback]
+ *
+ * Exit: always 0. `--json` says what happened; the shell does not need to care.
+ *
+ * @module pipeline/scripts/usage-register
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir, hostname, userInfo } from "node:os";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_ENDPOINT = "https://mmerterden.com/api/usage/ingest";
+const TIMEOUT_MS = 10000;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** The name this machine reports under: the GitHub login, never the git identity. */
+export function reportingUser(prefs, { env = process.env } = {}) {
+  const declared = prefs?.global?.identities?.[0]?.username;
+  if (typeof declared === "string" && declared.trim()) return declared.trim();
+  try {
+    const out = execFileSync("gh", ["api", "user", "--jq", ".login"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (out) return out;
+  } catch {
+    /* gh is optional */
+  }
+  try {
+    return env.USER || userInfo().username || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Should this machine register at all?
+ *
+ * The three "no" answers are deliberately distinguishable: the caller prints
+ * them, and "you opted out" and "we could not reach the endpoint" are different
+ * facts about the same silence.
+ */
+export function decideRegistration(
+  prefs,
+  { env = process.env, hasStoredToken = false, forFeedback = false } = {},
+) {
+  const g = prefs?.global || {};
+  const u = g.usageLog || {};
+  // `optOut` is a choice about PASSIVE collection. /multi-agent:feedback is the
+  // opposite: somebody typed a message meant to be read, and it rides the same
+  // token. So a feedback run may mint one - and it must NOT switch telemetry on
+  // when it does, which is what `enableTelemetry` below is for.
+  if (u.optOut === true && !forFeedback) return { act: false, reason: "opted out" };
+  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" };
+  if (hasStoredToken) return { act: false, reason: "token already onboarded" };
+  return { act: true, reason: "no token resolves" };
+}
+
+/** The /register URL derived from whatever endpoint the prefs name. */
+export function registerUrl(endpoint) {
+  const ep = (endpoint || DEFAULT_ENDPOINT).trim().replace(/\/+$/, "");
+  return ep.endsWith("/ingest") ? `${ep.slice(0, -"/ingest".length)}/register` : `${ep}/register`;
+}
+
+function storedToken(prefs, credStore) {
+  const name = prefs?.global?.keychainMapping?.usage_ingest;
+  if (!name || !existsSync(credStore)) return null;
+  const r = spawnSync("bash", [credStore, "get", name], { encoding: "utf8", timeout: 8000 });
+  const out = (r.stdout || "").trim();
+  return out || null;
+}
+
+async function requestToken(url, body) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    if (!res.ok) return { token: null, why: `endpoint answered ${res.status}` };
+    const json = await res.json().catch(() => null);
+    const token = typeof json?.token === "string" ? json.token.trim() : "";
+    return token ? { token, why: null } : { token: null, why: "endpoint returned no token" };
+  } catch (e) {
+    return {
+      token: null,
+      why: e?.name === "AbortError" ? "endpoint timed out" : "endpoint unreachable",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Write the switch, and the credential-store ENTRY NAME when there is one.
+ *
+ * `entryName` is optional on purpose: a token can resolve from the environment
+ * or from `usageLog.token`, and those machines still need the switch flipped.
+ * Claiming "enabled" while writing nothing is the failure this whole feature is
+ * about, one level smaller.
+ *
+ * The token itself is never written here, whatever the caller passes.
+ */
+export function persistPrefs(prefsPath, entryName = null, { enableTelemetry = true } = {}) {
+  const j = readJson(prefsPath);
+  if (!j) return false;
+  j.global = j.global || {};
+  if (entryName) {
+    j.global.keychainMapping = j.global.keychainMapping || {};
+    j.global.keychainMapping.usage_ingest = entryName;
+  }
+  j.global.usageLog = j.global.usageLog || {};
+  if (enableTelemetry) j.global.usageLog.enabled = true;
+  writeFileSync(prefsPath, `${JSON.stringify(j, null, 2)}\n`);
+  return true;
+}
+
+async function main(argv) {
+  const opts = { quiet: false, json: false, dryRun: false, prefs: null, feedback: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--quiet") opts.quiet = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--feedback") opts.feedback = true;
+    else if (a === "--prefs") opts.prefs = argv[++i];
+  }
+  const HOME = homedir();
+  const prefsPath = opts.prefs || join(HOME, ".claude", "multi-agent-preferences.json");
+  const credStore = join(HOME, ".claude", "lib", "credential-store.sh");
+
+  const say = (line) => {
+    if (!opts.quiet) process.stdout.write(`${line}\n`);
+  };
+  const done = (status, detail) => {
+    if (opts.json) process.stdout.write(`${JSON.stringify({ status, detail })}\n`);
+    return 0;
+  };
+
+  const prefs = readJson(prefsPath);
+  if (!prefs) {
+    // Setup writes this file; nothing here creates it. An installer that seeds
+    // state is the one thing the install contract forbids.
+    say("  -> operational reporting: no preferences file yet (run /multi-agent:setup)");
+    return done("skipped", "no prefs");
+  }
+
+  const has = Boolean(storedToken(prefs, credStore));
+  const decision = decideRegistration(prefs, { hasStoredToken: has, forFeedback: opts.feedback });
+  if (!decision.act) {
+    if (decision.reason !== "opted out") {
+      // Already has a token: make sure the switch is actually on. A token with
+      // enabled:false is the other half of the same silence.
+      if (prefs.global?.usageLog?.enabled !== true && !opts.dryRun) {
+        const name = prefs.global?.keychainMapping?.usage_ingest || null;
+        if (persistPrefs(prefsPath, name)) {
+          say("  -> operational reporting: enabled (a token was already onboarded)");
+          return done("enabled", decision.reason);
+        }
+        say("  -> operational reporting: could not write preferences");
+        return done("unavailable", "prefs write failed");
+      }
+    }
+    say(`  -> operational reporting: unchanged (${decision.reason})`);
+    return done("skipped", decision.reason);
+  }
+
+  const url = registerUrl(prefs.global?.usageLog?.endpoint);
+  const user = reportingUser(prefs);
+  let host = "unknown";
+  try {
+    host = hostname().split(".")[0] || "unknown";
+  } catch {
+    /* a nameless host is still a host */
+  }
+
+  if (opts.dryRun) {
+    say(`  -> operational reporting: would register ${user} with ${url}`);
+    return done("dry-run", url);
+  }
+
+  const { token, why } = await requestToken(url, { u: user, c: host });
+  if (!token) {
+    say(`  -> operational reporting left off (${why})`);
+    return done("unavailable", why);
+  }
+
+  const optedOut = prefs.global?.usageLog?.optOut === true;
+  const entry = `${process.env.USER || user}_Usage_Ingest_Token`;
+  const set = spawnSync("bash", [credStore, "set", entry], {
+    input: token,
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (set.status !== 0) {
+    say("  -> operational reporting left off (the credential store refused the token)");
+    return done("unavailable", "credential store write failed");
+  }
+  persistPrefs(prefsPath, entry, { enableTelemetry: !optedOut });
+  if (optedOut) {
+    say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");
+    return done("registered-feedback-only", entry);
+  }
+  say(
+    "  -> 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");
+  return done("registered", entry);
+}
+
+function isEntrypoint() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return import.meta.url === pathToFileURL(arg).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/pipeline/scripts/usage-report.mjs

@@ -9,7 +9,7 @@
  *
  * Enable + configure via prefs.global.usageLog:
  *   { "enabled": true,
- *     "endpoint": "https://mmerterden.vercel.app/api/usage/ingest",
+ *     "endpoint": "https://mmerterden.com/api/usage/ingest",
  *     "token": "<shared ingest token>" }         // token may instead come from
  *                                                 // env MULTI_AGENT_USAGE_TOKEN
  * Nothing is sent when enabled is not true or no token resolves.
@@ -30,7 +30,7 @@ import { createHash } from "crypto";
 import { costUsd } from "./_cost.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ENDPOINT_DEFAULT = "https://mmerterden.vercel.app/api/usage/ingest";
+const ENDPOINT_DEFAULT = "https://mmerterden.com/api/usage/ingest";
 const TIMEOUT_MS = 2500;
 
 // The emitter ships verbatim into ~/.claude, ~/.copilot and ~/.codex, so it must

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-15T12:49:28Z",
+  "generatedAt": "2026-09-15T20:06:53Z",
   "skillCount": 212,
   "entries": [
     {
@@ -93,11 +93,11 @@
     },
     {
       "path": "shared/core/multi-agent-issue/SKILL.md",
-      "sha256": "aec8737af368b01c7e3133521c711861456c18b07e3829425e5c0485a0181051"
+      "sha256": "8f8918c8a0f5d6431892e65737c685bb47a62379d023ac7c760a8a605d3eb0a4"
     },
     {
       "path": "shared/core/multi-agent-jira/SKILL.md",
-      "sha256": "0bd2046752f106f2a5f2974eab61a9618263153230bfbd9b0e59024fc5bff0a0"
+      "sha256": "1ceb984239217060ab9fa3e7964270f9c6245bef0a3cac429bc329548d91e617"
     },
     {
       "path": "shared/core/multi-agent-kill/SKILL.md",
@@ -181,7 +181,7 @@
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "40dc72793cd6bd1054d6203275fbc9f4ecdd6d8dc5de8f2437e7f670f4c5c646"
+      "sha256": "d475f14de5db9ffe0c8ae5b3b83374d5f82a41c29da5271c7399d151e6bd4c1d"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
@@ -233,7 +233,7 @@
     },
     {
       "path": "shared/core/multi-agent-update/SKILL.md",
-      "sha256": "e93e913473cb5d3a5810b30f26011a0d18754bed983890f4261b87972526d94a"
+      "sha256": "8a0b089ea5c0d81813dc936d8b9d012f956e6381f71e025ca8878e538a8e9303"
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",

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

@@ -34,3 +34,17 @@ Interactively list unassigned GitHub issues, let the user pick one, and send it
    - If the user passed the `autopilot` flag, start in autopilot mode
 
 6. **gh auth restore**  -  return to `{owner}` once done
+
+## Maturity: the picked item may not be ready
+
+The pipeline scores the item before anything is built. A blocker does not end the
+run any more: an interactive run asks at that step (open the item and fix it,
+continue without it - recording which gap was waved through - or abort), and an
+autopilot run with `prefs.global.maturityFollowup.autopilotCommentsOnIssue` on
+posts ONE comment on the item asking for what is missing, then stops and waits for
+`resume`. Never a status change, never an assignee, never a close; `Ref:`, never a
+closing keyword. Read the item's existing comments first and take the prior ask
+from the newest one of ours - a scan is a new run with a fresh state file, so
+state alone would make every scan a first ask. Full contract:
+`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`.
+

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

@@ -36,3 +36,17 @@ Interactively list the user's open Jira issues, let the user pick one, and send
 5. **Start the pipeline**  -  run the `/multi-agent` command:
    - Input: `"PROJ-{id}" "branch-name"`
    - If the `autopilot` flag is present, in autopilot mode
+
+## Maturity: the picked item may not be ready
+
+The pipeline scores the item before anything is built. A blocker does not end the
+run any more: an interactive run asks at that step (open the item and fix it,
+continue without it - recording which gap was waved through - or abort), and an
+autopilot run with `prefs.global.maturityFollowup.autopilotCommentsOnIssue` on
+posts ONE comment on the item asking for what is missing, then stops and waits for
+`resume`. Never a status change, never an assignee, never a close; `Ref:`, never a
+closing keyword. Read the item's existing comments first and take the prior ask
+from the newest one of ours - a scan is a new run with a fresh state file, so
+state alone would make every scan a first ask. Full contract:
+`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`.
+

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

@@ -141,6 +141,19 @@ Save the resolved mapping to preferences:
 
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
+### Step 2.7  -  Operational reporting
+
+```bash
+node "$HOME/.claude/scripts/usage-register.mjs"
+```
+
+Requests a per-machine **write-only** token when none resolves, stores it in the
+credential store only, and switches reporting on. Registration used to happen
+only in update, so a machine that ran setup and nothing else never reported at
+all. `usageLog.optOut: true` blocks it permanently; an unreachable endpoint
+leaves reporting off with one line. Contract:
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
+
 ### Step 3  -  Jira Project Key (auto-learned)
 
 Jira project keys are NOT asked during setup. They are auto-learned from pipeline usage:

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

@@ -37,6 +37,12 @@ Update the pipeline with a single command. Preferences are preserved; only skill
 4b. Refresh the stack-plugin marketplace so the latest plugin versions are picked up:
    `claude marketplace update multi-agent-plugins` (or `claude marketplace add {owner}/multi-agent-plugins` if not yet added)
 5. `node migrate-prefs.mjs` (if there is a schema upgrade)
+5b. `node "$HOME/.claude/scripts/usage-register.mjs"` - operational reporting.
+   It requests a per-machine **write-only** token when none resolves, stores it in
+   the credential store only, and switches reporting on. A no-op when a token is
+   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`.
 6. Show the new version + changelog
 7. Smoke test (schema + cross-cli)