@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/_autopilot-outcomes.mjs

@@ -0,0 +1,174 @@
+/**
+ * @file _autopilot-outcomes.mjs  -  the one outcome contract for continuous mode.
+ *
+ * The runner writes an outcome per attempt into attempted.jsonl; intake reads
+ * it back to decide whether the item may run again; the breaker reads it to
+ * decide whether the machine is broken. All three have to agree on what each
+ * word means, so the words and their classes live here and nowhere else.
+ *
+ *   TERMINAL   the item is finished with us. Never queued again.
+ *   RETRYABLE  the attempt produced nothing. Queued again until `maxAttempts`,
+ *              and each one counts toward that ceiling.
+ *   PARKED     the item is waiting for a person. Listed as awaiting, never
+ *              re-run on its own, and its session and worktree are left alone.
+ *   BLOCKED    `blocked-*`: nothing ran. Arming or a precondition refused the
+ *              item, which says nothing about the item or the machine, so it
+ *              neither counts as an attempt nor feeds the breaker.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/scripts/_autopilot-outcomes
+ */
+
+/** Every outcome word the runner writes, by name, so a typo is a ReferenceError. */
+export const OUTCOME = Object.freeze({
+  PR_OPENED: "pr-opened",
+  PUSHED_AWAITING_PR: "pushed-awaiting-pr",
+  MERGED: "merged",
+  SKIPPED: "skipped",
+  COMPLETED_NO_PR: "completed-no-pr",
+  NEEDS_INPUT: "needs-input",
+  AWAITING_ANSWER: "awaiting-answer",
+  VERIFICATION_FAILED: "verification-failed",
+  FAILED: "failed",
+  BUILD_FAILED: "build-failed",
+  LAUNCH_FAILED: "launch-failed",
+  TIMED_OUT: "timed-out",
+  NO_STATE: "no-state",
+  UNKNOWN: "unknown",
+  DIED: "died",
+  RATE_LIMITED: "rate-limited",
+  BLOCKED_NO_PATH: "blocked-no-path",
+  BLOCKED_GUARD_MISSING: "blocked-guard-missing",
+  BLOCKED_SANDBOX_UNAVAILABLE: "blocked-sandbox-unavailable",
+});
+
+/**
+ * `completed-no-pr` is here because a run can stop legitimately without a PR -
+ * a question answered in chat, nothing to change - and running it again would
+ * repeat the same answer at the same cost.
+ *
+ * `pushed-awaiting-pr` is a verified branch the runner pushed to a host with no
+ * draft PR (Bitbucket). The work is delivered and the one step left is a
+ * person's, which touches neither the worktree nor the queue: a retry would
+ * push the same work again, and parking would hold the repo for a step that
+ * does not need it.
+ */
+export const TERMINAL = new Set([
+  OUTCOME.PR_OPENED,
+  OUTCOME.PUSHED_AWAITING_PR,
+  OUTCOME.MERGED,
+  OUTCOME.SKIPPED,
+  OUTCOME.COMPLETED_NO_PR,
+]);
+
+/**
+ * `died` - a run the supervisor lost track of - counts toward the item's
+ * attempts like the rest. `rate-limited` does too, and additionally has its own
+ * backoff in the runner, because the limit is the account's and the next item
+ * would hit it just the same.
+ */
+export const RETRYABLE = new Set([
+  OUTCOME.FAILED,
+  OUTCOME.BUILD_FAILED,
+  OUTCOME.LAUNCH_FAILED,
+  OUTCOME.TIMED_OUT,
+  OUTCOME.NO_STATE,
+  OUTCOME.UNKNOWN,
+  OUTCOME.DIED,
+  OUTCOME.RATE_LIMITED,
+]);
+
+/**
+ * `verification-failed` is parked rather than retryable: the run produced work
+ * and its own verification rejected it, so an automatic retry repeats the same
+ * work into the same rejection and bills for it twice. It is not terminal
+ * either, because nothing was delivered - it waits for a person to look.
+ */
+export const PARKED = new Set([
+  OUTCOME.NEEDS_INPUT,
+  OUTCOME.AWAITING_ANSWER,
+  OUTCOME.VERIFICATION_FAILED,
+]);
+
+/**
+ * The `blocked-*` words written today: one per arming verdict, a checkout that
+ * is not on disk, a machine whose settings do not register the agent-guard
+ * hook the unattended contract relies on, and a profile file (or a checkout's
+ * own settings) that no longer holds the OS sandbox the contract rests on. classifyOutcome accepts the whole prefix family, because
+ * the runner writes `blocked-<blockedBy>` for whatever arming names.
+ */
+export const BLOCKED = new Set([
+  "blocked-credential",
+  "blocked-cost",
+  "blocked-cost-unknown",
+  "blocked-internal",
+  "blocked-config",
+  OUTCOME.BLOCKED_NO_PATH,
+  OUTCOME.BLOCKED_GUARD_MISSING,
+  OUTCOME.BLOCKED_SANDBOX_UNAVAILABLE,
+]);
+
+/** Prefix families. `stopped-<status>` is a run that ended mid-way. */
+const STOPPED_PREFIX = "stopped-";
+const BLOCKED_PREFIX = "blocked-";
+
+/**
+ * The class of one outcome word, or null for a word this contract does not
+ * know. Null is deliberately not folded into any class: an unknown word in the
+ * ledger is a writer that drifted, and guessing its class hides that.
+ *
+ * @param {string} outcome
+ * @returns {"terminal"|"retryable"|"parked"|"blocked"|null}
+ */
+export function classifyOutcome(outcome) {
+  if (typeof outcome !== "string" || !outcome) return null;
+  if (TERMINAL.has(outcome)) return "terminal";
+  if (RETRYABLE.has(outcome)) return "retryable";
+  if (PARKED.has(outcome)) return "parked";
+  if (outcome.startsWith(STOPPED_PREFIX) && outcome.length > STOPPED_PREFIX.length) {
+    return "retryable";
+  }
+  if (outcome.startsWith(BLOCKED_PREFIX) && outcome.length > BLOCKED_PREFIX.length) {
+    return "blocked";
+  }
+  return null;
+}
+
+export const isTerminal = (o) => classifyOutcome(o) === "terminal";
+export const isRetryable = (o) => classifyOutcome(o) === "retryable";
+export const isParked = (o) => classifyOutcome(o) === "parked";
+export const isBlocked = (o) => classifyOutcome(o) === "blocked";
+
+/**
+ * The text a rate-limited session leaves behind. The first pattern is the CLI
+ * notice observed from a live session at its plan limit ("You've hit your
+ * weekly limit · resets 5am ..."), which is the whole message when the API
+ * error does not follow it. The rest are the API 429 / `rate_limit_error`
+ * shapes and a "usage limit reached ... resets" notice, expected but not yet
+ * observed from an unattended run.
+ */
+const RATE_LIMIT_PATTERNS = [
+  /\bhit your (?:[a-z]+ )?limit\b/i,
+  /\brate[_ -]?limit(?:ed|_error)?\b/i,
+  /\busage limit reached\b/i,
+  /\blimit reached\b.*\bresets?\b/i,
+  /\b429\b.*\b(?:too many requests|rate)/i,
+  /API Error:\s*429\b/i,
+];
+
+/**
+ * Did this run stop because of a rate limit?
+ *
+ * Reads only the session's own row and the run's recorded halt reason - never
+ * the run log, where a task ABOUT rate limiting would match on its own prose.
+ *
+ * @param {{row?: object|null, state?: object|null}} evidence
+ * @returns {boolean}
+ */
+export function rateLimited({ row, state } = {}) {
+  const texts = [];
+  if (row && typeof row === "object") texts.push(JSON.stringify(row));
+  if (state && typeof state.haltReason === "string") texts.push(state.haltReason);
+  return texts.some((t) => RATE_LIMIT_PATTERNS.some((re) => re.test(t)));
+}

