@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/cost-analyze.mjs

@@ -61,11 +61,79 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { costUsd } from "./_cost.mjs";
 import { runMain } from "../lib/fatal.mjs";
+import { messages, outputLanguage } from "../lib/user-facing.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const STORE = process.env.COST_SNAPSHOT_STORE || join(homedir(), ".claude", "state", "cost");
 const TRANSCRIPT_ROOT = process.env.COST_TRANSCRIPT_ROOT || join(homedir(), ".claude", "projects");
 
+// The report is read by whoever ran it, so it renders in
+// `prefs.global.outputLanguage`. Both languages sit on one key so a wording
+// change cannot land on only one of them, and `--json` is untouched: that half
+// is parsed, not read.
+const REPORT = {
+  en: {
+    rate: (days, total, observedDays, perDay) =>
+      `last ${days} days: ${total} (${observedDays} days carry records) - ${perDay} a day`,
+    horizon: (d7, d30, d90) => `  7 days ${d7} - 30 days ${d30} - 90 days ${d90}`,
+    noCeiling:
+      "  no exhaustion date: --monthly-usd was not given and this machine declares no monthly ceiling",
+    noSpend: "  nothing spent, so there is nothing to exhaust",
+    exhausts: (ceiling, days) =>
+      `  the ${ceiling} monthly ceiling runs out in ${days} days at this rate`,
+    unpriced: (n, models) =>
+      `  ${n} records could not be priced (${models}) - they are outside the total`,
+    noModelField: "no model field",
+    listPrice: "  (estimated at list price, not what a subscription paid)",
+    family: (n, by, median, basis, threshold) =>
+      `${n} ${by} - median ${median} - scale ${basis} - threshold z>=${threshold}`,
+    inFamily: "  nothing out of family",
+    moreFlagged: (n, by) => `  ... and ${n} more ${by} above the threshold`,
+    burn: (day, spend, priorDays, priorPerDay) =>
+      `${day}: ${spend} - the preceding ${priorDays} days averaged ${priorPerDay} a day`,
+    noPrior: "  nothing spent in the preceding window, so there is no ratio",
+    ratio: (ratio, past, factor) =>
+      `  ${ratio}x ${past ? `- past the ${factor}x threshold` : "- within the normal range"}`,
+    saved: (path, days, total, perDay) =>
+      `saved: ${path}\n  last ${days} days ${total} - ${perDay} a day`,
+    empty: "  (empty)",
+    snapshot: (at, total, days) => `  ${at}  ${total} / ${days} days`,
+    perDayDiff: (from, to, delta) => `  a day ${from} -> ${to}  (${delta})`,
+    windowsDiffer: (a, b) =>
+      `  ! different windows (${a} / ${b} days) - the daily rate compares, the total does not`,
+  },
+  tr: {
+    rate: (days, total, observedDays, perDay) =>
+      `son ${days} gun: ${total} (${observedDays} gunde kayit var) - gunluk ${perDay}`,
+    horizon: (d7, d30, d90) => `  7 gun ${d7} - 30 gun ${d30} - 90 gun ${d90}`,
+    noCeiling:
+      "  butce tukenme tarihi yok: --monthly-usd verilmedi, bu makinede aylik tavan tanimli degil",
+    noSpend: "  harcama yok, tukenme hesaplanamaz",
+    exhausts: (ceiling, days) => `  ${ceiling} aylik tavan bu hizda ${days} gunde biter`,
+    unpriced: (n, models) => `  ${n} kayit fiyatlanamadi (${models}) - toplamin disinda`,
+    noModelField: "model alani yok",
+    listPrice: "  (liste fiyatindan tahmin, abonelikte odenen tutar degil)",
+    family: (n, by, median, basis, threshold) =>
+      `${n} ${by} - medyan ${median} - olcek ${basis} - esik z>=${threshold}`,
+    inFamily: "  aile disinda kayit yok",
+    moreFlagged: (n, by) => `  ... ve ${n} ${by} daha esigin uzerinde`,
+    burn: (day, spend, priorDays, priorPerDay) =>
+      `${day}: ${spend} - onceki ${priorDays} gun gunluk ortalama ${priorPerDay}`,
+    noPrior: "  onceki pencerede harcama yok, oran hesaplanamaz",
+    ratio: (ratio, past, factor) =>
+      `  ${ratio}x ${past ? `- esik ${factor}x asildi` : "- normal aralik"}`,
+    saved: (path, days, total, perDay) =>
+      `kaydedildi: ${path}\n  son ${days} gun ${total} - gunluk ${perDay}`,
+    empty: "  (bos)",
+    snapshot: (at, total, days) => `  ${at}  ${total} / ${days} gun`,
+    perDayDiff: (from, to, delta) => `  gunluk ${from} -> ${to}  (${delta})`,
+    windowsDiffer: (a, b) =>
+      `  ! pencereler farkli (${a} / ${b} gun) - gunluk oran karsilastirilabilir, toplam degil`,
+  },
+};
+
+const say = messages(REPORT, outputLanguage());
+
 function die(msg) {
   process.stderr.write(`cost-analyze: ${msg}\n`);
   process.exit(2);
@@ -336,27 +404,21 @@ async function cmdProjection(json) {
     );
   } else {
     process.stdout.write(
-      `son ${days} gun: ${usd(total)} (${observedDays} gunde kayit var) - gunluk ${usd(perDay)}\n` +
-        `  7 gun ${usd(proj[7])} - 30 gun ${usd(proj[30])} - 90 gun ${usd(proj[90])}\n`,
+      `${say.rate(days, usd(total), observedDays, usd(perDay))}\n` +
+        `${say.horizon(usd(proj[7]), usd(proj[30]), usd(proj[90]))}\n`,
     );
-    if (monthly === null)
-      process.stdout.write(
-        "  butce tukenme tarihi yok: --monthly-usd verilmedi, bu makinede aylik tavan tanimli degil\n",
-      );
-    else if (exhaustDays === null) process.stdout.write("  harcama yok, tukenme hesaplanamaz\n");
-    else
-      process.stdout.write(
-        `  ${usd(monthly)} aylik tavan bu hizda ${exhaustDays.toFixed(1)} gunde biter\n`,
-      );
+    if (monthly === null) process.stdout.write(`${say.noCeiling}\n`);
+    else if (exhaustDays === null) process.stdout.write(`${say.noSpend}\n`);
+    else process.stdout.write(`${say.exhausts(usd(monthly), exhaustDays.toFixed(1))}\n`);
     if (s.unpriced)
       process.stdout.write(
-        `  ${s.unpriced} kayit fiyatlanamadi (${s.unpricedModels.join(", ") || "model alani yok"}) - toplamin disinda\n`,
+        `${say.unpriced(s.unpriced, s.unpricedModels.join(", ") || say.noModelField)}\n`,
       );
     // Said every time, not in a footnote somebody reads once: on a subscription
     // this figure is what the same tokens would have COST at list price, not
     // what was paid. It is the right number for comparing days to each other
     // and the wrong number to put in an invoice.
-    process.stdout.write("  (liste fiyatindan tahmin - abonelikte odenen tutar degil)\n");
+    process.stdout.write(`${say.listPrice}\n`);
   }
   if (finding) process.exitCode = 10;
 }
