@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/plugins/maestro-skills/vendor/unlazy/scripts/gate-lint.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// gate-lint.mjs : audit whether a ledger is worth passing.
+// Zero dependencies. Node 16+.
+//
+// The checker and the Stop hook decide whether gates were met. Neither asks
+// whether the gates were worth meeting. A gate reading "the entire feature
+// works perfectly" with `CHECK: echo ok` and `EXPECT: ok` passes the checker,
+// the parent re-verification and the hook, because the oracle is real, runs,
+// and returns what it promised. Authoring is the one step in the enforcement
+// hierarchy that is still pure prose discipline, and this lints it.
+//
+// This never executes a CHECK. It reads the ledger and judges its oracles.
+//
+//   node gate-lint.mjs [options] <ledger.md ...>
+//     --strict   treat warnings as failures
+//     --json     machine-readable findings
+//
+// exit codes: 0 no strict failures, 1 strict findings, 2 usage or parse error.
+//
+// Usable as a gate, so a ledger can require its own quality:
+//   CHECK: node scripts/gate-lint.mjs GATES.md
+//   EXPECT: LINT OK
+
+import { parseGates, readStableRegularFile } from "./lib/gates.mjs";
+
+const HELP = `usage: gate-lint.mjs [--strict] [--json] <ledger.md ...>
+
+Audit gate quality, not gate completion. Report lexical signs of fixed-output
+oracles, weak expectations, manual measurements, and titles that name an
+activity instead of an outcome. Never executes a CHECK.
+
+exit codes: 0 no strict failures, 1 strict findings, 2 usage or parse error.`;
+
+const KNOWN_OPTIONS = new Set(["--strict", "--json", "--help", "-h"]);
+const MAX_GATE_LEDGER_BYTES = 8 * 1024 * 1024;
+const MAX_REPORTED_FINDINGS = 64;
+const MAX_REPORT_BYTES = 256 * 1024;
+const TRUNCATION_MARKER = "...[truncated]";
+
+// Findings and CLI diagnostics can contain repository-controlled filenames,
+// gate text, parser messages, or argv. Escape terminal controls at those data
+// boundaries instead of rewriting complete output, so help text, structural
+// newlines, and JSON indentation retain their intended formatting.
+const TERMINAL_CONTROL = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/;
+function terminalSafe(value, maxBytes = 1024) {
+  const pieces = [];
+  const sizes = [];
+  let bytes = 0;
+  let truncated = false;
+  for (const character of String(value)) {
+    let piece = character;
+    if (TERMINAL_CONTROL.test(character)) {
+      const code = character.codePointAt(0);
+      const prefix = code <= 0xff ? "\\x" : "\\u";
+      const width = code <= 0xff ? 2 : 4;
+      piece = prefix + code.toString(16).padStart(width, "0");
+    }
+    const size = Buffer.byteLength(piece, "utf8");
+    if (bytes + size > maxBytes) { truncated = true; break; }
+    pieces.push(piece);
+    sizes.push(size);
+    bytes += size;
+  }
+  if (!truncated) return pieces.join("");
+  const markerBytes = Buffer.byteLength(TRUNCATION_MARKER, "utf8");
+  while (pieces.length && bytes + markerBytes > maxBytes) {
+    pieces.pop();
+    bytes -= sizes.pop();
+  }
+  return pieces.join("") + TRUNCATION_MARKER;
+}
+
+const args = process.argv.slice(2);
+if (!args.length) {
+  console.error(HELP);
+  process.exit(2);
+}
+// `--` makes every following token a filename, including literal files named
+// `--help` and `-h`. Only scan the option prefix for the help flags.
+const positionalIndex = args.indexOf("--");
+const optionPrefix = positionalIndex === -1 ? args : args.slice(0, positionalIndex);
+if (optionPrefix.includes("--help") || optionPrefix.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+let strict = false;
+let asJson = false;
+let positional = false;
+const files = [];
+for (const arg of args) {
+  if (!positional && arg === "--") { positional = true; continue; }
+  if (!positional && KNOWN_OPTIONS.has(arg)) {
+    if (arg === "--strict") strict = true;
+    else if (arg === "--json") asJson = true;
+    continue;
+  }
+  if (!positional && arg.startsWith("-")) {
+    console.error("gate-lint: unknown option " + terminalSafe(arg, 512));
+    console.error("run gate-lint.mjs --help for usage");
+    process.exit(2);
+  }
+  files.push(arg);
+}
+if (!files.length) {
+  console.error("gate-lint: name at least one ledger file");
+  process.exit(2);
+}
+
+// This is deliberately advisory and whole-command only. Shell text beginning
+// with `echo` can still chain a real verifier, and argv containing EXPECT says
+// nothing about what the called program prints or whether it exits zero.
+const FIXED_OUTPUT_COMMAND = /^\s*(?:(?:echo|printf)(?:\s+[^&|;]*)?|true|:|exit\s+0)\s*$/i;
+// Tokens that appear in failure output as readily as in success output.
+const WEAK_EXPECT = new Set([
+  "ok", "okay", "done", "pass", "passed", "success", "successful", "succeeded",
+  "complete", "completed", "finished", "yes", "true", "0", "good", "fine", "working",
+]);
+// Openings that name an activity rather than an outcome a stranger could judge.
+const ACTIVITY_START = /^(work(ing)? on|improve|enhance|handle|support|ensure|make sure|try|attempt|look (at|into)|investigate|consider|review|refactor|clean ?up|polish|update|tidy|address|deal with|add support)\b/i;
+const findings = [];
+let errorCount = 0;
+let warningCount = 0;
+let findingCount = 0;
+const add = (file, level, gate, rule, message) => {
+  findingCount++;
+  if (level === "error") errorCount++;
+  else if (level === "warn") warningCount++;
+  if (findings.length >= MAX_REPORTED_FINDINGS) return;
+  findings.push({
+    file: terminalSafe(file, 512),
+    level: terminalSafe(level, 16),
+    gate: gate ? terminalSafe(gate, 128) : null,
+    rule: terminalSafe(rule, 64),
+    message: terminalSafe(message, 1024),
+  });
+};
+
+let parseFailed = false;
+
+for (const file of files) {
+  let text;
+  try {
+    // Explicit lint targets may intentionally live outside the current
+    // working directory, so constrain file kind and size without a root.
+    text = readStableRegularFile(file, {
+      maxBytes: MAX_GATE_LEDGER_BYTES,
+      label: "gate ledger",
+    });
+  } catch (error) {
+    console.error("gate-lint: cannot read " + terminalSafe(file, 512) + ": " + terminalSafe(error.message, 1024));
+    process.exit(2);
+  }
+
+  const doc = parseGates(text);
+  if (doc.errors.length) {
+    // A ledger the shared parser rejects cannot be judged on quality.
+    parseFailed = true;
+    for (const error of doc.errors) add(file, "error", null, "parse", error);
+    continue;
+  }
+
+  const live = doc.gates.filter((gate) => !doc.abandoned.has(gate.id));
+  const runnable = live.filter((gate) => gate.check);
+
+  for (const gate of live) {
+    const { id, title, check, expect } = gate;
+
+    if (check && FIXED_OUTPUT_COMMAND.test(check)) {
+      add(file, "warn", id, "tautological-check",
+        'CHECK looks like a fixed-output command: "' + check + '"; use an oracle that observes the named outcome');
+    }
+
+    if (expect && WEAK_EXPECT.has(expect.trim().toLowerCase())) {
+      add(file, "warn", id, "weak-expect",
+        'EXPECT "' + expect + '" also appears in failure output; match a line only success can print');
+    }
+
+    if (gate.expectation && gate.expectation.kind === "regex" && gate.expectation.pathLike) {
+      add(file, "warn", id, "path-read-as-regex",
+        'EXPECT "' + expect + '" looks like a literal path but is read as a regular expression, so its dots are wildcards');
+    }
+
+    if (!check) {
+      add(file, "warn", id, "manual-gate",
+        "no CHECK, so this outcome is judged by hand and its evidence is only as good as the reader");
+      if (/\d/.test(title)) {
+        add(file, "warn", id, "unmeasured-number",
+          'title states a number that nothing measures: "' + title + '"');
+      }
+    }
+
+    if (ACTIVITY_START.test(title)) {
+      add(file, "warn", id, "activity-not-outcome",
+        'names an activity, not an outcome a stranger could judge: "' + title + '"');
+    }
+  }
+
+  if (live.length && runnable.length / live.length < 0.5) {
+    add(file, "warn", null, "mostly-manual",
+      runnable.length + "/" + live.length + " gates are runnable; a mostly manual ledger is prose with checkboxes");
+  }
+}
+
+const failed = errorCount > 0 || (strict && warningCount > 0);
+
+if (asJson) {
+  const report = {
+    ok: !failed,
+    errors: errorCount,
+    warnings: warningCount,
+    findings: [...findings],
+    truncated: findingCount > findings.length,
+    omittedFindings: findingCount - findings.length,
+  };
+  let output = JSON.stringify(report, null, 2);
+  while (Buffer.byteLength(output, "utf8") > MAX_REPORT_BYTES && report.findings.length) {
+    report.findings.pop();
+    report.truncated = true;
+    report.omittedFindings = findingCount - report.findings.length;
+    output = JSON.stringify(report, null, 2);
+  }
+  console.log(output);
+} else {
+  let lastFile = null;
+  for (const finding of findings) {
+    if (finding.file !== lastFile) {
+      console.log(finding.file);
+      lastFile = finding.file;
+    }
+    const label = finding.level === "error" ? "ERROR" : "WARN ";
+    const who = finding.gate ? finding.gate + ": " : "";
+    console.log("  " + label + " " + who + finding.message + "  [" + finding.rule + "]");
+  }
+  const omitted = findingCount - findings.length;
+  if (omitted) console.log("... [report truncated: " + omitted + " finding(s) omitted]");
+  if (!failed) {
+    console.log(warningCount ? "LINT OK (" + warningCount + " warning(s))" : "LINT OK");
+  } else {
+    console.log("LINT FINDINGS: " + errorCount + " error(s), " + warningCount + " warning(s)");
+  }
+}
+
+// Let Node drain stdout before exiting. A forced process.exit() can truncate a
+// large report when stdout is an asynchronous POSIX pipe.
+process.exitCode = parseFailed ? 2 : failed ? 1 : 0;

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/check-supervisor.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Keep a stable process-group leader alive until CHECK stdio closes.
+// Zero dependencies. Node 16+.
+
+import { spawn } from "node:child_process";
+
+const [shell, command] = process.argv.slice(2);
+if (!shell || command === undefined) {
+  console.error("unlazy-check-supervisor: expected resolved shell and CHECK command");
+  process.exit(2);
+}
+
+let child;
+let spawnError = null;
+try {
+  child = spawn(command, {
+    cwd: process.cwd(),
+    shell,
+    windowsHide: true,
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+} catch (error) {
+  console.error("unlazy-check-supervisor: could not start CHECK: " + error.message);
+  process.exit(127);
+}
+
+// Pipe instead of inheriting descriptors directly. Node's `close` event then
+// waits for descendants that inherited the shell's stdout or stderr, keeping
+// this detached supervisor alive as the original process-group identity.
+child.stdout.pipe(process.stdout, { end: false });
+child.stderr.pipe(process.stderr, { end: false });
+child.once("error", (error) => { spawnError = error; });
+child.once("close", (code, signal) => {
+  if (spawnError) {
+    console.error("unlazy-check-supervisor: CHECK spawn failed: " + spawnError.message);
+    process.exitCode = 127;
+    return;
+  }
+  if (Number.isInteger(code)) {
+    process.exitCode = code;
+    return;
+  }
+  console.error("unlazy-check-supervisor: CHECK ended by " + (signal || "unknown signal"));
+  process.exitCode = 1;
+});

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/dispatch.mjs

@@ -0,0 +1,293 @@
+// Atomic host-dispatch wave state. Zero dependencies. Node 16+.
+
+import { join, resolve } from "node:path";
+import {
+  appendStatus, readStableRegularFile, scopeRoot, validateScopeId, withFileLock, writeAtomic,
+} from "./gates.mjs";
+
+const SCHEMA = 1;
+const MAX_STATE_BYTES = 8 * 1024 * 1024;
+const STATES = new Set(["open", "sealed", "complete", "abandoned"]);
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/;
+const CONTROL_GLOBAL = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g;
+
+const record = (value = {}) => Object.assign(Object.create(null), value);
+const emptyState = () => ({ schema: SCHEMA, waves: record() });
+const count = (record) => Object.keys(record).length;
+
+function fail(message) { throw new Error(message); }
+const safeDiagnostic = (value) => String(value).replace(CONTROL_GLOBAL, " ").replace(/\s+/g, " ").trim().slice(0, 500);
+
+function validId(value, label) {
+  if (typeof value !== "string") fail(label + " must be a string");
+  const error = validateScopeId(value, label);
+  if (error) fail(error);
+  return value;
+}
+
+function validHandle(value) {
+  if (typeof value !== "string") fail("handle must be a string");
+  const handle = value.trim();
+  if (!handle || handle.length > 256 || CONTROL.test(handle)) {
+    fail("handle must be printable, nonblank, and at most 256 characters");
+  }
+  return handle;
+}
+
+function validReason(value) {
+  if (typeof value !== "string") fail("reason must be a string");
+  const reason = value.trim();
+  if (!reason || reason.length > 500 || CONTROL.test(reason)) {
+    fail("reason must be printable, nonblank, and at most 500 characters");
+  }
+  return reason;
+}
+
+function validTime(value, label) {
+  if (typeof value !== "string" || !value || Number.isNaN(Date.parse(value))) {
+    fail(label + " must be an ISO timestamp");
+  }
+  return Date.parse(value);
+}
+
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+
+function validateState(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state) || state.schema !== SCHEMA ||
+      !state.waves || typeof state.waves !== "object" || Array.isArray(state.waves)) {
+    fail("expected schema 1 with a waves object");
+  }
+  state.waves = record(state.waves);
+
+  for (const [waveId, wave] of Object.entries(state.waves)) {
+    validId(waveId, "wave");
+    if (!wave || typeof wave !== "object" || Array.isArray(wave) || !STATES.has(wave.state) ||
+        !Array.isArray(wave.leaves) || !wave.leaves.length ||
+        !wave.started || typeof wave.started !== "object" || Array.isArray(wave.started) ||
+        !wave.returned || typeof wave.returned !== "object" || Array.isArray(wave.returned)) {
+      fail("wave " + waveId + " has an invalid shape");
+    }
+    wave.started = record(wave.started);
+    wave.returned = record(wave.returned);
+    const openedAt = validTime(wave.openedAt, "wave " + waveId + " openedAt");
+    let abandonedAt = null;
+    if (wave.state === "abandoned") {
+      abandonedAt = validTime(wave.abandonedAt, "wave " + waveId + " abandonedAt");
+      wave.reason = validReason(wave.reason);
+    } else if (hasOwn(wave, "abandonedAt") || hasOwn(wave, "reason")) {
+      fail(wave.state + " wave " + waveId + " contains abandonment metadata");
+    }
+    const leaves = new Set();
+    for (const leaf of wave.leaves) {
+      const id = validId(leaf, "leaf");
+      if (leaves.has(id)) fail("wave " + waveId + " has duplicate leaf " + id);
+      leaves.add(id);
+    }
+
+    const handles = new Set();
+    const startTimes = record();
+    let latestStart = openedAt;
+    for (const [leaf, start] of Object.entries(wave.started)) {
+      if (!leaves.has(leaf)) fail("wave " + waveId + " started unknown leaf " + leaf);
+      if (!start || typeof start !== "object" || Array.isArray(start)) fail("wave " + waveId + " has invalid start for " + leaf);
+      const handle = validHandle(start.handle);
+      if (handles.has(handle)) fail("wave " + waveId + " reuses handle " + handle);
+      handles.add(handle);
+      const at = validTime(start.at, "wave " + waveId + " start time for " + leaf);
+      if (at < openedAt) fail("wave " + waveId + " starts " + leaf + " before it opened");
+      startTimes[leaf] = at;
+      latestStart = Math.max(latestStart, at);
+    }
+
+    const returnTimes = [];
+    for (const [leaf, returned] of Object.entries(wave.returned)) {
+      if (!leaves.has(leaf) || !wave.started[leaf]) fail("wave " + waveId + " returned unstarted leaf " + leaf);
+      if (!returned || typeof returned !== "object" || Array.isArray(returned)) fail("wave " + waveId + " has invalid return for " + leaf);
+      const at = validTime(returned.at, "wave " + waveId + " return time for " + leaf);
+      if (at < startTimes[leaf]) fail("wave " + waveId + " returns " + leaf + " before it started");
+      returnTimes.push(at);
+    }
+
+    const allStarted = count(wave.started) === wave.leaves.length;
+    const allReturned = count(wave.returned) === wave.leaves.length;
+    if (wave.state === "open" && count(wave.returned)) fail("open wave " + waveId + " contains returns");
+    if (wave.state !== "open" && wave.state !== "abandoned" && !allStarted) {
+      fail(wave.state + " wave " + waveId + " is missing starts");
+    }
+    if (wave.state === "complete" && !allReturned) fail("complete wave " + waveId + " is missing returns");
+    if (wave.state === "sealed" && allReturned) fail("sealed wave " + waveId + " should be complete");
+
+    const needsSeal = wave.state === "sealed" || wave.state === "complete" ||
+      (wave.state === "abandoned" && hasOwn(wave, "sealedAt"));
+    let sealedAt = null;
+    if (needsSeal) {
+      sealedAt = validTime(wave.sealedAt, "wave " + waveId + " sealedAt");
+      if (!allStarted) fail(wave.state + " wave " + waveId + " is missing starts after sealing");
+      if (sealedAt < latestStart) fail("wave " + waveId + " was sealed before its final start");
+    } else if (hasOwn(wave, "sealedAt")) {
+      fail(wave.state + " wave " + waveId + " contains seal metadata");
+    }
+
+    if (returnTimes.length) {
+      if (sealedAt === null) fail(wave.state + " wave " + waveId + " contains returns without being sealed");
+      if (returnTimes.some((at) => at < sealedAt)) fail("wave " + waveId + " contains a return before sealing");
+    }
+
+    if (wave.state === "complete") {
+      const completedAt = validTime(wave.completedAt, "wave " + waveId + " completedAt");
+      if (completedAt < Math.max(sealedAt, ...returnTimes)) {
+        fail("wave " + waveId + " completed before its final return");
+      }
+    } else if (hasOwn(wave, "completedAt")) {
+      fail(wave.state + " wave " + waveId + " contains completion metadata");
+    }
+
+    if (wave.state === "abandoned") {
+      if (allReturned) fail("abandoned wave " + waveId + " already has every return and must be complete");
+      if (abandonedAt < Math.max(openedAt, latestStart, sealedAt || openedAt, ...returnTimes)) {
+        fail("wave " + waveId + " was abandoned before its latest transition");
+      }
+    }
+  }
+  return state;
+}
+
+function readState(root, path) {
+  try {
+    const text = readStableRegularFile(path, {
+      root: resolve(root),
+      maxBytes: MAX_STATE_BYTES,
+      label: "dispatch state",
+    });
+    return validateState(JSON.parse(text));
+  } catch (error) {
+    if (error && error.code === "ENOENT") return emptyState();
+    if (String(error.message).startsWith("invalid dispatch state:")) throw error;
+    throw new Error("invalid dispatch state: " + error.message);
+  }
+}
+
+export function dispatchStatePath(root, scope) {
+  return join(scopeRoot(resolve(root), validId(scope, "scope")), "dispatch.json");
+}
+
+export function getDispatchWave(root, scope, waveId) {
+  const wave = validId(waveId, "wave");
+  const state = readState(root, dispatchStatePath(root, scope));
+  if (!state.waves[wave]) fail("unknown wave " + wave);
+  return state.waves[wave];
+}
+
+export function dispatchIssues(root, scope) {
+  return dispatchStatus(root, scope).blocking;
+}
+
+export function dispatchStatus(root, scope) {
+  if (!scope) return { blocking: [], abandoned: [], resolved: [], errors: [] };
+  let state;
+  try { state = readState(root, dispatchStatePath(root, scope)); }
+  catch (error) {
+    const message = safeDiagnostic(error.message);
+    return {
+      blocking: ["dispatch:PARSE invalid dispatch state"],
+      abandoned: [],
+      resolved: ["dispatch:PARSE=invalid"],
+      errors: ["invalid dispatch state for scope " + scope + ": " + message],
+    };
+  }
+  const result = { blocking: [], abandoned: [], resolved: [], errors: [] };
+  for (const [id, wave] of Object.entries(state.waves).sort(([left], [right]) => left.localeCompare(right))) {
+    const started = count(wave.started);
+    const returned = count(wave.returned);
+    result.resolved.push("dispatch:" + id + "=" + wave.state + ";started=" + started + "/" +
+      wave.leaves.length + ";returned=" + returned + "/" + wave.leaves.length);
+    if (wave.state === "complete") continue;
+    if (wave.state === "abandoned") {
+      result.abandoned.push("dispatch:" + id);
+    } else if (wave.state === "open") {
+      result.blocking.push("dispatch:" + id + " open (" + started + "/" + wave.leaves.length + " started)");
+    } else {
+      result.blocking.push("dispatch:" + id + " sealed (" + returned + "/" + wave.leaves.length + " returned)");
+    }
+  }
+  return result;
+}
+
+export async function updateDispatch(root, spec) {
+  const scope = validId(spec.scope, "scope");
+  const waveId = validId(spec.wave, "wave");
+  const path = dispatchStatePath(root, scope);
+  let event = "";
+
+  const wave = await withFileLock(root, path, () => {
+    const state = readState(root, path);
+    const now = spec.now || new Date().toISOString();
+    validTime(now, "timestamp");
+
+    if (spec.action === "open") {
+      if (state.waves[waveId]) fail("wave " + waveId + " already exists");
+      const leaves = (spec.leaves || []).map((leaf) => validId(leaf, "leaf"));
+      if (!leaves.length) fail("open requires at least one --leaf");
+      const seen = new Set();
+      for (const leaf of leaves) {
+        if (seen.has(leaf)) fail("duplicate leaf " + leaf);
+        seen.add(leaf);
+      }
+      state.waves[waveId] = { leaves, state: "open", openedAt: now, started: record(), returned: record() };
+      event = "dispatch " + waveId + " opened: " + leaves.join(", ");
+    } else {
+      const current = state.waves[waveId];
+      if (!current) fail("unknown wave " + waveId);
+      if (spec.action === "abandon") {
+        if (current.state === "complete" || current.state === "abandoned") {
+          fail("wave " + waveId + " is " + current.state + "; abandon requires an open or sealed wave");
+        }
+        current.state = "abandoned";
+        current.reason = validReason(spec.reason);
+        current.abandonedAt = now;
+        event = "dispatch " + waveId + " abandoned: " + current.reason;
+      } else if (spec.action === "start") {
+        const leaf = validId(spec.leaf, "leaf");
+        const handle = validHandle(spec.handle);
+        if (current.state !== "open") fail("wave " + waveId + " is " + current.state + "; start requires an open wave");
+        if (!current.leaves.includes(leaf)) fail("unknown leaf " + leaf + " in wave " + waveId);
+        if (current.started[leaf]) fail("leaf " + leaf + " already started");
+        const owner = Object.entries(current.started).find(([, start]) => start.handle === handle);
+        if (owner) fail("handle is already assigned to " + owner[0]);
+        current.started[leaf] = { handle, at: now };
+        event = "dispatch " + waveId + " started " + leaf + " as " + handle;
+      } else if (spec.action === "seal") {
+        if (current.state !== "open") fail("wave " + waveId + " is " + current.state + "; seal requires an open wave");
+        const missing = current.leaves.filter((leaf) => !current.started[leaf]);
+        if (missing.length) fail("cannot seal " + waveId + ": missing starts for " + missing.join(", "));
+        current.state = "sealed";
+        current.sealedAt = now;
+        event = "dispatch " + waveId + " sealed";
+      } else if (spec.action === "return") {
+        const leaf = validId(spec.leaf, "leaf");
+        if (current.state !== "sealed") fail("return requires a sealed wave; " + waveId + " is " + current.state);
+        if (!current.leaves.includes(leaf)) fail("unknown leaf " + leaf + " in wave " + waveId);
+        if (current.returned[leaf]) fail("leaf " + leaf + " already returned");
+        current.returned[leaf] = { at: now };
+        if (count(current.returned) === current.leaves.length) {
+          current.state = "complete";
+          current.completedAt = now;
+        }
+        event = "dispatch " + waveId + " returned " + leaf;
+      } else fail("unknown dispatch action " + spec.action);
+    }
+
+    validateState(state);
+    writeAtomic(path, JSON.stringify(state, null, 2) + "\n", { root });
+    return state.waves[waveId];
+  });
+
+  let logWarning = "";
+  try {
+    await appendStatus(root, scope, new Date().toISOString() + " " + event);
+  } catch (error) {
+    logWarning = "state transition committed; audit status append was skipped: " +
+      safeDiagnostic(error && error.message ? error.message : error);
+  }
+  return { wave, logWarning };
+}