@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/verification.js

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cantRunReason, detectCheckCommand, failureExcerpt, failureFingerprint, runCheck } from "./checks.js";
+const KINDS = /* @__PURE__ */ new Set(["build", "typecheck", "lint", "unit", "integration", "browser", "mutation", "visual", "accessibility", "custom"]);
+const DEFAULT_CHECK_TIMEOUT = 5 * 6e4;
+const MAX_CHECK_TIMEOUT = 30 * 6e4;
+const MAX_SUITE_TIMEOUT = 60 * 6e4;
+function validateVerificationProfile(value) {
+  if (!value || typeof value !== "object") throw new Error("A verification profile is required");
+  const p = value;
+  if (typeof p.name !== "string" || !p.name.trim() || p.name.length > 120) throw new Error("Verification profile needs a name of at most 120 characters");
+  if (!Array.isArray(p.checks) || p.checks.length > 12) throw new Error("Verification profiles support at most 12 checks");
+  const ids = /* @__PURE__ */ new Set();
+  const checks = p.checks.map((raw) => {
+    if (!raw || typeof raw !== "object") throw new Error("Invalid verification check");
+    const c = raw;
+    if (typeof c.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(c.id) || ids.has(c.id)) throw new Error("Verification check IDs must be unique and contain letters, digits, underscores or hyphens");
+    ids.add(c.id);
+    if (!KINDS.has(c.kind)) throw new Error(`Unknown verification kind for ${c.id}`);
+    if (typeof c.command !== "string" || !c.command.trim() || c.command.length > 4e3 || c.command.includes("\0")) throw new Error(`Invalid command for ${c.id}`);
+    const timeoutMs = c.timeoutMs ?? DEFAULT_CHECK_TIMEOUT;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_CHECK_TIMEOUT) throw new Error(`Check timeout must be between 1 ms and ${MAX_CHECK_TIMEOUT} ms`);
+    if (c.required !== void 0 && typeof c.required !== "boolean") throw new Error(`Invalid required flag for ${c.id}`);
+    return { id: c.id, ...typeof c.title === "string" && c.title.trim() ? { title: c.title.trim().slice(0, 120) } : {}, kind: c.kind, command: c.command.trim(), required: c.required !== false, timeoutMs };
+  });
+  let requirements;
+  if (p.requirements !== void 0) {
+    if (!Array.isArray(p.requirements) || p.requirements.length > 48) throw new Error("Verification supports at most 48 requirement mappings");
+    const requirementIds = /* @__PURE__ */ new Set();
+    requirements = p.requirements.map((raw) => {
+      if (!raw || typeof raw !== "object") throw new Error("Invalid requirement mapping");
+      const requirement = raw;
+      if (typeof requirement.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(requirement.id) || requirementIds.has(requirement.id) || typeof requirement.description !== "string" || !requirement.description.trim() || requirement.description.length > 4e3 || !Array.isArray(requirement.checks) || requirement.checks.some((id) => typeof id !== "string" || !ids.has(id)) || new Set(requirement.checks).size !== requirement.checks.length) throw new Error("Requirements need unique IDs, descriptions, and references to configured checks");
+      requirementIds.add(requirement.id);
+      return { id: requirement.id, description: requirement.description.trim(), checks: [...requirement.checks] };
+    });
+  }
+  return { name: p.name.trim(), checks, ...requirements ? { requirements } : {}, ...typeof p.source === "string" ? { source: p.source.slice(0, 500) } : {}, ...typeof p.setup === "string" && p.setup.trim() ? { setup: p.setup.trim().slice(0, 4e3) } : {} };
+}
+async function detectVerificationProfile(repo, preset = "standard") {
+  if (!["lightweight", "standard", "thorough"].includes(preset)) throw new Error("Unknown verification preset");
+  const include = preset === "lightweight" ? ["typecheck", "lint", "unit"] : preset === "standard" ? ["build", "typecheck", "lint", "unit"] : ["build", "typecheck", "lint", "unit", "integration", "browser", "mutation", "visual", "accessibility"];
+  const has = (path) => existsSync(join(repo, path));
+  const checks = [];
+  if (has("package.json")) {
+    let pkg;
+    try {
+      pkg = JSON.parse(await readFile(join(repo, "package.json"), "utf8"));
+    } catch {
+      throw new Error("Cannot detect verification: package.json is not valid JSON");
+    }
+    const runner = has("pnpm-lock.yaml") ? "pnpm run" : has("yarn.lock") ? "yarn run" : has("bun.lock") || has("bun.lockb") ? "bun run" : "npm run";
+    const scripts = [["build", ["build"]], ["typecheck", ["typecheck", "check:types"]], ["lint", ["lint"]], ["unit", ["test:unit", "test"]], ["integration", ["test:integration"]], ["browser", ["test:e2e", "test:browser"]], ["mutation", ["test:mutation", "mutation"]], ["visual", ["test:visual"]], ["accessibility", ["test:a11y", "test:accessibility"]]];
+    for (const [kind, candidates] of scripts) {
+      if (!include.includes(kind)) continue;
+      const script = candidates.find((name) => typeof pkg.scripts?.[name] === "string" && String(pkg.scripts[name]).trim() && !/no test specified/i.test(String(pkg.scripts[name])));
+      if (script) checks.push({ id: kind, kind, command: `${runner} ${script}`, required: true, timeoutMs: DEFAULT_CHECK_TIMEOUT });
+    }
+    if (checks.length) return { name: preset, checks, source: "package.json" };
+  }
+  const detected = await detectCheckCommand(repo);
+  if (detected) checks.push({ id: "unit", kind: "unit", command: detected.command, required: true, timeoutMs: DEFAULT_CHECK_TIMEOUT });
+  return { name: preset, checks, source: detected?.source, setup: detected?.setup };
+}
+function diagnoseChecks(attempts, baseline) {
+  if (!attempts.length) return { diagnosis: "failed", reason: "No check attempt completed" };
+  if (attempts.some((a) => a.ok) && attempts.some((a) => !a.ok)) return { diagnosis: "flaky", reason: "The same command both passed and failed on this revision" };
+  if (attempts.every((a) => a.ok)) return { diagnosis: "passed" };
+  const reason = attempts.map(cantRunReason).find(Boolean);
+  if (reason) return { diagnosis: "environment", reason };
+  if (baseline?.ok) return { diagnosis: "regression", reason: "This check passed on the baseline revision" };
+  if (baseline && !baseline.ok && attempts.every((a) => failureFingerprint(a) === failureFingerprint(baseline))) return { diagnosis: "pre-existing", reason: "The baseline reports the same failure; this check still requires attention" };
+  return { diagnosis: "failed" };
+}
+function resultState(checks, skipped = []) {
+  if (skipped.some((c) => c.check.required)) return "blocked";
+  const required = checks.filter((c) => c.check.required);
+  if (required.some((c) => c.diagnosis === "environment")) return "blocked";
+  if (required.some((c) => c.diagnosis !== "passed")) return "needs-changes";
+  return required.length ? "verified" : "unchecked";
+}
+async function runVerification(cwd, input, opts = {}) {
+  const profile = validateVerificationProfile(input);
+  const repeats = opts.repeats ?? 1;
+  if (!Number.isInteger(repeats) || repeats < 1 || repeats > 3) throw new Error("Verification repeats must be between 1 and 3");
+  const timeoutMs = opts.timeoutMs ?? 15 * 6e4;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_SUITE_TIMEOUT) throw new Error("Verification deadline must be between 1 ms and one hour");
+  const startedAt = Date.now();
+  const checks = [];
+  const skipped = [];
+  for (const check of profile.checks) {
+    if (opts.signal?.aborted || Date.now() - startedAt >= timeoutMs) {
+      skipped.push({ check, reason: opts.signal?.aborted ? "Verification was cancelled" : "The verification deadline was reached" });
+      continue;
+    }
+    const attempts = [];
+    for (let i = 0; i < repeats; i++) {
+      const remaining = timeoutMs - (Date.now() - startedAt);
+      if (opts.signal?.aborted || remaining <= 0) break;
+      const execution = { timeoutMs: Math.min(check.timeoutMs, remaining), signal: opts.signal, container: opts.container };
+      attempts.push(await (opts.execute ? opts.execute(check, execution) : runCheck(cwd, check.command, execution)));
+    }
+    const baseline = opts.baseline?.[check.id];
+    const diagnosis = diagnoseChecks(attempts, baseline);
+    if (["unit", "integration", "browser"].includes(check.kind) && attempts.some((attempt) => attempt.tests === 0)) {
+      diagnosis.diagnosis = "failed";
+      diagnosis.reason = "The test runner reported zero executed tests";
+    }
+    checks.push({ check, attempts, baseline, ...diagnosis });
+    if (attempts.length < repeats || opts.signal?.aborted) skipped.push({ check, reason: opts.signal?.aborted ? "Verification was cancelled" : "Repeated verification did not complete before the deadline" });
+  }
+  const requirements = (opts.requirements ?? profile.requirements)?.map((r) => {
+    const missing = r.checks.filter((id) => !checks.some((c) => c.check.id === id && c.diagnosis === "passed"));
+    return { id: r.id, description: r.description, covered: r.checks.length > 0 && !missing.length, missing };
+  });
+  let state = resultState(checks, skipped);
+  if (state === "verified" && requirements?.some((r) => !r.covered)) state = "needs-changes";
+  return {
+    version: 1,
+    profile: profile.name,
+    state,
+    startedAt,
+    endedAt: Date.now(),
+    checks,
+    skipped,
+    requirements,
+    ...opts.changedFiles ? { risk: assessChangeRisk(opts.changedFiles), review: reviewCoverage(opts.changedFiles.map((f) => f.path), opts.reviewedFiles ?? []) } : {}
+  };
+}
+function assessChangeRisk(files) {
+  const reasons = /* @__PURE__ */ new Set();
+  const sensitiveFiles = [];
+  for (const f of files) {
+    const path = f.path.replaceAll("\\", "/");
+    let sensitive = false;
+    for (const [pattern, reason] of [
+      [/(^|\/)(migrations?|schema)(\/|\.)|\.sql$/i, "Database or schema changes require migration review"],
+      [/(^|[\/_-])(auth|permissions?|security|secrets?|credentials?|crypto)([\/_.-]|$)/i, "Authentication, permissions or sensitive data handling changed"],
+      [/(^|\/)(\.github\/workflows|Dockerfile|\.env)|(^|\/)(deploy|infra|terraform)(\/|\.)/i, "Execution or deployment configuration changed"]
+    ]) if (pattern.test(path)) {
+      reasons.add(reason);
+      sensitive = true;
+    }
+    if (sensitive) sensitiveFiles.push(f.path);
+  }
+  const lines = files.reduce((n, f) => n + (f.additions ?? 0) + (f.deletions ?? 0), 0);
+  if (files.length > 20 || lines > 1e3) reasons.add("Large change surface needs broader verification");
+  return { level: sensitiveFiles.length ? "high" : reasons.size || files.length > 5 ? "medium" : "low", reasons: [...reasons], sensitiveFiles };
+}
+function reviewCoverage(changed, reviewed) {
+  const normalize = (p) => p.replaceAll("\\", "/").replace(/^\.\//, "");
+  const files = [...new Set(changed.map(normalize))];
+  const seen = new Set(reviewed.map(normalize));
+  const unreviewed = files.filter((f) => !seen.has(f));
+  return { changed: files.length, reviewed: files.length - unreviewed.length, percent: files.length ? Math.round(100 * (files.length - unreviewed.length) / files.length) : 100, unreviewed };
+}
+function renderVerificationReport(report) {
+  const cell = (s) => s.replaceAll("|", "\\|").replaceAll("\n", " ");
+  const parts = [`# Verification: ${report.state}`, "", `Profile: ${cell(report.profile)} \xB7 Duration: ${((report.endedAt - report.startedAt) / 1e3).toFixed(1)}s`, "", "| Check | Required | Result | Attempts |", "| --- | --- | --- | --- |"];
+  for (const c of report.checks) parts.push(`| ${cell(c.check.title ?? c.check.id)} | ${c.check.required ? "yes" : "no"} | ${c.diagnosis} | ${c.attempts.length} |`);
+  for (const s of report.skipped) parts.push(`| ${cell(s.check.id)} | ${s.check.required ? "yes" : "no"} | skipped: ${cell(s.reason)} | 0 |`);
+  for (const c of report.checks.filter((c2) => c2.diagnosis !== "passed")) {
+    const output = failureExcerpt(c.attempts.find((a) => !a.ok)?.output ?? c.reason ?? "No output");
+    const fence = "`".repeat(Math.max(3, ...[...output.matchAll(/`+/g)].map((m) => m[0].length + 1)));
+    parts.push("", `## ${cell(c.check.id)}: ${c.diagnosis}`, "", c.reason ?? "The check did not pass.", "", fence, output, fence);
+  }
+  if (report.risk) parts.push("", `Change risk: ${report.risk.level}`, ...report.risk.reasons.map((r) => `- ${r}`));
+  if (report.review) parts.push("", `Review coverage: ${report.review.reviewed}/${report.review.changed} files (${report.review.percent}%)`, ...report.review.unreviewed.map((p) => `- Unreviewed: ${p}`));
+  if (report.requirements) parts.push("", "Requirements:", ...report.requirements.map((r) => `- ${r.covered ? "[x]" : "[ ]"} ${r.id}: ${r.description}${r.missing.length ? ` (missing: ${r.missing.join(", ")})` : ""}`));
+  return `${parts.join("\n")}
+`;
+}
+export {
+  assessChangeRisk,
+  detectVerificationProfile,
+  diagnoseChecks,
+  renderVerificationReport,
+  resultState,
+  reviewCoverage,
+  runVerification,
+  validateVerificationProfile
+};

package/src/watch.js

@@ -0,0 +1,195 @@
+import { git } from "./git.js";
+import { CODEFLOW_MARKER, failedLogs, GH_AUTH_ERROR, ghAuthStatus, githubUser, prChecks, prStatus, safeFence } from "./github.js";
+import { logWarn } from "./log.js";
+const ACTIVE = /* @__PURE__ */ new Set(["watching", "fixing", "green"]);
+const FAILURES_BEFORE_NEEDS_YOU = 3;
+const MAX_BACKOFF_MS = 30 * 6e4;
+const MAX_QUIET_MS = 10 * 6e4;
+class PrWatcher {
+  constructor(manager, intervalMs = Number(process.env.CODEFLOW_WATCH_INTERVAL_MS) || 6e4) {
+    this.manager = manager;
+    this.intervalMs = intervalMs;
+  }
+  timer;
+  polling;
+  stopped = false;
+  /** Watches whose polls are failing, by `<run id>/<branch>`; forgotten on restart. */
+  failing = /* @__PURE__ */ new Map();
+  /** Watches with nothing to do lately, by `<run id>/<branch>`; forgotten on restart. */
+  quiet = /* @__PURE__ */ new Map();
+  start() {
+    if (this.timer) return;
+    this.stopped = false;
+    this.timer = setInterval(() => void this.poll(), this.intervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+    return this.polling;
+  }
+  /** One pass over every active watch; concurrent calls share the pass in progress. `now` is for tests. */
+  poll(now) {
+    if (this.stopped) return Promise.resolve();
+    this.polling ??= this.pollAll(now).finally(() => this.polling = void 0);
+    return this.polling;
+  }
+  async pollAll(now = Date.now()) {
+    for (const run of this.manager.watchedRuns()) {
+      for (const watch of Object.values(run.watches)) {
+        if (this.stopped) return;
+        const key = `${run.id}/${watch.branch}`;
+        const failing = this.failing.get(key);
+        const retrying = watch.state === "needs-you" && !!failing;
+        if (!ACTIVE.has(watch.state) && !retrying || run.status === "running" || run.archived) {
+          if (!retrying) this.failing.delete(key);
+          this.quiet.delete(key);
+          continue;
+        }
+        if (failing && failing.nextAt > now) continue;
+        if ((this.quiet.get(key)?.nextAt ?? 0) > now) continue;
+        try {
+          this.noteQuiet(key, await this.pollOne(run, watch), now);
+          this.failing.delete(key);
+        } catch (err) {
+          this.quiet.delete(key);
+          await this.pollFailed(run, watch, key, err, now);
+        }
+      }
+    }
+  }
+  /** After a poll: `seen` is what a poll with nothing to do found (undefined when it found something). */
+  noteQuiet(key, seen, now) {
+    if (!seen) {
+      this.quiet.delete(key);
+      return;
+    }
+    const prev = this.quiet.get(key);
+    const count = prev?.seen === seen ? prev.count + 1 : 1;
+    const wait = Math.min(MAX_QUIET_MS, this.intervalMs * 2 ** Math.min(count - 1, 20));
+    this.quiet.set(key, { count, seen, nextAt: wait > this.intervalMs ? now + wait - this.intervalMs / 2 : 0 });
+  }
+  /** Count a failed poll and wait longer before the next; the third in a row hands the PR to you. */
+  async pollFailed(run, watch, key, err, now) {
+    const count = (this.failing.get(key)?.count ?? 0) + 1;
+    let error = err.message;
+    if (count === 1 || GH_AUTH_ERROR.test(error)) {
+      const auth = await ghAuthStatus(run.repo).catch(() => void 0);
+      if (auth && !auth.ok) error = `gh isn't signed in \u2014 run \`gh auth login\`${auth.message ? ` (gh auth status: ${auth.message.slice(0, 200)})` : ""}`;
+    }
+    const wait = Math.min(MAX_BACKOFF_MS, this.intervalMs * 2 ** (count - 1));
+    this.failing.set(key, { count, nextAt: now + wait, error });
+    const detail = `Couldn't check the PR ${count} time${count === 1 ? "" : "s"} in a row: ${error}`;
+    if (count >= FAILURES_BEFORE_NEEDS_YOU) {
+      if (count === FAILURES_BEFORE_NEEDS_YOU) logWarn(`PR watch on ${watch.pr} keeps failing`, { run: run.id, error });
+      this.manager.updateWatch(run.id, watch.branch, { state: "needs-you", detail, lastPolled: now });
+    } else {
+      this.manager.updateWatch(run.id, watch.branch, { detail, lastPolled: now });
+    }
+  }
+  /** One poll. Returns what it found when there was nothing to do (green, no new comments), else undefined. */
+  async pollOne(run, w) {
+    const update = (patch) => {
+      this.manager.updateWatch(run.id, w.branch, { lastPolled: Date.now(), ...patch });
+      return void 0;
+    };
+    const status = await prStatus(run.repo, w.pr);
+    if (status.state !== "OPEN") {
+      return update({ state: "closed", detail: status.state === "MERGED" ? "The pull request was merged" : "The pull request was closed" });
+    }
+    if (status.commentsTruncated) return update({ state: "needs-you", detail: "The PR has at least 1,000 inline review comments; review its complete discussion before restarting follow-through" });
+    if (w.state === "fixing" || run.status !== "done") {
+      return update({ state: "needs-you", detail: `The run is ${run.status}; resume it, then watch again` });
+    }
+    const worktree = run.worktrees.find((x) => x.branch === w.branch);
+    if (!worktree) return update({ state: "needs-you", detail: "The branch's worktree is gone" });
+    const seen = new Set(w.seenComments ?? status.comments.filter((c) => Date.parse(c.createdAt) < w.startedAt).map((c) => c.id));
+    if (!w.seenComments) {
+      this.manager.log(run.id, `Watching ${w.pr}: line comments on the diff (review threads) aren't read yet; only PR comments and review summaries reach the agent`);
+    }
+    const fresh = status.comments.filter((c) => !seen.has(c.id));
+    const seenComments = [...seen, ...fresh.map((c) => c.id)];
+    const me = await githubUser(run.repo).catch(() => "");
+    const allowed = new Set([me, ...w.allow ?? []].filter(Boolean).map((login) => login.toLowerCase()));
+    const actionable = fresh.filter((c) => !c.body.includes(CODEFLOW_MARKER) && allowed.has(c.author.toLowerCase()));
+    for (const c of fresh) {
+      if (!c.body.includes(CODEFLOW_MARKER) && !actionable.includes(c)) {
+        this.manager.log(
+          run.id,
+          `Ignored a PR comment from @${c.author} (${c.association || "no association"}): only you${w.allow?.length ? ` and ${w.allow.map((a) => `@${a}`).join(", ")}` : ""} can direct agents on this watch`,
+          "warn"
+        );
+      }
+    }
+    const synced = (await git(["merge-base", "--is-ancestor", status.headRefOid, w.branch], run.repo)).code === 0;
+    if (actionable.length) {
+      if (!synced) return update({ seenComments, state: "needs-you", detail: "The PR has commits code-flow doesn't have" });
+      if (w.fixes >= w.maxFixes) return update({ seenComments, state: "needs-you", detail: `New comments after ${w.fixes} fixes; over to you` });
+      const who = [...new Set(actionable.map((c) => `@${c.author}`))].join(", ");
+      update({ seenComments, state: "fixing", fixes: w.fixes + 1, detail: `Addressing ${actionable.length} new comment${actionable.length === 1 ? "" : "s"} from ${who}` });
+      await this.manager.followUp(run.id, {
+        kind: "comments",
+        worktree: worktree.name,
+        agent: w.agent,
+        from: `${who} on the pull request`,
+        message: actionable.map((c) => {
+          const location = c.path ? `File: ${c.path}${c.line ? `:${c.line}` : ""}${c.side ? ` (${c.side.toLowerCase()} side)` : ""}${c.outdated ? " [outdated diff]" : ""}` : "";
+          return `@${c.author}:
+${safeFence([location, c.threadId ? `Thread: ${c.threadId}` : "", c.body.trim()].filter(Boolean).join("\n\n"))}`;
+        }).join("\n\n"),
+        push: w.remoteBranch,
+        watch: w.branch,
+        trust: unattendedTrust(run)
+      });
+      return;
+    }
+    const checks = await prChecks(run.repo, w.pr);
+    const failing = checks.filter((c) => c.bucket === "fail");
+    const counts = {
+      pass: checks.filter((c) => c.bucket === "pass" || c.bucket === "skipping").length,
+      fail: failing.length,
+      pending: checks.filter((c) => c.bucket === "pending").length
+    };
+    if (counts.pending) return update({ seenComments, checks: counts, state: "watching", detail: `CI is running (${counts.pending} pending)` });
+    if (!counts.fail) {
+      update({ seenComments, checks: counts, state: "green", detail: checks.length ? "All checks pass" : "No CI checks reported" });
+      return fresh.length ? void 0 : `${status.headRefOid} ${counts.pass}/${counts.fail}/${counts.pending} ${w.startedAt}`;
+    }
+    if (w.fixedHeads.includes(status.headRefOid)) {
+      return update({ seenComments, checks: counts, state: "needs-you", detail: "CI still fails on a commit code-flow already tried to fix" });
+    }
+    if (w.fixes >= w.maxFixes) return update({ seenComments, checks: counts, state: "needs-you", detail: `CI still fails after ${w.fixes} fixes; over to you` });
+    if (!synced) return update({ seenComments, checks: counts, state: "needs-you", detail: "The PR has commits code-flow doesn't have" });
+    const logs = await failedLogs(run.repo, checks, 8e3);
+    update({
+      seenComments,
+      checks: counts,
+      state: "fixing",
+      fixes: w.fixes + 1,
+      fixedHeads: [...w.fixedHeads, status.headRefOid],
+      detail: `Fixing ${failing.map((c) => c.name).join(", ")} (fix ${w.fixes + 1} of ${w.maxFixes})`
+    });
+    await this.manager.followUp(run.id, {
+      kind: "ci-fix",
+      worktree: worktree.name,
+      agent: w.agent,
+      message: `Failing checks:
+${failing.map((c) => `- ${c.name}${c.link ? ` (${c.link})` : ""}`).join("\n")}` + (logs ? `
+
+Logs of the failed jobs:
+${safeFence(logs)}` : "\n\n(No logs available; reproduce the failure locally.)"),
+      push: w.remoteBranch,
+      watch: w.branch,
+      trust: unattendedTrust(run)
+    });
+  }
+}
+function unattendedTrust(run) {
+  return run.trust === "trusted" || run.trust === "full" ? "standard" : run.trust;
+}
+export {
+  FAILURES_BEFORE_NEEDS_YOU,
+  PrWatcher,
+  unattendedTrust
+};

package/src/work-queue.js

@@ -0,0 +1,47 @@
+class WorkQueue {
+  constructor(concurrency = 4) {
+    this.concurrency = concurrency;
+  }
+  tails = /* @__PURE__ */ new Map();
+  ready = [];
+  active = 0;
+  pending = 0;
+  bytes = 0;
+  get stats() {
+    return { active: this.active, pending: this.pending, bytes: this.bytes, keys: this.tails.size };
+  }
+  run(key, operation, bytes = 0) {
+    this.pending++;
+    this.bytes += bytes;
+    const work = (this.tails.get(key) ?? Promise.resolve()).then(async () => {
+      await new Promise((resolve) => {
+        const grant = () => {
+          this.active++;
+          resolve();
+        };
+        if (this.active < this.concurrency) grant();
+        else this.ready.push(grant);
+      });
+      try {
+        return await operation();
+      } finally {
+        this.active--;
+        this.pending--;
+        this.bytes -= bytes;
+        this.ready.shift()?.();
+      }
+    });
+    const settled = work.then(() => void 0, () => void 0);
+    this.tails.set(key, settled);
+    void settled.then(() => {
+      if (this.tails.get(key) === settled) this.tails.delete(key);
+    });
+    return work;
+  }
+  async flush(key) {
+    await Promise.all(key === void 0 ? [...this.tails.values()] : [this.tails.get(key)]);
+  }
+}
+export {
+  WorkQueue
+};

package/src/workflow-control.js

@@ -0,0 +1,83 @@
+import { planProblem } from "./patterns/auto-team-model.js";
+class TeamPlanEditError extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.status = status;
+  }
+}
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const boundedText = (value, max, empty = false) => typeof value === "string" && value.length <= max && !value.includes("\0") && (empty || !!value.trim());
+const identifiers = /^[a-z][a-z0-9-]{0,39}$/;
+const clamp = (value, fallback, min, max) => typeof value === "number" && Number.isFinite(value) ? Math.max(min, Math.min(max, Math.floor(value))) : fallback;
+function strings(value, count, maxLength, label) {
+  if (!Array.isArray(value) || value.length > count || value.some((item) => !boundedText(item, maxLength))) throw new TeamPlanEditError(`${label} must contain at most ${count} bounded, nonempty strings.`);
+  if (new Set(value).size !== value.length) throw new TeamPlanEditError(`${label} must not contain duplicates.`);
+  return [...value];
+}
+function editableTeamPlan(team) {
+  return { revision: team.revision, rationale: team.rationale, contracts: [...team.contracts], tasks: team.tasks.map(({ id, title, instructions, owner, kind, dependsOn, dependencyTypes, requirements, acceptance, paths }) => ({ id, title, instructions, owner, kind, dependsOn: [...dependsOn], ...dependencyTypes ? { dependencyTypes: { ...dependencyTypes } } : {}, requirements: [...requirements], acceptance: [...acceptance], paths: [...paths] })) };
+}
+function teamPlanPolicy(team, input) {
+  const coordinator = input.roles.coordinator?.[0];
+  if (!coordinator || !team.inventory) throw new TeamPlanEditError("The original provider inventory is unavailable; ask the coordinator for a revised plan instead.");
+  return { coordinator, pool: [...input.roles.pool ?? []], inventory: structuredClone(team.inventory), maxMembers: clamp(input.options.maxMembers, 4, 2, 6), maxTasks: clamp(input.options.maxTasks, 12, 1, 24), differentProviderReview: input.options.differentProviderReview === true };
+}
+function validateTeamPlanEdit(value, team, policy) {
+  if (team.status !== "awaiting_approval" || team.tasks.some((task) => task.status && task.status !== "pending" || (task.attempts ?? 0) > 0 || task.startedAt !== void 0 || task.finishedAt !== void 0 || task.head || task.artifacts?.length)) throw new TeamPlanEditError("This team has already started work. Edit a new pending plan instead.", 409);
+  if (!object(value) || Object.keys(value).some((key) => !["revision", "tasks", "contracts", "rationale"].includes(key))) throw new TeamPlanEditError("Only tasks, contracts and rationale may be edited. Members and requirements stay fixed.");
+  if (!Number.isSafeInteger(value.revision) || value.revision !== team.revision) throw new TeamPlanEditError("The plan changed while you were editing. Refresh the plan and merge your edits before saving.", 409);
+  if (!Array.isArray(value.tasks) || value.tasks.length < 1 || value.tasks.length > policy.maxTasks) throw new TeamPlanEditError(`Keep between 1 and ${policy.maxTasks} tasks.`);
+  const tasks = value.tasks.map((item, index) => {
+    if (!object(item) || Object.keys(item).some((key) => !["id", "title", "instructions", "owner", "kind", "dependsOn", "dependencyTypes", "requirements", "acceptance", "paths"].includes(key))) throw new TeamPlanEditError(`Task ${index + 1} contains unsupported or runtime fields.`);
+    if (typeof item.id !== "string" || !identifiers.test(item.id) || typeof item.owner !== "string" || !identifiers.test(item.owner) || !boundedText(item.title, 180) || !boundedText(item.instructions, 16e3) || !["implementation", "investigation"].includes(String(item.kind))) throw new TeamPlanEditError(`Task ${index + 1} needs a valid ID, owner, title, kind and instructions.`);
+    const dependsOn = strings(item.dependsOn, policy.maxTasks, 40, `${item.id} dependencies`);
+    let dependencyTypes;
+    if (item.dependencyTypes !== void 0) {
+      if (!object(item.dependencyTypes) || Object.keys(item.dependencyTypes).length > policy.maxTasks || Object.entries(item.dependencyTypes).some(([id, kind]) => !dependsOn.includes(id) || !["completion", "artifact", "knowledge"].includes(String(kind)))) throw new TeamPlanEditError(`${item.id} contains invalid dependency types.`);
+      dependencyTypes = { ...item.dependencyTypes };
+    }
+    return { id: item.id, title: item.title, instructions: item.instructions, owner: item.owner, kind: item.kind, dependsOn, ...dependencyTypes ? { dependencyTypes } : {}, requirements: strings(item.requirements, 48, 40, `${item.id} requirements`), acceptance: strings(item.acceptance, 16, 2e3, `${item.id} acceptance criteria`), paths: strings(item.paths, 64, 500, `${item.id} paths`), status: "pending", attempts: 0 };
+  });
+  if (!boundedText(value.rationale, 4e3, true)) throw new TeamPlanEditError("Rationale must be text of at most 4,000 characters.");
+  const plan = { requirements: structuredClone(team.requirements), members: structuredClone(team.members), tasks, contracts: strings(value.contracts, 24, 8e3, "Shared contracts"), rationale: value.rationale };
+  if (team.templateUses?.length) {
+    for (const original of team.tasks.filter((task) => team.templateUses.some((use) => task.id.startsWith(`${use.id}-`)))) {
+      const edited = tasks.find((task) => task.id === original.id);
+      if (!edited || edited.kind !== original.kind || !original.acceptance.every((item) => edited.acceptance.includes(item)) || !original.dependsOn.every((item) => edited.dependsOn.includes(item)) || !original.requirements.every((item) => edited.requirements.includes(item))) throw new TeamPlanEditError("Template tasks, dependencies and required checks must be preserved. Create a new template version to change its guarantees.");
+      if (edited.instructions !== original.instructions && !edited.instructions.startsWith(original.instructions + "\n")) throw new TeamPlanEditError("Template instructions can only be extended. Publish a new template version to replace them.");
+      if (edited.paths.some((path) => !original.paths.some((base) => base === "*" || path === base || path.startsWith(base + "/")))) throw new TeamPlanEditError("Template file ownership cannot be broadened");
+      if (original.dependsOn.some((id) => (edited.dependencyTypes?.[id] ?? "completion") !== (original.dependencyTypes?.[id] ?? "completion"))) throw new TeamPlanEditError("Preserve template dependency types");
+    }
+    if (!team.contracts.every((contract) => plan.contracts.includes(contract))) throw new TeamPlanEditError("Preserve template contracts");
+    plan.templateUses = structuredClone(team.templateUses);
+  }
+  const problem = planProblem(plan, policy);
+  if (problem) throw new TeamPlanEditError(problem);
+  return plan;
+}
+function summarizeTeamPlan(team) {
+  return `${team.rationale}
+
+Team:
+${team.members.map((member) => `- ${member.name} (${member.id}, ${member.role}) \xB7 ${member.provider}`).join("\n")}
+
+Requirements:
+${team.requirements.map((requirement) => `- ${requirement.id}: ${requirement.description}`).join("\n")}
+
+Tasks:
+${team.tasks.map((task) => `- ${task.id}: ${task.title} \u2192 ${task.owner}; depends on ${task.dependsOn.join(", ") || "nothing"}; paths ${task.paths.join(", ") || "read only"}
+  ${task.instructions}
+  Acceptance: ${task.acceptance.join("; ")}`).join("\n")}
+
+Shared contracts:
+${team.contracts.join("\n") || "None"}
+
+Limits: ${team.invocationLimit} calls; ${team.coordinationLimit} coordinator calls; ${team.maxWaves} task attempts/waves; ${team.maxRepairs} repairs.`;
+}
+export {
+  TeamPlanEditError,
+  editableTeamPlan,
+  summarizeTeamPlan,
+  teamPlanPolicy,
+  validateTeamPlanEdit
+};