@@ -407,18 +469,15 @@ async function cmdAnomaly(json) {
       )}\n`,
     );
   } else {
-    process.stdout.write(
-      `${rows.length} ${by} - medyan ${usd(med)} - olcek ${basis} - esik z>=${threshold}\n`,
-    );
-    if (!flagged.length) process.stdout.write("  aile disinda kayit yok\n");
+    process.stdout.write(`${say.family(rows.length, by, usd(med), basis, threshold)}\n`);
+    if (!flagged.length) process.stdout.write(`${say.inFamily}\n`);
     // Ten lines, then a count. Session spend is heavy-tailed - the median
     // session is a few cents of question-answering and a real run is three
     // orders of magnitude above it - so `--by session` legitimately flags
     // dozens, and forty lines of flags is a list nobody finishes reading.
     for (const r of flagged.slice(0, 10))
       process.stdout.write(`  ! ${r.key}  ${usd(r.usd)}  z=${r.z.toFixed(1)}\n`);
-    if (flagged.length > 10)
-      process.stdout.write(`  ... ve ${flagged.length - 10} ${by} daha esigin uzerinde\n`);
+    if (flagged.length > 10) process.stdout.write(`${say.moreFlagged(flagged.length - 10, by)}\n`);
   }
   if (flagged.length) process.exitCode = 10;
 }
@@ -467,13 +526,10 @@ async function cmdBurn(json) {
     );
   } else {
     process.stdout.write(
-      `${today[0]}: ${usd(today[1])} - onceki ${priorRows.length} gun gunluk ortalama ${usd(priorPerDay)}\n`,
+      `${say.burn(today[0], usd(today[1]), priorRows.length, usd(priorPerDay))}\n`,
     );
-    if (ratio === null) process.stdout.write("  onceki pencerede harcama yok, oran hesaplanamaz\n");
-    else
-      process.stdout.write(
-        `  ${ratio.toFixed(1)}x ${finding ? `- esik ${factor}x asildi` : "- normal aralik"}\n`,
-      );
+    if (ratio === null) process.stdout.write(`${say.noPrior}\n`);
+    else process.stdout.write(`${say.ratio(ratio.toFixed(1), finding, factor)}\n`);
   }
   if (finding) process.exitCode = 10;
 }
@@ -506,10 +562,7 @@ async function cmdSave(json) {
   const path = join(STORE, `${snap.savedAt.replace(/[:.]/g, "-")}.json`);
   writeFileSync(path, `${JSON.stringify(snap, null, 2)}\n`);
   if (json) process.stdout.write(`${JSON.stringify({ saved: path, ...snap }, null, 2)}\n`);
-  else
-    process.stdout.write(
-      `kaydedildi: ${path}\n  son ${days} gun ${usd(snap.totalUsd)} - gunluk ${usd(snap.perDayUsd)}\n`,
-    );
+  else process.stdout.write(`${say.saved(path, days, usd(snap.totalUsd), usd(snap.perDayUsd))}\n`);
 }
 
 function cmdList(json) {
@@ -518,10 +571,10 @@ function cmdList(json) {
     process.stdout.write(`${JSON.stringify({ store: STORE, snapshots: files }, null, 2)}\n`);
   else {
     process.stdout.write(`${STORE}\n`);
-    if (!files.length) process.stdout.write("  (bos)\n");
+    if (!files.length) process.stdout.write(`${say.empty}\n`);
     for (const f of files) {
       const d = JSON.parse(readFileSync(f, "utf-8"));
-      process.stdout.write(`  ${d.savedAt}  ${usd(d.totalUsd)} / ${d.windowDays} gun\n`);
+      process.stdout.write(`${say.snapshot(d.savedAt, usd(d.totalUsd), d.windowDays)}\n`);
     }
   }
 }
@@ -563,15 +616,12 @@ function cmdDiff(json) {
     );
   } else {
     process.stdout.write(`${A.savedAt} -> ${B.savedAt}\n`);
-    process.stdout.write(
-      `  gunluk ${usd(A.perDayUsd)} -> ${usd(B.perDayUsd)}  (${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${
-        pct === null ? "" : `, ${pct >= 0 ? "+" : ""}${pct.toFixed(0)}%`
-      })\n`,
-    );
+    const shift = `${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${
+      pct === null ? "" : `, ${pct >= 0 ? "+" : ""}${pct.toFixed(0)}%`
+    }`;
+    process.stdout.write(`${say.perDayDiff(usd(A.perDayUsd), usd(B.perDayUsd), shift)}\n`);
     if (A.windowDays !== B.windowDays)
-      process.stdout.write(
-        `  ! pencereler farkli (${A.windowDays} / ${B.windowDays} gun) - gunluk oran karsilastirilabilir, toplam degil\n`,
-      );
+      process.stdout.write(`${say.windowsDiffer(A.windowDays, B.windowDays)}\n`);
   }
 }
 

package/pipeline/scripts/diff-explain.mjs

@@ -79,6 +79,17 @@ function resolveStateByTaskId(id) {
   return found;
 }
 
+// Phase 3 Step 3 persists triage per review round, so the newest round that
+// has finished triage is the one the diff reflects. A round still in progress
+// carries no triage yet and is skipped.
+function latestIterationTriage(state) {
+  const rounds = Array.isArray(state?.reviewIterations) ? state.reviewIterations : [];
+  for (let i = rounds.length - 1; i >= 0; i--) {
+    if (rounds[i]?.triage) return rounds[i].triage;
+  }
+  return null;
+}
+
 function loadTriage() {
   if (flags.triage) {
     if (!existsSync(flags.triage)) die(`triage file not found: ${flags.triage}`);
@@ -89,7 +100,7 @@ function loadTriage() {
   if (statePath) {
     if (!existsSync(statePath)) die(`state file not found: ${statePath}`);
     const state = JSON.parse(readFileSync(statePath, "utf-8"));
-    const triage = state?.phases?.["4"]?.triage ?? state?.triage;
+    const triage = latestIterationTriage(state) ?? state?.phases?.["4"]?.triage ?? state?.triage;
     if (!triage) die(`no triage block found in ${statePath}`);
     return triage;
   }

package/pipeline/scripts/doctor.mjs

@@ -54,6 +54,9 @@ import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { runMain } from "../lib/fatal.mjs";
+import { hostCommand } from "../lib/user-facing.mjs";
+import { UNATTENDED_SETTINGS_FILE } from "../lib/unattended-settings-location.mjs";
+import { prefsHosts, profileGaps } from "../lib/unattended-profile-check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -234,7 +237,7 @@ function checkInstallVersion() {
       "install-version",
       "WARN",
       `installed ${installed}, this checkout is ${pkg.version}`,
-      "run /multi-agent:update",
+      `run ${hostCommand("update", HERE)}`,
     );
     return;
   }
@@ -305,7 +308,7 @@ function checkScriptSurface() {
       "script-surface",
       "BLOCK",
       `${missing.length} script(s) a command calls are not installed: ${missing.slice(0, 3).join(", ")}`,
-      "run /multi-agent:update",
+      `run ${hostCommand("update", HERE)}`,
       missing,
     );
     return;
@@ -330,7 +333,7 @@ function checkSkillSiblings() {
       "skill-siblings",
       "WARN",
       `the sibling audit did not complete: ${String(e.message).split("\n")[0]}`,
-      "run /multi-agent:sync",
+      `run ${hostCommand("sync", HERE)}`,
     );
     return;
   }
@@ -342,7 +345,12 @@ function checkSkillSiblings() {
     }
   })();
   if (!j) {
-    report("skill-siblings", "WARN", "the sibling audit returned no JSON", "run /multi-agent:sync");
+    report(
+      "skill-siblings",
+      "WARN",
+      "the sibling audit returned no JSON",
+      `run ${hostCommand("sync", HERE)}`,
+    );
     return;
   }
   // A local-only wrapper is authored for this machine and deliberately excluded
@@ -365,7 +373,7 @@ function checkSkillSiblings() {
       "skill-siblings",
       "WARN",
       `${unsynced} of ${j.commands - localOnly.size} synced command(s) are missing from at least one installed host`,
-      "run /multi-agent:sync",
+      `run ${hostCommand("sync", HERE)}`,
     );
     return;
   }
@@ -394,7 +402,7 @@ function checkStateWritable() {
 function checkPrefsValid() {
   const prefs = join(CLAUDE, "multi-agent-preferences.json");
   if (!existsSync(prefs)) {
-    report("prefs-valid", "WARN", "no preferences file yet", "run /multi-agent:setup");
+    report("prefs-valid", "WARN", "no preferences file yet", `run ${hostCommand("setup", HERE)}`);
     return;
   }
   const j = readJson(prefs);
@@ -403,12 +411,17 @@ function checkPrefsValid() {
       "prefs-valid",
       "BLOCK",
       "multi-agent-preferences.json does not parse",
-      "run /multi-agent:setup",
+      `run ${hostCommand("setup", HERE)}`,
     );
     return;
   }
   if (typeof j.global !== "object" || j.global === null) {
-    report("prefs-valid", "BLOCK", "preferences carry no global block", "run /multi-agent:setup");
+    report(
+      "prefs-valid",
+      "BLOCK",
+      "preferences carry no global block",
+      `run ${hostCommand("setup", HERE)}`,
+    );
     return;
   }
   ok("prefs-valid");
@@ -430,7 +443,7 @@ function checkIdentity() {
     "identity",
     "WARN",
     "no git identity recorded, so a run stops at the commit phase",
-    "run /multi-agent:setup",
+    `run ${hostCommand("setup", HERE)}`,
   );
 }
 
@@ -496,14 +509,14 @@ function checkCredentials(inv) {
       "credential-mapping",
       "WARN",
       `${malformed.length} mapped credential(s) are malformed: ${malformed.map((c) => c.logical).join(", ")}`,
-      "run /multi-agent:setup",
+      `run ${hostCommand("setup", HERE)}`,
     );
   } else if (unmapped.length) {
     report(
       "credential-mapping",
       "INFO",
       `${unmapped.length} optional capabilit${unmapped.length === 1 ? "y is" : "ies are"} not enabled: ${unmapped.map((c) => c.logical).join(", ")}`,
-      `map ${unmapped.map((c) => c.logical).join(", ")} with /multi-agent:setup`,
+      `map ${unmapped.map((c) => c.logical).join(", ")} with ${hostCommand("setup", HERE)}`,
     );
   } else {
     ok("credential-mapping");
@@ -528,7 +541,7 @@ function checkCredentials(inv) {
       "credential-liveness",
       "WARN",
       `${rejected.length} credential(s) were refused: ${rejected.map(([k, w]) => `${k} (${w})`).join(", ")}`,
-      "run /multi-agent:setup",
+      `run ${hostCommand("setup", HERE)}`,
     );
     return;
   }
@@ -827,7 +840,7 @@ function checkWorktreeResidue() {
       "worktree-residue",
       "WARN",
       `${entries.length} worktree(s) left under ${wt}${size}; runs that stopped before Phase 4 are never collected`,
-      "run /multi-agent:garbage-collect, or /multi-agent:kill for a task you know is dead",
+      `run ${hostCommand("garbage-collect", HERE)}, or ${hostCommand("kill", HERE)} for a task you know is dead`,
     );
     return;
   }
@@ -863,32 +876,68 @@ function checkServerProfile(resolved) {
       "unattended-contract",
       "WARN",
       "unattended-contract.md is not installed, so nothing here documents what an unattended run resolves",
-      "run /multi-agent:update to refresh the reference tree",
+      `run ${hostCommand("update", HERE)} to refresh the reference tree`,
     );
   }
 
   // 2. The permission posture. autopilot spawns `claude --permission-prompts
   //    none`, but the tools it then calls still have to be allowed somewhere,
   //    and on a fresh machine they are not - the run stops at the first
-  //    prompt with nobody to answer it.
-  const settings = join(root, "settings.json");
-  let allow = [];
-  try {
-    allow = JSON.parse(readFileSync(settings, "utf-8"))?.permissions?.allow ?? [];
-  } catch {
-    allow = [];
+  //    prompt with nobody to answer it. The rule is schemas/unattended-profile.json,
+  //    the same file `install --unattended` writes from, and the posture lives
+  //    in multi-agent-unattended.settings.json, the file the runner passes with
+  //    `claude --settings`: dontAsk, Edit and Write allowed, every deny rule
+  //    present. Permission lists merge across settings files, so a whole-Bash
+  //    allow in settings.json undoes the narrow list and is a gap too.
+  const settings = join(root, UNATTENDED_SETTINGS_FILE);
+  const readDoc = (f) => {
+    try {
+      return JSON.parse(readFileSync(f, "utf-8")) ?? {};
+    } catch {
+      return {};
+    }
+  };
+  const doc = readDoc(settings);
+  const perms = doc.permissions ?? {};
+  const attendedAllow = (() => {
+    const a = readDoc(join(root, "settings.json")).permissions?.allow;
+    return (Array.isArray(a) ? a : []).map(String);
+  })();
+  const allow = (Array.isArray(perms.allow) ? perms.allow : []).map(String);
+  const deny = (Array.isArray(perms.deny) ? perms.deny : []).map(String);
+  let profile = null;
+  for (const p of [
+    join(root, "schemas", "unattended-profile.json"),
+    join(HERE, "..", "schemas", "unattended-profile.json"),
+  ]) {
+    try {
+      profile = JSON.parse(readFileSync(p, "utf-8"));
+      break;
+    } catch {
+      /* next candidate */
+    }
+  }
+  const gaps = [];
+  for (const t of ["Edit", "Write"]) if (!allow.includes(t)) gaps.push(`${t} is not allowed`);
+  if (!allow.some((a) => a.startsWith("Bash("))) gaps.push("no Bash rule is allowed");
+  if (profile) {
+    for (const { rule } of profile.wideAllows)
+      if (attendedAllow.includes(rule))
+        gaps.push(`a bare ${rule} allow in settings.json makes the narrow list meaningless`);
+    const found = profileGaps(doc, profile, { extraHosts: prefsHosts(dirname(root)) });
+    gaps.push(...found.permissions, ...found.sandbox);
+  } else {
+    gaps.push("schemas/unattended-profile.json is not installed, so the posture cannot be checked");
   }
-  const needed = ["Bash", "Edit", "Write"];
-  const missing = needed.filter((t) => !allow.some((a) => String(a).startsWith(t)));
-  if (!missing.length) {
+  if (!gaps.length) {
     ok("unattended-permissions");
   } else {
     report(
       "unattended-permissions",
       "WARN",
-      `permissions.allow does not cover ${missing.join(", ")}; an unattended run stops at the first prompt`,
-      "run /multi-agent:setup, or add them to permissions.allow in settings.json",
-      { settings, allow },
+      `the unattended permission posture is incomplete: ${gaps.join("; ")}`,
+      "run `npx --@mmerterden:registry=https://registry.npmjs.org @mmerterden/multi-agent-pipeline install --unattended` (it prints the profile before writing it)",
+      { settings, allow, deny },
     );
   }
 
@@ -911,7 +960,7 @@ function checkServerProfile(resolved) {
       "scheduler",
       "WARN",
       "no multi-agent launchd agent is loaded, so nothing starts a queued run on its own",
-      "run /multi-agent:autopilot to install the agent, or schedule the runner yourself",
+      `run ${hostCommand("autopilot", HERE)} to install the agent, or schedule the runner yourself`,
     );
   }