@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/scripts/worktrees.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * @file worktrees.mjs  -  which runs own a worktree, and how much disk each
+ * one holds.
+ *
+ * A panel deciding what to `/multi-agent:kill` needs the list and, when asked,
+ * the size. Measuring walks the whole tree, so it is opt-in: without
+ * `--measure` every `sizeBytes` and `measuredAt` is null, which reads as "not
+ * measured" rather than as zero.
+ *
+ * A run counts when its agent-state.json names a worktree. A local-mode run
+ * (`localMode: true`, or `worktreePath` equal to `projectRoot`) has none - its
+ * path is the user's own checkout, and measuring or offering that for removal
+ * would be wrong in both directions. A multi-repo run contributes one entry per
+ * project worktree.
+ *
+ * Read-only. `--redact` drops `worktreePath`, the one field specific to this
+ * machine. Shape: pipeline/schemas/worktrees.schema.json.
+ *
+ * Usage:
+ *   node worktrees.mjs --json [--measure] [--redact]
+ *
+ * Exit: 0 printed, 2 usage error.
+ *
+ * @module pipeline/scripts/worktrees
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { listRuns } from "./_run-paths.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const DU_TIMEOUT_MS = 120000;
+
+function readState(dir) {
+  for (const p of [join(dir, "agent-state.json"), join(dir, "artifacts", "agent-state.json")]) {
+    if (!existsSync(p)) continue;
+    try {
+      return JSON.parse(readFileSync(p, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** The worktrees one state names, local-mode checkouts left out. */
+export function worktreesOf(state) {
+  if (!state || state.localMode === true) return [];
+  const out = [];
+  const add = (path, project, root) => {
+    if (typeof path !== "string" || !path.trim()) return;
+    if (root && path === root) return;
+    out.push({ path, project: project ?? null });
+  };
+  if (Array.isArray(state.projects) && state.projects.length) {
+    for (const p of state.projects) add(p?.worktreePath, p?.project ?? p?.name, p?.projectRoot);
+  } else {
+    add(state.worktreePath, state.project, state.projectRoot);
+  }
+  return out;
+}
+
+/** Bytes on disk, or null when du cannot say. */
+export function measure(path) {
+  const r = spawnSync("du", ["-sk", path], { encoding: "utf8", timeout: DU_TIMEOUT_MS });
+  if (r.status !== 0) return null;
+  const kb = Number.parseInt(r.stdout, 10);
+  return Number.isFinite(kb) ? kb * 1024 : null;
+}
+
+export function buildList({ doMeasure = false, redact = false, now = () => new Date() } = {}) {
+  const worktrees = [];
+  for (const run of listRuns()) {
+    for (const wt of worktreesOf(readState(run.dir))) {
+      const exists = existsSync(wt.path);
+      const size = doMeasure && exists ? measure(wt.path) : null;
+      const entry = {
+        taskId: run.taskId,
+        project: wt.project,
+        worktreePath: wt.path,
+        exists,
+        sizeBytes: size,
+        measuredAt: size === null ? null : now().toISOString(),
+      };
+      if (redact) delete entry.worktreePath;
+      worktrees.push(entry);
+    }
+  }
+  return { contractVersion: CONTRACT_VERSION, worktrees };
+}
+
+function main(argv) {
+  const flags = { json: false, measure: false, redact: false };
+  for (const a of argv) {
+    if (a === "--json") flags.json = true;
+    else if (a === "--measure") flags.measure = true;
+    else if (a === "--redact") flags.redact = true;
+    else {
+      process.stderr.write(`worktrees: unknown argument ${a}\n`);
+      return 2;
+    }
+  }
+  const out = buildList({ doMeasure: flags.measure, redact: flags.redact });
+  if (flags.json) process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  else {
+    for (const w of out.worktrees) {
+      const size = w.sizeBytes === null ? "-" : `${Math.round(w.sizeBytes / 1048576)}M`;
+      process.stdout.write(
+        `${w.taskId.padEnd(30)} ${size.padStart(7)}  ${w.exists ? "" : "(missing) "}${w.worktreePath ?? ""}\n`,
+      );
+    }
+  }
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("worktrees", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/write-state.mjs

@@ -278,11 +278,15 @@ function releaseLock(path, ino = heldLockIno) {
   }
 }
 
-/**
- * @param {object} base
- * @param {object} patch
- * @returns {object}
- */
+const STATE_SCHEMA = (() => {
+  try {
+    const schemaPath = new URL("../schemas/agent-state.schema.json", import.meta.url);
+    return JSON.parse(readFileSync(schemaPath, "utf-8"));
+  } catch {
+    return null;
+  }
+})();
+
 /**
  * The version a NEWLY created state document is stamped with, read from the
  * schema so the writer and the schema cannot disagree. The literal is a
@@ -290,15 +294,37 @@ function releaseLock(path, ino = heldLockIno) {
  * have failed on.
  */
 const STATE_SCHEMA_VERSION = (() => {
-  try {
-    const schemaPath = new URL("../schemas/agent-state.schema.json", import.meta.url);
-    const sv = JSON.parse(readFileSync(schemaPath, "utf-8"))?.properties?.schemaVersion;
-    return sv?.const ?? sv?.enum?.at(-1) ?? "2.1.0";
-  } catch {
-    return "2.1.0";
-  }
+  const sv = STATE_SCHEMA?.properties?.schemaVersion;
+  return sv?.const ?? sv?.enum?.at(-1) ?? "2.1.0";
 })();
 
+/**
+ * Top-level keys this write introduces that agent-state.schema.json does not
+ * declare. Reported, never refused: the schema is additionalProperties:false,
+ * so such a key makes the document invalid, but failing the write would stop a
+ * run over a documentation gap, and the runtime package ships no validator.
+ * Keys already on disk are not reported again, so a document written by an
+ * older version stays quiet until something adds to it.
+ *
+ * @param {object} payload
+ * @param {object} current
+ * @returns {string[]}
+ */
+function undeclaredKeys(payload, current) {
+  const declared = STATE_SCHEMA?.properties;
+  if (!declared || typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return [];
+  }
+  return Object.keys(payload).filter(
+    (k) => !Object.hasOwn(declared, k) && !Object.hasOwn(current ?? {}, k),
+  );
+}
+
+/**
+ * @param {object} base
+ * @param {object} patch
+ * @returns {object}
+ */
 function deepMerge(base, patch) {
   if (Array.isArray(patch)) return patch; // arrays replace
   if (typeof patch !== "object" || patch === null) return patch;
@@ -358,11 +384,11 @@ async function main() {
 
   try {
     let next;
+    /** @type {object} */
+    let current = {};
     if (replace) {
       next = payload;
     } else {
-      /** @type {object} */
-      let current = {};
       if (existsSync(path)) {
         try {
           current = JSON.parse(readFileSync(path, "utf-8"));
@@ -424,11 +450,16 @@ async function main() {
 
     next.rev = priorRev + 1;
 
+    const unknown = undeclaredKeys(payload, replace ? {} : current);
+    if (unknown.length) {
+      console.error(
+        `write-state: warning: not declared in agent-state.schema.json: ${unknown.join(", ")}`,
+      );
+    }
+
     // schemaVersion is stamped only when this call CREATES the document. The
     // migration runner keys on it, and a document that never carries one can
-    // never be migrated - measured on a real install, 43 of 43 state files had
-    // no schemaVersion, so pipeline/schemas/migrations/ was unreachable code.
-    // A merge into an existing unstamped file is deliberately left alone:
+    // never be migrated. A merge into an existing unstamped file is left alone:
     // stamping there would claim a conformance nothing verified.
     if (!fileExistedBefore && typeof next.schemaVersion !== "string") {
       next.schemaVersion = STATE_SCHEMA_VERSION;