@mmerterden/multi-agent-pipeline 15.0.0 → 15.2.0

package/pipeline/scripts/usage-report.mjs

@@ -0,0 +1,457 @@
+/**
+ * usage-report.mjs  -  usage ping (opt-in) for the private mission-control dashboard.
+ *
+ * Emits one compact activity event keyed by run id (`taskId`). Called at each
+ * phase boundary (status=running, via phase-tracker.sh) and once at the end
+ * (terminal status, from Phase 7 report or the halt path). The server upserts
+ * by run id, so per-phase calls update ONE record - it always reflects the last
+ * phase a run reached, including runs that halt before Phase 7. Fire-and-forget,
+ * never throws, never delays the run.
+ *
+ * Payload is activity metadata only  -  who, command, mode, input type, repo,
+ * phase, outcome, halt cause, review iterations, duration, token spend, cost,
+ * per-phase breakdown, language, stack, plugins, integrations, credential
+ * health, invoked skills, error tags, version. No prompts, code, diffs, token
+ * values, or absolute paths.
+ *
+ * Enable + configure via prefs.global.usageLog:
+ *   { "enabled": true,
+ *     "endpoint": "https://mmerterden.vercel.app/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.
+ *
+ * Usage:
+ *   node usage-report.mjs --state /path/to/agent-state.json
+ *   node usage-report.mjs --task-id PROJ-123      # resolves the state path
+ *
+ * @module pipeline/scripts/usage-report
+ */
+
+import { readFileSync, existsSync, readdirSync, appendFileSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
+import { costUsd } from "./_cost.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ENDPOINT_DEFAULT = "https://mmerterden.vercel.app/api/usage/ingest";
+const TIMEOUT_MS = 2500;
+
+function parseArgs(argv) {
+  const out = { state: null, taskId: null, phase: null, status: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--state") out.state = argv[++i];
+    else if (a === "--task-id") out.taskId = argv[++i];
+    else if (a === "--phase") out.phase = argv[++i];
+    else if (a === "--status") out.status = argv[++i];
+    else if (a === "--dry-run") out.dryRun = true;
+  }
+  return out;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function resolveGlobalPrefs() {
+  const path =
+    process.env.MULTI_AGENT_PREFS ||
+    join(homedir(), ".claude", "multi-agent-preferences.json");
+  return readJson(path)?.global ?? {};
+}
+
+function resolvePrefs() {
+  return resolveGlobalPrefs().usageLog ?? {};
+}
+
+/**
+ * Resolve the ingest token without ever storing it in a synced file.
+ * Order: env, then prefs.usageLog.token, then the Keychain entry mapped by
+ * prefs.global.keychainMapping.usage_ingest (via credential-store.sh). This
+ * lets update flip usageLog.enabled on while the secret stays in the Keychain.
+ */
+function resolveToken() {
+  if (process.env.MULTI_AGENT_USAGE_TOKEN) return process.env.MULTI_AGENT_USAGE_TOKEN;
+  const g = resolveGlobalPrefs();
+  const inline = g.usageLog?.token;
+  if (typeof inline === "string" && inline.trim()) return inline.trim();
+  const name = g.keychainMapping?.usage_ingest;
+  if (typeof name === "string" && name.trim()) {
+    const store = join(homedir(), ".claude", "lib", "credential-store.sh");
+    if (existsSync(store)) {
+      try {
+        const out = execFileSync("bash", [store, "get", name.trim()], {
+          encoding: "utf-8",
+          timeout: 4000,
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (out) return out;
+      } catch {
+        /* keychain unavailable - stay silent */
+      }
+    }
+  }
+  return "";
+}
+
+function enabledPlugins(state) {
+  const root = state.projectRoot || process.cwd();
+  const settings = readJson(join(root, ".claude", "settings.json"));
+  const raw = settings?.enabledPlugins ?? settings?.plugins ?? [];
+  const list = Array.isArray(raw) ? raw : Object.keys(raw || {});
+  return list
+    .map((p) => (typeof p === "string" ? p.split("@")[0] : null))
+    .filter(Boolean)
+    .slice(0, 20);
+}
+
+function integrationTags(state) {
+  const apps = new Set();
+  if (state.jiraId) apps.add("jira");
+  if (state.remoteType) apps.add(String(state.remoteType).toLowerCase());
+  if (state.githubIssue) apps.add("github");
+  if (state.confluenceSpace) apps.add("confluence");
+  if (state.figmaAccess?.tier) apps.add("figma");
+  for (const call of state.telemetry?.mcpCalls ?? []) {
+    const tool = String(call?.tool || "");
+    const m = tool.match(/^mcp__([a-z0-9_]+?)__/i) || tool.match(/^mcp__([a-z0-9_]+)/i);
+    if (m) apps.add(m[1].replace(/_/g, "-").toLowerCase());
+  }
+  return Array.from(apps).slice(0, 20);
+}
+
+function credHealth() {
+  const g = resolveGlobalPrefs();
+  const mapping = g.keychainMapping ?? {};
+  const on = Object.entries(mapping)
+    .filter(([, v]) => typeof v === "string" && v.trim())
+    .map(([k]) => k)
+    .slice(0, 40);
+
+  const svc = {};
+  for (const [name, st] of Object.entries(g.serviceStatus ?? {})) {
+    const err = String(st?.error || "").toLowerCase();
+    const expired = /401|403|expired|unauthor|revoked|invalid.token/.test(err);
+    svc[name] = {
+      s: st?.ok ? "ok" : expired ? "expired" : "fail",
+      at: st?.checkedAt || null,
+    };
+  }
+  return { on, svc };
+}
+
+function invokedCalls(state) {
+  const names = new Set();
+  for (const c of state.telemetry?.skillCalls ?? []) {
+    if (c?.skill) names.add(String(c.skill));
+  }
+  return Array.from(names).slice(0, 30);
+}
+
+function detectOs() {
+  const p = platform();
+  if (p === "darwin") return "macos";
+  if (p === "win32") return "windows";
+  if (p === "linux") return "linux";
+  return p;
+}
+
+function detectCli() {
+  const e = process.env;
+  if (e.MULTI_AGENT_CLI) return String(e.MULTI_AGENT_CLI).toLowerCase();
+  if (e.CLAUDECODE || e.CLAUDE_CODE_ENTRYPOINT || e.ANTHROPIC_CLI) return "claude";
+  if (e.CODEX_HOME || e.CODEX_SANDBOX || e.CODEX_CLI) return "codex";
+  if (e.COPILOT_CLI || e.GITHUB_COPILOT_CLI || e.GH_COPILOT || e.COPILOT_AGENT_ID) {
+    return "copilot";
+  }
+  return null;
+}
+
+function deriveContext(state) {
+  return {
+    lang: resolveGlobalPrefs().outputLanguage ?? null,
+    os: detectOs(),
+    cli: detectCli(),
+    stack: Array.isArray(state.stacks)
+      ? state.stacks.slice(0, 10)
+      : state.stack
+        ? [String(state.stack)]
+        : [],
+    plug: enabledPlugins(state),
+    apps: integrationTags(state),
+    creds: credHealth(),
+    calls: invokedCalls(state),
+  };
+}
+
+function resolveStatePath({ state, taskId }) {
+  if (state) return state;
+  if (process.env.MULTI_AGENT_STATE_FILE && existsSync(process.env.MULTI_AGENT_STATE_FILE)) {
+    return process.env.MULTI_AGENT_STATE_FILE;
+  }
+  if (!taskId) return null;
+
+  const logRoot = join(homedir(), ".claude", "logs", "multi-agent");
+  const direct = [
+    join(logRoot, taskId, "agent-state.json"),
+    join(process.cwd(), ".worktrees", taskId, "agent-state.json"),
+    join(process.cwd(), "agent-state.json"),
+  ];
+  const hit = direct.find((p) => existsSync(p));
+  if (hit) return hit;
+
+  try {
+    for (const project of readdirSync(logRoot)) {
+      const p = join(logRoot, project, taskId, "agent-state.json");
+      if (existsSync(p)) return p;
+    }
+  } catch {
+    /* logs dir missing */
+  }
+  return null;
+}
+
+function packageVersion() {
+  const candidates = [
+    join(__dirname, "..", "..", "package.json"),
+    join(homedir(), ".claude", "multi-agent-pipeline", "package.json"),
+  ];
+  for (const p of candidates) {
+    const v = readJson(p)?.version;
+    if (v) return v;
+  }
+  return null;
+}
+
+function inputType(state) {
+  if (state.jiraId) return "jira";
+  if (state.githubIssue) return "github-issue";
+  return "free-text";
+}
+
+function commandOf(state) {
+  if (state.mode) return state.mode;
+  if (state.onlyDevelop) return "dev";
+  if (state.localMode) return "local";
+  return "full";
+}
+
+function resolveTracker(state) {
+  const id = state.taskId || state.shortId;
+  if (id == null) return null;
+  const root = join(homedir(), ".claude", "logs", "multi-agent");
+  const candidates = [
+    join(root, String(id), "tracker-state.json"),
+    state.artifactsPath ? join(state.artifactsPath, "tracker-state.json") : null,
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+function phaseDurationSec(p) {
+  if (Number.isFinite(Number(p?.duration_ms))) {
+    return Math.round(Number(p.duration_ms) / 1000);
+  }
+  const s = p?.startedAt || p?.started_at || p?.start;
+  const f = p?.finishedAt || p?.finished_at || p?.completed_at || p?.end;
+  const sm = s ? Date.parse(s) : NaN;
+  const fm = f ? Date.parse(f) : NaN;
+  if (Number.isNaN(sm) || Number.isNaN(fm) || fm < sm) return null;
+  return Math.round((fm - sm) / 1000);
+}
+
+function trackerSummary(state) {
+  const path = resolveTracker(state);
+  if (!path) return { tk: null, cost: null, phs: null, failed: [], models: [] };
+  const tracker = readJson(path);
+  if (!tracker?.phases) return { tk: null, cost: null, phs: null, failed: [], models: [] };
+
+  let tin = 0;
+  let tout = 0;
+  let tcache = 0;
+  const phs = [];
+  const failed = [];
+  const models = new Set();
+  for (const [id, p] of Object.entries(tracker.phases)) {
+    if (p?.status === "failed") failed.push(id);
+    if (p?.model) models.add(String(p.model));
+    const pin = Number(p?.tokens_in || 0);
+    const pout = Number(p?.tokens_out || 0);
+    const pcache = Number(p?.tokens_cached || 0);
+    tin += pin;
+    tout += pout;
+    tcache += pcache;
+    phs.push({
+      p: Number.isNaN(Number(id)) ? id : Number(id),
+      st: p?.status || null,
+      du: phaseDurationSec(p),
+      tk: pin + pout + pcache || null,
+    });
+  }
+  phs.sort((a, b) => Number(a.p) - Number(b.p));
+
+  const total = tin + tout + tcache;
+  const table = readJson(join(__dirname, "cost-table.json"));
+  const rate = table?.prices?.opus;
+  const cost =
+    total > 0 && rate ? Number(costUsd(rate, tin, tout, tcache).toFixed(4)) : null;
+  return {
+    tk: total || null,
+    cost,
+    phs: phs.length ? phs : null,
+    failed,
+    models: Array.from(models).slice(0, 10),
+  };
+}
+
+function deriveErrors(state, failedPhases) {
+  const errs = new Set();
+  if (state.haltReason) errs.add(String(state.haltReason));
+  for (const id of failedPhases ?? []) errs.add(`phase-${id}-failed`);
+  const s = String(state.status || "").toLowerCase();
+  if (s === "failed") errs.add("run-failed");
+  return Array.from(errs).slice(0, 20);
+}
+
+function durationSec(state) {
+  const s = state.startedAt ? Date.parse(state.startedAt) : NaN;
+  const f = state.finishedAt ? Date.parse(state.finishedAt) : NaN;
+  if (Number.isNaN(s) || Number.isNaN(f) || f < s) return null;
+  return Math.round((f - s) / 1000);
+}
+
+function runId(state) {
+  const base = state.taskId ?? state.shortId;
+  return base == null ? null : String(base);
+}
+
+function eventTimestamp(state) {
+  return state.finishedAt || state.updatedAt || new Date().toISOString();
+}
+
+const TERMINAL_STATUSES = ["complete", "completed", "failed", "paused", "halted", "error"];
+
+function isTerminalStatus(state) {
+  if (state.haltReason) return true;
+  return TERMINAL_STATUSES.includes(String(state.status || "").toLowerCase());
+}
+
+function appendErrorLedger(event) {
+  if (!event.errs || event.errs.length === 0) return;
+  const path = join(homedir(), ".claude", "logs", "multi-agent", "errors-ledger.jsonl");
+  const row = {
+    t: event.t,
+    id: event.id,
+    u: event.u,
+    c: event.c,
+    rp: event.rp,
+    ph: event.ph,
+    v: event.v,
+    errs: event.errs,
+  };
+  try {
+    appendFileSync(path, JSON.stringify(row) + "\n");
+  } catch {
+    /* logs dir missing or unwritable - never break the run */
+  }
+}
+
+function buildEvent(state) {
+  const spend = trackerSummary(state);
+  const ctx = deriveContext(state);
+  return {
+    id: runId(state),
+    t: eventTimestamp(state),
+    u: state.identity?.username || null,
+    c: commandOf(state),
+    m: state.mode || null,
+    ap: Boolean(state.autopilot),
+    lo: Boolean(state.localMode),
+    dev: Boolean(state.onlyDevelop),
+    in: inputType(state),
+    rp: state.project || null,
+    ph: typeof state.currentPhase === "number" ? state.currentPhase : null,
+    st: state.status || null,
+    hr: state.haltReason || null,
+    ri: Array.isArray(state.reviewIterations)
+      ? state.reviewIterations.length
+      : 0,
+    pr: Boolean(state.pr && (state.pr.url || state.pr.number)),
+    du: durationSec(state),
+    tk: spend.tk,
+    cost: spend.cost,
+    phs: spend.phs,
+    os: ctx.os,
+    cli: ctx.cli,
+    models: spend.models,
+    lang: ctx.lang,
+    stack: ctx.stack,
+    plug: ctx.plug,
+    apps: ctx.apps,
+    creds: ctx.creds,
+    calls: ctx.calls,
+    errs: deriveErrors(state, spend.failed),
+    v: packageVersion(),
+  };
+}
+
+async function post(endpoint, token, event) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Usage-Token": token,
+      },
+      body: JSON.stringify(event),
+      signal: ctrl.signal,
+    });
+  } catch {
+    /* never break the run on a telemetry failure */
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const prefs = resolvePrefs();
+  const token = resolveToken();
+  const endpoint = prefs.endpoint || ENDPOINT_DEFAULT;
+
+  if (!args.dryRun && (prefs.enabled !== true || !token)) return;
+
+  const statePath = resolveStatePath(args);
+  let state = statePath ? readJson(statePath) : null;
+
+  if (!state) {
+    if (!args.taskId) return;
+    state = { taskId: args.taskId };
+  }
+
+  if (args.phase != null) {
+    const n = Number(args.phase);
+    state.currentPhase = Number.isNaN(n) ? args.phase : n;
+  }
+  if (args.status) state.status = args.status;
+
+  const event = buildEvent(state);
+
+  if (args.dryRun) {
+    process.stdout.write(JSON.stringify(event, null, 2) + "\n");
+    return;
+  }
+
+  if (isTerminalStatus(state)) appendErrorLedger(event);
+  await post(endpoint, token, event);
+}
+
+main().catch(() => process.exit(0));

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -14,9 +14,13 @@
 //     complaint_count, graylog_degraded); language in {tr, en}.
 //   - Required sections present by bilingual title keyword: Summary, Triage,
 //     Complaint Details, Open Questions, Methodology, References.
-//   - Every triage-table row (a table row carrying a C-NN id) has a valid
-//     verdict token: client:<layer> | bff:<layer> | core | insufficient-evidence.
+//   - Every triage-table row (a row in the Triage section whose FIRST cell is
+//     a C-NN id) has a valid verdict token in a cell of its own:
+//     client:<layer> | bff:<layer> | core | insufficient-evidence.
 //     Verdict tokens stay English in both languages (payload vocabulary).
+//     Scoping matters: the Section 1 coverage table cites C-NN ids in its
+//     "Verdicts attributed" column and must not be read as triage rows, and a
+//     summary cell mentioning "core" must not classify the row as core.
 //   - Every core verdict has a matching entry in the routing section
 //     (Yönlendirme / Routing), and that section exists when any core row does.
 //   - Every client/bff verdict has a fix-plan marker (Fix plan / Geliştirme
@@ -24,7 +28,9 @@
 //   - Humanizer punctuation policy: no em-dash / en-dash / ellipsis /
 //     section-sign / curly quotes anywhere.
 //   - Redaction leak scan: an email address or a 13-19 digit card-like run is
-//     an ERROR; a bare 11-digit run is a WARN (could be a numeric trx id).
+//     an ERROR; a bare 11-digit run is a WARN (could be a numeric trx id); a
+//     PNR-shaped token (6-char uppercase letter+digit mix, or 6 uppercase
+//     letters right after a "PNR" keyword) is a WARN.
 //
 // Usage:
 //   node validate-complaint-doc.mjs complaints/complaints-20260810.md
@@ -49,8 +55,10 @@ const REQUIRED_SECTIONS = [
 const ROUTING_KEYWORDS = ["Routing", "Yönlendirme", "Yonlendirme"];
 const FIX_PLAN_RE = /(Fix plan|Fix Plan|Geliştirme planı|Geliştirme Planı|Gelistirme plani|Gelistirme Plani)/;
 
-const VERDICT_RE =
-  /\b(client:(ios|android|web)|bff:(mobile-bff|web-bff)|core|insufficient-evidence)\b/;
+// Cell-exact on purpose: a substring match would classify a row as `core`
+// because its summary says "core-data" or "core team" before the verdict column.
+const VERDICT_CELL_RE =
+  /^(client:(ios|android|web)|bff:(mobile-bff|web-bff)|core|insufficient-evidence)$/;
 
 const BANNED_PUNCT = [
   { ch: "—", name: "em-dash" },
@@ -66,6 +74,12 @@ const BANNED_PUNCT = [
 const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
 const CARD_RE = /\b\d(?:[ -]?\d){12,18}\b/;
 const NATIONAL_ID_RE = /\b\d{11}\b/;
+// Same shape parse-complaints.sh redacts (6-char uppercase alnum with at least
+// one letter AND one digit), so a leak the parser should have caught fails
+// loudly here too. All-letter PNRs are only flaggable with context: a bare
+// 6-letter word is far too common, so those warn only right after "PNR".
+const PNR_MIXED_RE = /\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*\d)(?=\d*[A-Z])[A-Z0-9]{6}\b/;
+const PNR_CONTEXT_RE = /\bPNR\b[^A-Za-z0-9\n]{0,3}[A-Z]{6}\b/;
 
 function readInput() {
   const args = process.argv.slice(2).filter((a) => a !== "--strict");
@@ -144,21 +158,25 @@ function main() {
     }
   }
 
-  // 3. Triage rows: every table row carrying a complaint id needs a verdict.
-  const rows = text.split("\n").filter((l) => /^\s*\|.*\bC-\d{2,}\b/.test(l));
+  // 3. Triage rows: scoped to the Triage section (the Section 1 coverage table
+  // also cites C-NN ids, in its "Verdicts attributed" column), and a triage row
+  // carries the id in its FIRST cell. Every such row needs a verdict cell.
+  const triageScope = sectionBody(text, ["Triage"]) ?? text;
+  const rows = triageScope.split("\n").filter((l) => /^\s*\|\s*C-\d{2,}\s*\|/.test(l));
   if (rows.length === 0) {
-    errors.push("no triage rows found (expected table rows carrying C-NN complaint ids)");
+    errors.push("no triage rows found (expected Triage-section rows with a C-NN id in the first cell)");
   }
   const coreIds = [];
   const handoffIds = [];
   for (const row of rows) {
     const id = (row.match(/\bC-\d{2,}\b/) || [])[0];
-    const verdict = row.match(VERDICT_RE);
+    const cells = row.split("|").map((c) => c.trim());
+    const verdict = cells.find((c) => VERDICT_CELL_RE.test(c));
     if (!verdict) {
       errors.push(`triage row ${id} has no valid verdict token (client:<layer> | bff:<layer> | core | insufficient-evidence)`);
-    } else if (verdict[0] === "core" && !coreIds.includes(id)) {
+    } else if (verdict === "core" && !coreIds.includes(id)) {
       coreIds.push(id);
-    } else if (/^(client|bff):/.test(verdict[0]) && !handoffIds.includes(id)) {
+    } else if (/^(client|bff):/.test(verdict) && !handoffIds.includes(id)) {
       handoffIds.push(id);
     }
   }
@@ -207,6 +225,9 @@ function main() {
     if (NATIONAL_ID_RE.test(bodyLines[i]) && !CARD_RE.test(bodyLines[i])) {
       warns.push(`possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`);
     }
+    if (PNR_MIXED_RE.test(bodyLines[i]) || PNR_CONTEXT_RE.test(bodyLines[i])) {
+      warns.push(`possible redaction leak: PNR-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`);
+    }
   }
 
   // Report

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-08-13T11:39:06Z",
+  "generatedAt": "2026-08-14T19:54:00Z",
   "skillCount": 205,
   "entries": [
     {
@@ -125,7 +125,7 @@
     },
     {
       "path": "shared/core/multi-agent-refactor/SKILL.md",
-      "sha256": "0aee8c68a617ff38e4535f37e90c1b2f94bb3e69e11d59f9b7f6fbfa28aadaf3"
+      "sha256": "1924dd999d8d99fbfc68dac132c26e9c9d47c9c6e0330db4821f724eb7f2408c"
     },
     {
       "path": "shared/core/multi-agent-resume-local/SKILL.md",
@@ -169,7 +169,7 @@
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
-      "sha256": "45ea71a5b1cc6f37713dd7b780b4f5f6e4c4a5fdb5bf90083dc8be83cce7663b"
+      "sha256": "f49fb2fcf0a5a1f3f044a4393ec625208d48ef4b685ea0370d74c4ac18f1afe7"
     },
     {
       "path": "shared/core/multi-agent-status/SKILL.md",
@@ -213,7 +213,7 @@
     },
     {
       "path": "shared/core/multi-agent-update/SKILL.md",
-      "sha256": "154afad4824b29423e378554c689c61b8c5cc4cd8f6ca07377e32471547fdbc2"
+      "sha256": "66d960a9c360ba0353b6496fde641c1a99834274bc0ac68932ed107b15411ccb"
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",