package/pipeline/scripts/_command-contract.mjs

@@ -0,0 +1,384 @@
+/**
+ * @file _command-contract.mjs  -  the command surface as data: each command's
+ * parameters, whether a client offers it, and whether it destroys anything.
+ *
+ * Every `pipeline/commands/multi-agent/<id>/SKILL.md` declares, in frontmatter:
+ *
+ *   parameters:  [{name, kind, required?, repeat?, enum?}]   one-line JSON
+ *   gui:         button | form | hidden
+ *   destructive: true | false
+ *   confirm:     required | none
+ *
+ * `argument-hint` is what a person reads in autocomplete and `parameters` is
+ * what a client renders a form from. Two hand-written descriptions of one
+ * signature drift, so `checkCommand` holds them to each other. The rule, which
+ * is the whole of what "consistent" means here:
+ *
+ *   1. No arguments. A hint that is absent, empty, or starts with `(` declares
+ *      none, and `parameters` must be `[]`.
+ *   2. Flags. The set of `--name` tokens anywhere in the hint - syntax and the
+ *      prose after the `  -  ` separator both, because several hints list flags
+ *      only in the prose - equals the set of parameters named `--name`. A flag
+ *      is never required.
+ *   3. Flag values, read in the syntax part only (prose is prose). `--x=...` or
+ *      `--x <value>` takes a value, so its kind is not `flag`; a bare `--x`
+ *      takes none, so its kind is `flag`. A value spelled as a list of bare
+ *      words (`a|b|c`, `a,b,c`) makes the kind `enum` with exactly those
+ *      values, and `,` makes it `repeat: true`.
+ *   4. Positionals. The syntax part (before the first `  -  `) splits at top
+ *      level into slots: a `[...]`, `<...>`, quoted or bare token. A slot whose
+ *      text starts with `--` is a flag group, not a positional. The parameters
+ *      not named `--...` match the remaining slots one to one, in order:
+ *      `[...]` is `required: false`, any other slot `required: true`; text
+ *      ending in `...` is `repeat: true`.
+ *   5. Positional enums. A slot of two or more bare lowercase alternatives
+ *      (`[en|tr]`) must be `kind: "enum"` with exactly those values. A
+ *      positional of kind `flag` is a literal keyword (`[autopilot]`), so its
+ *      name must equal the slot's text.
+ *
+ * Surface rules: `destructive: true` needs `confirm: required`; a `button`
+ * takes no required parameter; a `form` has at least one parameter.
+ *
+ * Zero runtime dependencies (ADR-0004): the frontmatter reader is line-based
+ * like lint-skills.mjs, and `parameters` is JSON so it parses without YAML.
+ *
+ * @module pipeline/scripts/_command-contract
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const PARAMETER_KINDS = [
+  "run-id",
+  "branch",
+  "pull-request",
+  "issue-key",
+  "path",
+  "text",
+  "enum",
+  "flag",
+];
+export const GUI_SURFACES = ["button", "form", "hidden"];
+export const CONFIRM_VALUES = ["required", "none"];
+
+/** The separator every hint uses between its syntax and its prose. */
+const HINT_SEPARATOR = "  -  ";
+
+/** Unquote one YAML scalar the way a YAML parser would for the two quote styles. */
+export function yamlScalar(value) {
+  const v = String(value ?? "").trim();
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  return v;
+}
+
+/**
+ * Top-level `key: value` lines of the frontmatter, values raw (still quoted).
+ *
+ * @param {string} raw  whole SKILL.md text
+ * @returns {Record<string,string>|null}  null when there is no frontmatter
+ */
+export function frontmatterFields(raw) {
+  if (!raw.startsWith("---\n")) return null;
+  const end = raw.indexOf("\n---", 4);
+  if (end === -1) return null;
+  const fields = {};
+  for (const line of raw.slice(4, end).split("\n")) {
+    const m = line.match(/^([a-zA-Z][a-zA-Z0-9-]*):\s*(.*)$/);
+    if (m) fields[m[1]] = m[2];
+  }
+  return fields;
+}
+
+/** Split text into top-level slots: `[...]`, `<...>`, quoted, or bare tokens. */
+export function topLevelSlots(text) {
+  const slots = [];
+  let i = 0;
+  const closer = { "[": "]", "<": ">" };
+  while (i < text.length) {
+    const ch = text[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    const start = i;
+    if (ch === "[" || ch === "<") {
+      const stack = [closer[ch]];
+      let quote = null;
+      i++;
+      while (i < text.length && stack.length) {
+        const c = text[i];
+        if (quote) {
+          if (c === quote) quote = null;
+        } else if (c === '"' || c === "'") quote = c;
+        else if (c === "[" || c === "<") stack.push(closer[c]);
+        else if (c === stack[stack.length - 1]) stack.pop();
+        i++;
+      }
+      slots.push({ raw: text.slice(start, i), bracket: ch, inner: text.slice(start + 1, i - 1) });
+    } else if (ch === '"' || ch === "'") {
+      const close = text.indexOf(ch, i + 1);
+      i = close === -1 ? text.length : close + 1;
+      slots.push({ raw: text.slice(start, i), bracket: ch, inner: text.slice(start + 1, i - 1) });
+    } else {
+      while (i < text.length && !/\s/.test(text[i])) i++;
+      slots.push({ raw: text.slice(start, i), bracket: null, inner: text.slice(start, i) });
+    }
+  }
+  return slots.map((s) => {
+    const inner = s.inner.trim();
+    const repeat = /\.\.\.\s*$/.test(inner);
+    return {
+      ...s,
+      inner,
+      optional: s.bracket === "[",
+      repeat,
+      isFlagGroup: inner.startsWith("--"),
+    };
+  });
+}
+
+const BARE_WORD = /^[a-z0-9][a-z0-9-]*$/;
+
+/** A value spelled as a list of bare words, or null when it is a placeholder. */
+function wordList(value) {
+  for (const sep of ["|", ","]) {
+    if (!value.includes(sep)) continue;
+    const words = value.split(sep).map((w) => w.trim());
+    if (words.length >= 2 && words.every((w) => BARE_WORD.test(w))) {
+      return { words, repeat: sep === "," };
+    }
+  }
+  return null;
+}
+
+/**
+ * What the syntax part says about each flag it names: whether it takes a value
+ * and, when the value is a word list, which words.
+ */
+function flagShapes(syntax) {
+  const shapes = new Map();
+  // A value belongs to its flag only inside one top-level slot, so
+  // `[--dry-run] [target]` never reads `target` as the flag's value.
+  for (const slot of topLevelSlots(syntax)) {
+    const tokens = slot.inner
+      .replace(/[[\]]/g, " ")
+      .split(/\s+|\|(?=\s*--)/)
+      .filter(Boolean);
+    for (let i = 0; i < tokens.length; i++) {
+      const m = tokens[i].match(/^(--[a-z][a-z0-9-]*)(=(.*))?$/);
+      if (!m) continue;
+      let value = null;
+      if (m[2] !== undefined) value = m[3];
+      else {
+        const next = tokens[i + 1];
+        if (next !== undefined && !next.startsWith("--") && next !== "|") value = next;
+      }
+      shapes.set(m[1], { takesValue: value !== null, list: value ? wordList(value) : null });
+    }
+  }
+  return shapes;
+}
+
+/**
+ * Everything the hint declares, in the shape `checkCommand` compares against.
+ *
+ * @param {string|undefined} hint  the unquoted argument-hint
+ */
+export function parseHint(hint) {
+  const text = String(hint ?? "").trim();
+  if (text === "" || text.startsWith("(")) {
+    return { noArgs: true, flags: new Set(), shapes: new Map(), slots: [] };
+  }
+  const cut = text.indexOf(HINT_SEPARATOR);
+  const syntax = cut === -1 ? text : text.slice(0, cut);
+  const flags = new Set(text.match(/--[a-z][a-z0-9-]*/g) ?? []);
+  const slots = topLevelSlots(syntax).filter((s) => !s.isFlagGroup);
+  return { noArgs: false, flags, shapes: flagShapes(syntax), slots };
+}
+
+/** Parse the `parameters:` line. Returns {value} or {error}. */
+export function parseParameters(rawValue) {
+  if (rawValue === undefined) return { error: "missing required field: parameters" };
+  try {
+    const value = JSON.parse(rawValue);
+    if (!Array.isArray(value)) return { error: "parameters must be a JSON array" };
+    return { value };
+  } catch (err) {
+    return { error: `parameters is not one-line JSON (${err.message})` };
+  }
+}
+
+/** Fill the documented defaults so a consumer never has to know them. */
+export function normalizeParameter(p) {
+  const out = {
+    name: p.name,
+    kind: p.kind,
+    required: p.required === true,
+    repeat: p.repeat === true,
+  };
+  if (Array.isArray(p.enum)) out.enum = [...p.enum];
+  return out;
+}
+
+const sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+
+/**
+ * Every contract violation in one command's frontmatter.
+ *
+ * @param {Record<string,string>} fields  raw values from frontmatterFields()
+ * @returns {string[]}
+ */
+export function checkCommand(fields) {
+  const errors = [];
+  const parsed = parseParameters(fields.parameters);
+  if (parsed.error) errors.push(parsed.error);
+  const params = parsed.value ?? [];
+
+  const names = new Set();
+  params.forEach((p, i) => {
+    const at = `parameters[${i}]`;
+    if (!p || typeof p !== "object" || Array.isArray(p)) {
+      errors.push(`${at} is not an object`);
+      return;
+    }
+    if (typeof p.name !== "string" || !/^(--)?[a-z0-9][a-z0-9-]*$/.test(p.name)) {
+      errors.push(`${at}.name must be lowercase kebab-case, "--" prefixed for a flag`);
+    } else if (names.has(p.name)) errors.push(`${at}.name "${p.name}" is declared twice`);
+    else names.add(p.name);
+    if (!PARAMETER_KINDS.includes(p.kind)) {
+      errors.push(`${at}.kind must be one of ${PARAMETER_KINDS.join("|")}`);
+    }
+    for (const k of ["required", "repeat"]) {
+      if (k in p && typeof p[k] !== "boolean") errors.push(`${at}.${k} must be a boolean`);
+    }
+    if (p.kind === "enum" && !(Array.isArray(p.enum) && p.enum.length >= 1)) {
+      errors.push(`${at} is kind enum but has no enum values`);
+    }
+    if (p.kind !== "enum" && "enum" in p) errors.push(`${at} has enum values but is not kind enum`);
+    const extra = Object.keys(p).filter(
+      (k) => !["name", "kind", "required", "repeat", "enum"].includes(k),
+    );
+    if (extra.length) errors.push(`${at} has unknown keys: ${extra.join(", ")}`);
+  });
+
+  const hint = parseHint(yamlScalar(fields["argument-hint"]));
+  const valid = params.filter((p) => p && typeof p.name === "string");
+  const flagParams = valid.filter((p) => p.name.startsWith("--"));
+  const positional = valid.filter((p) => !p.name.startsWith("--"));
+
+  if (hint.noArgs) {
+    if (params.length) errors.push("argument-hint declares no arguments but parameters is not []");
+  } else {
+    for (const f of hint.flags) {
+      if (!flagParams.some((p) => p.name === f)) {
+        errors.push(`argument-hint names ${f}, which parameters does not declare`);
+      }
+    }
+    for (const p of flagParams) {
+      if (!hint.flags.has(p.name)) {
+        errors.push(`parameter ${p.name} does not appear in argument-hint`);
+        continue;
+      }
+      if (p.required === true) errors.push(`flag ${p.name} cannot be required`);
+      const shape = hint.shapes.get(p.name);
+      if (!shape) continue;
+      if (shape.takesValue && p.kind === "flag") {
+        errors.push(`${p.name} takes a value in argument-hint, so its kind cannot be flag`);
+      }
+      if (!shape.takesValue && p.kind !== "flag") {
+        errors.push(`${p.name} takes no value in argument-hint, so its kind must be flag`);
+      }
+      if (shape.list) {
+        if (p.kind !== "enum" || !sameSet(p.enum ?? [], shape.list.words)) {
+          errors.push(
+            `${p.name} must be enum [${shape.list.words.join(", ")}] as argument-hint lists`,
+          );
+        }
+        if ((p.repeat === true) !== shape.list.repeat) {
+          errors.push(`${p.name} repeat must be ${shape.list.repeat} (argument-hint separator)`);
+        }
+      }
+    }
+
+    if (positional.length !== hint.slots.length) {
+      errors.push(
+        `argument-hint has ${hint.slots.length} positional slot(s) but parameters declares ${positional.length}`,
+      );
+    } else {
+      positional.forEach((p, i) => {
+        const slot = hint.slots[i];
+        if ((p.required === true) === slot.optional) {
+          errors.push(
+            `${p.name} required must be ${!slot.optional} (argument-hint slot ${slot.raw})`,
+          );
+        }
+        if ((p.repeat === true) !== slot.repeat) {
+          errors.push(`${p.name} repeat must be ${slot.repeat} (argument-hint slot ${slot.raw})`);
+        }
+        const alts = slot.inner
+          .replace(/\.\.\.\s*$/, "")
+          .split("|")
+          .map((a) => a.trim())
+          .filter(Boolean);
+        if (alts.length >= 2 && alts.every((a) => BARE_WORD.test(a))) {
+          if (p.kind !== "enum" || !sameSet(p.enum ?? [], alts)) {
+            errors.push(`${p.name} must be enum [${alts.join(", ")}] as argument-hint lists`);
+          }
+        }
+        if (p.kind === "flag" && p.name !== slot.inner) {
+          errors.push(
+            `${p.name} is a keyword, so its name must equal the slot text "${slot.inner}"`,
+          );
+        }
+      });
+    }
+  }
+
+  const gui = yamlScalar(fields.gui);
+  if (!GUI_SURFACES.includes(gui)) errors.push(`gui must be ${GUI_SURFACES.join("|")}`);
+  const destructive = yamlScalar(fields.destructive);
+  if (!["true", "false"].includes(destructive)) errors.push("destructive must be true|false");
+  const confirm = yamlScalar(fields.confirm);
+  if (!CONFIRM_VALUES.includes(confirm)) errors.push(`confirm must be ${CONFIRM_VALUES.join("|")}`);
+  if (destructive === "true" && confirm !== "required") {
+    errors.push("a destructive command must declare confirm: required");
+  }
+  if (gui === "button" && valid.some((p) => p.required === true)) {
+    errors.push("a button cannot have a required parameter; use gui: form");
+  }
+  if (gui === "form" && params.length === 0) {
+    errors.push("a form needs at least one parameter; use gui: button");
+  }
+  return errors;
+}
+
+/**
+ * The catalog a client renders from: one entry per command, defaults filled.
+ *
+ * @param {string} commandsDir  pipeline/commands/multi-agent (or an installed copy)
+ */
+export function loadCatalog(commandsDir) {
+  const out = [];
+  for (const id of readdirSync(commandsDir).sort()) {
+    const file = join(commandsDir, id, "SKILL.md");
+    if (!existsSync(file)) continue;
+    const fields = frontmatterFields(readFileSync(file, "utf8"));
+    if (!fields) continue;
+    const parsed = parseParameters(fields.parameters);
+    out.push({
+      id,
+      argumentHint: yamlScalar(fields["argument-hint"]),
+      parameters: (parsed.value ?? []).map(normalizeParameter),
+      gui: yamlScalar(fields.gui) || null,
+      destructive: yamlScalar(fields.destructive) === "true",
+      confirm: yamlScalar(fields.confirm) || null,
+    });
+  }
+  return out;
+}

package/pipeline/scripts/_cost.mjs

@@ -33,3 +33,43 @@ export function costUsd(rate, tokensIn = 0, tokensOut = 0, tokensCached = 0) {
     ((tokensOut || 0) / 1_000_000) * rout
   );
 }
+
+/**
+ * Spend across autopilot attempt-ledger rows (attempted.jsonl).
+ *
+ * A row's `usd` is the run's cumulative cost when the row was written, priced
+ * from the tracker the run keeps. One run can be recorded more than once - parked
+ * and later settled, or researched and then resumed - and each later row carries
+ * the running total again. Rows are therefore grouped by `taskId`, the id the
+ * runner gives one claim, and each run counts once at the largest figure any of
+ * its rows recorded. A run whose rows never carry a number (`usd: null`) is
+ * unknown, never 0. A row with no `taskId` stands for itself, and a row with no
+ * `usd` at all is one where nothing ran.
+ *
+ * @param {object[]} rows
+ * @returns {{usd: number, unknown: number}}
+ */
+export function attemptSpend(rows) {
+  let usd = 0;
+  let unknown = 0;
+  const runs = new Map();
+  for (const r of rows || []) {
+    if (!r || typeof r !== "object") continue;
+    const measured = r.usd !== null && r.usd !== undefined && Number.isFinite(Number(r.usd));
+    const key = typeof r.taskId === "string" && r.taskId ? r.taskId : null;
+    if (!key) {
+      if (r.usd === null) unknown += 1;
+      else if (measured) usd += Number(r.usd);
+      continue;
+    }
+    const run = runs.get(key) || { max: null, unmeasured: false };
+    if (measured) run.max = run.max === null ? Number(r.usd) : Math.max(run.max, Number(r.usd));
+    else if (r.usd === null) run.unmeasured = true;
+    runs.set(key, run);
+  }
+  for (const run of runs.values()) {
+    if (run.max !== null) usd += run.max;
+    else if (run.unmeasured) unknown += 1;
+  }
+  return { usd, unknown };
+}