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

package/src/notifications.js

@@ -0,0 +1,413 @@
+import { checksLabel } from "./run-status.js";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+import { registerPrivateEnvNames } from "./env.js";
+import { logWarn } from "./log.js";
+import { redactExport, redactText } from "./privacy.js";
+const EVENTS = ["done", "failure", "needs-attention"];
+const MAX_DELIVERIES = 200;
+const MAX_SEEN = 2e3;
+const MAX_ATTEMPTS = 3;
+const MAX_PENDING_AGE = 24 * 60 * 6e4;
+const EMPTY = () => ({ version: 1, settings: /* @__PURE__ */ Object.create(null), deliveries: [], seen: [] });
+const defaults = () => ({ enabled: false, events: [], projects: [] });
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const text = (value, max) => typeof value === "string" ? value.slice(0, max) : "";
+function notificationEvents(run) {
+  if (run.archived || run.projectTeam) return [];
+  const candidates = [];
+  if (run.endedAt && ["done", "failed", "stopped", "interrupted"].includes(run.status)) {
+    const failed = run.status !== "done" || ["Failed", "Blocked"].includes(checksLabel(run));
+    candidates.push({ event: failed ? "failure" : "done", key: `${run.id}:ended:${run.endedAt}` });
+  }
+  const attention = run.awaiting ? ["approval", run.awaiting.kind, run.awaiting.at] : run.team?.awaitingRequestId ? ["question", run.team.awaitingRequestId] : run.triage?.state === "pending" ? ["triage", run.triage.at] : run.team?.status === "blocked" ? ["blocked", run.team.gaps] : void 0;
+  if (attention) candidates.push({ event: "needs-attention", key: `${run.id}:attention:${digest(attention)}` });
+  for (const watch of Object.values(run.watches ?? {})) if (watch.state === "needs-you") candidates.push({ event: "needs-attention", key: `${run.id}:watch:${digest([watch.branch, watch.detail, watch.fixes])}` });
+  return candidates;
+}
+function validateNotificationSettings(value) {
+  if (!value || typeof value !== "object") throw new Error("Choose notification settings");
+  const raw = value;
+  if (typeof raw.enabled !== "boolean" || !Array.isArray(raw.events) || raw.events.length > 3 || raw.events.some((event) => !EVENTS.includes(event))) throw new Error("Choose valid notification events and enabled state");
+  const events = [...new Set(raw.events)];
+  if (raw.projects !== "all" && (!Array.isArray(raw.projects) || raw.projects.length > 100 || raw.projects.some((project) => typeof project !== "string" || !/^[\w-]{1,100}$/.test(project)))) throw new Error("Choose all projects or explicit project IDs");
+  const projects = raw.projects === "all" ? "all" : [...new Set(raw.projects)];
+  if (raw.enabled && (!events.length || projects !== "all" && !projects.length)) throw new Error("Enabling notifications requires an event and a project scope");
+  return { enabled: raw.enabled, events, projects };
+}
+class Notifications {
+  configs = [];
+  state = EMPTY();
+  loaded = false;
+  queue = Promise.resolve();
+  draining;
+  timer;
+  stopped = false;
+  file;
+  environment;
+  fetcher;
+  now;
+  constructor(options = {}) {
+    this.file = options.file ?? join(CODEFLOW_HOME, "notifications.json");
+    this.environment = options.environment ?? process.env;
+    this.fetcher = options.fetch ?? fetch;
+    this.now = options.now ?? Date.now;
+  }
+  async load(input) {
+    this.loaded = false;
+    this.configs = [];
+    this.state = EMPTY();
+    if (input === void 0) {
+      const content = this.environment.CODEFLOW_NOTIFICATIONS_FILE ? await readFile(this.environment.CODEFLOW_NOTIFICATIONS_FILE, "utf8") : this.environment.CODEFLOW_NOTIFICATIONS_JSON;
+      if (content && content.length > 128e3) throw new Error("Notification configuration exceeds 128 KB");
+      try {
+        input = content ? JSON.parse(content) : [];
+      } catch {
+        throw new Error("Notification configuration is not valid JSON");
+      }
+    }
+    if (!Array.isArray(input) || input.length > 20) throw new Error("Configure at most 20 notification destinations");
+    const ids = /* @__PURE__ */ new Set();
+    const configs = input.map((raw) => {
+      if (!raw || !/^[a-z][a-z0-9-]{0,63}$/.test(raw.id) || ids.has(raw.id) || !["webhook", "slack"].includes(raw.protocol)) throw new Error("Notification destinations need unique IDs and webhook or slack protocol");
+      ids.add(raw.id);
+      if (typeof raw.urlEnv !== "string" || !/^[A-Z_][A-Z0-9_]{0,99}$/.test(raw.urlEnv) || raw.secretEnv !== void 0 && (typeof raw.secretEnv !== "string" || !/^[A-Z_][A-Z0-9_]{0,99}$/.test(raw.secretEnv))) throw new Error("Notification credentials must name server environment variables");
+      return { id: raw.id, name: text(raw.name, 80) || raw.id, protocol: raw.protocol, urlEnv: raw.urlEnv, secretEnv: raw.secretEnv };
+    });
+    registerPrivateEnvNames(["CODEFLOW_NOTIFICATIONS_FILE", "CODEFLOW_NOTIFICATIONS_JSON", ...configs.flatMap((c) => [c.urlEnv, ...c.secretEnv ? [c.secretEnv] : []])]);
+    this.configs = configs;
+    const saved = await readFile(this.file, "utf8").catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    let state = EMPTY();
+    if (saved !== void 0) {
+      if (saved.length > 2 * 1024 * 1024) throw new Error("Notification state exceeds its limit; notifications remain disabled");
+      try {
+        const parsed = JSON.parse(saved);
+        if (parsed.version !== 1 || !parsed.settings || typeof parsed.settings !== "object" || !Array.isArray(parsed.deliveries) || !Array.isArray(parsed.seen)) throw new Error("Invalid state");
+        state = { version: 1, settings: /* @__PURE__ */ Object.create(null), deliveries: [], seen: parsed.seen.filter((key) => typeof key === "string" && key.length <= 200).slice(-MAX_SEEN) };
+        for (const c of configs) {
+          const value = Object.hasOwn(parsed.settings, c.id) ? parsed.settings[c.id] : void 0;
+          if (value) state.settings[c.id] = { ...validateNotificationSettings(value), destinationHash: text(value.destinationHash, 64), dropped: Number.isSafeInteger(value.dropped) && value.dropped > 0 ? value.dropped : 0, lastError: text(value.lastError, 300) || void 0 };
+        }
+        for (const value of parsed.deliveries.slice(-MAX_DELIVERIES)) {
+          if (!value || !/^notification-[a-f0-9]{24}$/.test(value.id) || !configs.some((c) => c.id === value.target) || !EVENTS.includes(value.event) || !["pending", "sending", "delivered", "failed", "cancelled"].includes(value.state) || !Number.isFinite(value.createdAt) || !Number.isFinite(value.updatedAt) || !Number.isInteger(value.attempts) || value.attempts < 0 || value.attempts > MAX_ATTEMPTS || !value.payload || value.payload.version !== 1 || value.payload.id !== value.id || value.payload.runId !== value.runId || value.payload.event !== value.event || value.payload.project !== value.project) throw new Error("Invalid delivery");
+          const delivery = {
+            id: value.id,
+            target: value.target,
+            event: value.event,
+            runId: text(value.runId, 100),
+            teamId: text(value.payload.teamId, 100) || void 0,
+            cycleId: text(value.payload.cycleId, 100) || void 0,
+            project: text(value.project, 100) || void 0,
+            state: value.state,
+            attempts: value.attempts,
+            totalAttempts: Number.isSafeInteger(value.totalAttempts) && value.totalAttempts >= value.attempts ? value.totalAttempts : value.attempts,
+            retryCount: Number.isSafeInteger(value.retryCount) && value.retryCount > 0 ? value.retryCount : 0,
+            createdAt: value.createdAt,
+            updatedAt: value.updatedAt,
+            nextAttemptAt: Number.isFinite(value.nextAttemptAt) ? value.nextAttemptAt : void 0,
+            httpStatus: Number.isInteger(value.httpStatus) && value.httpStatus >= 100 && value.httpStatus <= 599 ? value.httpStatus : void 0,
+            reason: text(value.reason, 300) || void 0,
+            manual: value.manual === true || void 0,
+            payload: this.payload(value.payload),
+            destinationHash: text(value.destinationHash, 64)
+          };
+          if (delivery.state === "sending") {
+            delivery.state = "failed";
+            delivery.reason = "Delivery outcome is unknown after restart; retry manually if needed";
+            delivery.nextAttemptAt = void 0;
+          }
+          state.deliveries.push(delivery);
+        }
+      } catch {
+        throw new Error("Notification state is damaged; notifications remain disabled and the file was preserved");
+      }
+    }
+    this.configs = configs;
+    for (const c of configs) {
+      const preference = state.settings[c.id] ?? defaults();
+      const destination = this.destination(c);
+      if (preference.enabled && (!destination || preference.destinationHash !== destination.hash)) {
+        preference.enabled = false;
+        preference.lastError = "Destination changed or is unavailable; review settings and enable again";
+      }
+      state.settings[c.id] = preference;
+    }
+    this.state = state;
+    this.loaded = true;
+  }
+  list() {
+    return this.redact(this.configs.map((c) => {
+      const destination = this.destination(c), setting = this.state.settings[c.id] ?? defaults();
+      return { id: c.id, name: c.name, protocol: c.protocol, available: this.loaded, configured: !!destination, host: destination?.url.hostname, settings: { enabled: setting.enabled, events: setting.events, projects: setting.projects }, dropped: setting.dropped ?? 0, lastError: setting.lastError };
+    }));
+  }
+  deliveries() {
+    return this.redact([...this.state.deliveries].reverse().map(({ payload: _payload, destinationHash: _hash, ...delivery }) => delivery));
+  }
+  async update(id, value) {
+    const c = this.config(id), settings = validateNotificationSettings(value), destination = this.destination(c);
+    if (settings.enabled && !destination) throw new Error("Configure a valid HTTPS destination and credentials before enabling notifications");
+    await this.mutate(() => {
+      this.state.settings[id] = { ...this.state.settings[id], ...settings, destinationHash: destination?.hash, lastError: void 0 };
+      for (const job of this.state.deliveries) if (job.target === id && job.state === "pending" && !this.allowed(job, settings)) {
+        job.state = "cancelled";
+        job.updatedAt = this.now();
+        job.reason = "Notification settings no longer allow this delivery";
+      }
+    });
+    return this.list().find((target) => target.id === id);
+  }
+  async observe(run, extraAttentionKey) {
+    if (!this.loaded || this.stopped) return { queued: 0, dropped: 0 };
+    const candidates = notificationEvents(run);
+    if (extraAttentionKey && !run.archived && !run.projectTeam) candidates.push({ event: "needs-attention", key: `${run.id}:external-attention:${digest(extraAttentionKey.slice(0, 200))}` });
+    return this.enqueue(candidates, { runId: run.id, project: run.project, pattern: run.pattern, status: run.status, result: { Passed: "verified", Failed: "needs-changes", Blocked: "blocked" }[checksLabel(run)] ?? "unchecked", title: run.task?.split("\n")[0] ?? "Run update" });
+  }
+  async observeProjectTeam(team) {
+    for (const cycle of team.cycles) {
+      const opportunities = team.opportunities.filter((o) => o.cycleId === cycle.id || o.id === cycle.opportunityId);
+      const actionable = opportunities.some((o) => ["proposed", "ready"].includes(o.status));
+      const failed = ["blocked", "failed", "unknown"].includes(cycle.status);
+      if (!failed && !(cycle.status === "completed" && actionable)) continue;
+      const event = failed ? "failure" : "needs-attention";
+      await this.enqueue([{ event, key: `${team.id}:${cycle.id}:${cycle.status}` }], { runId: "", teamId: team.id, cycleId: cycle.id, project: team.projectId, pattern: "project-team", status: cycle.status, result: failed ? "blocked" : "ready-for-review", title: `${team.name}: ${cycle.reason ?? cycle.summary ?? "An improvement is ready for review"}` });
+    }
+  }
+  async enqueue(candidates, subject) {
+    if (!this.loaded || this.stopped) return { queued: 0, dropped: 0 };
+    if (!candidates.length || !this.configs.some((c) => {
+      const settings = this.state.settings[c.id] ?? defaults();
+      const destination = this.destination(c);
+      return destination && settings.destinationHash === destination.hash && settings.enabled && candidates.some((candidate) => this.allowed({ event: candidate.event, project: subject.project }, settings) && !this.state.seen.includes(digest([c.id, candidate.event, candidate.key])));
+    })) return { queued: 0, dropped: 0 };
+    let queued = 0, dropped = 0;
+    await this.mutate(() => {
+      for (const c of this.configs) {
+        const settings = this.state.settings[c.id] ?? defaults(), destination = this.destination(c);
+        if (!destination || !settings.enabled || settings.destinationHash !== destination.hash) continue;
+        for (const candidate of candidates) {
+          const identity = digest([c.id, candidate.event, candidate.key]);
+          if (!this.allowed({ event: candidate.event, project: subject.project }, settings) || this.state.seen.includes(identity)) continue;
+          this.state.seen = [...this.state.seen, identity].slice(-MAX_SEEN);
+          if (!this.room()) {
+            dropped++;
+            settings.dropped = (settings.dropped ?? 0) + 1;
+            settings.lastError = `Notification queue is full; event for run ${subject.runId} was dropped`;
+            continue;
+          }
+          const payload = this.payload({ ...subject, version: 1, id: `notification-${randomBytes(12).toString("hex")}`, event: candidate.event });
+          this.state.deliveries.push(this.job(c, destination.hash, payload));
+          queued++;
+        }
+      }
+    });
+    if (queued) void this.drain().catch((error) => logWarn("Notification delivery could not be persisted", { error: error.message }));
+    return { queued, dropped };
+  }
+  async test(id) {
+    const c = this.config(id), destination = this.destination(c);
+    if (!destination) throw new Error("Configure a valid HTTPS destination and credentials first");
+    let delivery;
+    await this.mutate(() => {
+      if (!this.room()) throw new Error("Notification queue is full");
+      delivery = this.job(c, destination.hash, this.payload({ version: 1, id: `notification-${randomBytes(12).toString("hex")}`, event: "done", runId: "test", pattern: "test", status: "test", result: "test", title: "code-flow notification test", test: true }));
+      delivery.manual = true;
+      this.state.deliveries.push(delivery);
+    });
+    void this.drain().catch((error) => logWarn("Test notification could not be persisted", { error: error.message }));
+    return this.deliveries().find((value) => value.id === delivery.id);
+  }
+  async retry(id) {
+    await this.mutate(() => {
+      const job = this.state.deliveries.find((value) => value.id === id);
+      if (!job || job.state !== "failed") throw new Error("Only a failed notification can be retried");
+      const c = this.config(job.target), destination = this.destination(c);
+      if (!destination || !job.manual && !this.allowed(job, this.state.settings[c.id] ?? defaults())) throw new Error("Enable this destination and its event/project scope before retrying");
+      job.destinationHash = destination.hash;
+      job.attempts = 0;
+      job.retryCount = (job.retryCount ?? 0) + 1;
+      job.state = "pending";
+      job.nextAttemptAt = this.now();
+      job.updatedAt = this.now();
+      job.reason = "Explicit retry requested";
+    });
+    void this.drain().catch((error) => logWarn("Notification retry could not be persisted", { error: error.message }));
+    return this.deliveries().find((value) => value.id === id);
+  }
+  start(intervalMs = 1e4) {
+    if (this.timer || !this.loaded) return;
+    this.stopped = false;
+    this.timer = setInterval(() => void this.drain().catch((error) => logWarn("Notification retry failed", { error: error.message })), Math.max(1e3, intervalMs));
+    this.timer.unref?.();
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+    await this.draining;
+    await this.queue;
+  }
+  drain() {
+    this.draining ??= this.drainAll().finally(() => {
+      this.draining = void 0;
+    });
+    return this.draining;
+  }
+  async drainAll() {
+    if (!this.loaded || this.stopped) return;
+    for (let count = 0; count < 20; count++) {
+      if (this.stopped) return;
+      const candidate = this.state.deliveries.find((value) => value.state === "pending" && (value.nextAttemptAt ?? 0) <= this.now());
+      if (!candidate) return;
+      const claimed = await this.mutate(() => {
+        const job2 = this.state.deliveries.find((value) => value.id === candidate.id);
+        if (!job2 || job2.state !== "pending" || (job2.nextAttemptAt ?? 0) > this.now()) return void 0;
+        if (job2.attempts >= MAX_ATTEMPTS) {
+          job2.state = "failed";
+          job2.reason = "Automatic retry limit reached";
+          job2.updatedAt = this.now();
+          return void 0;
+        }
+        const c2 = this.configs.find((config) => config.id === job2.target), destination2 = c2 && this.destination(c2);
+        if (!c2 || !destination2 || destination2.hash !== job2.destinationHash || !job2.manual && !this.allowed(job2, this.state.settings[job2.target] ?? defaults()) || this.now() - (job2.nextAttemptAt ?? job2.createdAt) > MAX_PENDING_AGE) {
+          job2.state = "cancelled";
+          job2.reason = "Destination or scope changed, or this pending delivery expired";
+          job2.updatedAt = this.now();
+          return void 0;
+        }
+        job2.state = "sending";
+        job2.attempts++;
+        job2.totalAttempts = (job2.totalAttempts ?? 0) + 1;
+        job2.updatedAt = this.now();
+        job2.nextAttemptAt = void 0;
+        return { job: job2, c: c2, destination: destination2 };
+      });
+      if (!claimed) continue;
+      const { job, c, destination } = claimed;
+      let status, retryable = true, retryAfter = 3e4, delivered = false;
+      try {
+        const headers = { "content-type": "application/json", "idempotency-key": job.id };
+        if (c.secretEnv) headers.authorization = `Bearer ${this.environment[c.secretEnv]}`;
+        const message = `code-flow: ${job.event}
+${job.payload.title}
+${job.payload.teamId ? `Team ${job.payload.teamId}` : `Run ${job.runId}`} \xB7 ${job.payload.status} \xB7 ${job.payload.result}`;
+        const slackText = message.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+        const body = c.protocol === "slack" ? { text: slackText, blocks: [{ type: "section", text: { type: "plain_text", text: message, emoji: false } }], unfurl_links: false, unfurl_media: false } : job.payload;
+        const response = await this.fetcher(destination.url, { method: "POST", headers, body: JSON.stringify(body), redirect: "error", signal: AbortSignal.timeout(1e4) });
+        status = response.status;
+        retryable = status === 429 || status >= 500;
+        const retry = Number(response.headers.get("retry-after"));
+        if (Number.isFinite(retry) && retry > 0) retryAfter = Math.min(3e5, retry * 1e3);
+        await response.body?.cancel();
+        delivered = response.ok;
+      } catch {
+      }
+      if (delivered) {
+        await this.mutate(() => {
+          job.state = "delivered";
+          job.httpStatus = status;
+          job.reason = void 0;
+          job.updatedAt = this.now();
+        });
+        continue;
+      }
+      await this.mutate(() => {
+        job.httpStatus = status;
+        job.updatedAt = this.now();
+        job.reason = status ? `Destination returned HTTP ${status}` : "Connection, TLS or timeout failure";
+        if (retryable && job.attempts < MAX_ATTEMPTS) {
+          job.state = "pending";
+          job.nextAttemptAt = this.now() + Math.min(3e5, Math.max(retryAfter, 3e4 * 2 ** (job.attempts - 1)));
+        } else job.state = "failed";
+      });
+    }
+  }
+  allowed(job, settings) {
+    return settings.enabled && settings.events.includes(job.event) && (settings.projects === "all" || settings.projects.includes(job.project ?? "unassigned"));
+  }
+  config(id) {
+    const c = this.configs.find((value) => value.id === id);
+    if (!c) throw new Error("Notification destination not found");
+    return c;
+  }
+  destination(c) {
+    const value = this.environment[c.urlEnv];
+    if (!value || value.length > 4096 || c.secretEnv && !this.environment[c.secretEnv]) return void 0;
+    try {
+      const url = new URL(value);
+      if (url.protocol !== "https:" || url.username || url.password || url.hash) return void 0;
+      return { url, hash: digest([c.protocol, url.href]) };
+    } catch {
+      return void 0;
+    }
+  }
+  payload(value) {
+    return this.redact({ version: 1, id: text(value.id, 100), event: value.event, runId: text(value.runId, 100), teamId: value.teamId ? text(value.teamId, 100) : void 0, cycleId: value.cycleId ? text(value.cycleId, 100) : void 0, project: value.project ? text(value.project, 100) : void 0, pattern: text(value.pattern, 100), status: text(value.status, 100), result: text(value.result, 100), title: text(this.redact(value.title), 200), ...value.test ? { test: true } : {} });
+  }
+  redact(value) {
+    const secrets = this.configs.flatMap((c) => [this.environment[c.urlEnv], c.secretEnv ? this.environment[c.secretEnv] : void 0]).filter((secret) => !!secret && secret.length >= 8);
+    const visit = (item) => typeof item === "string" ? redactText(item, secrets) : Array.isArray(item) ? item.map(visit) : item && typeof item === "object" ? Object.fromEntries(Object.entries(item).map(([key, entry]) => [key, visit(entry)])) : item;
+    return visit(redactExport(value));
+  }
+  job(c, destinationHash, payload) {
+    const at = this.now();
+    return { id: payload.id, target: c.id, event: payload.event, runId: payload.runId, teamId: payload.teamId, cycleId: payload.cycleId, project: payload.project, state: "pending", attempts: 0, totalAttempts: 0, retryCount: 0, createdAt: at, updatedAt: at, nextAttemptAt: at, destinationHash, payload };
+  }
+  room() {
+    if (this.state.deliveries.length < MAX_DELIVERIES) return true;
+    const index = this.state.deliveries.findIndex((job) => !["pending", "sending"].includes(job.state));
+    if (index < 0) return false;
+    this.state.deliveries.splice(index, 1);
+    return true;
+  }
+  mutate(change) {
+    if (!this.loaded) return Promise.reject(new Error("Notifications are unavailable until their configuration and saved state load successfully"));
+    const operation = this.queue.then(async () => {
+      const previous = structuredClone(this.state);
+      try {
+        const result = change();
+        await this.save();
+        return result;
+      } catch (error) {
+        this.state = previous;
+        throw error;
+      }
+    });
+    this.queue = operation.catch(() => void 0);
+    return operation;
+  }
+  async save() {
+    await mkdir(dirname(this.file), { recursive: true });
+    const temporary = `${this.file}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+      const handle = await open(temporary, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(this.state) + "\n");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, this.file);
+      if (process.platform !== "win32") {
+        const directory = await open(dirname(this.file), "r");
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+      }
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+}
+export {
+  Notifications,
+  notificationEvents,
+  validateNotificationSettings
+};

package/src/patterns/auto-team-model.js

@@ -0,0 +1,230 @@
+function replacementSettings(provider, role) {
+  const configured = provider.settingsByRole?.[role];
+  const model = configured?.model || provider.model || provider.catalog?.defaultModel || provider.models?.[0]?.id || "";
+  const effort = configured?.effort ?? (model === provider.model ? provider.effort : void 0) ?? "";
+  return { model, effort };
+}
+const obj = (properties) => ({ type: "object", properties, required: Object.keys(properties), additionalProperties: false });
+const str = { type: "string" };
+const identifier = { type: "string", pattern: "^[a-z][a-z0-9-]{0,39}$", description: "Stable lowercase identifier, e.g. api, add-validation, goal; never T1 or R1" };
+const strings = { type: "array", items: str };
+const array = (items) => ({ type: "array", items });
+const member = obj({ id: identifier, name: str, role: { type: "string", enum: ["coordinator", "worker", "reviewer"] }, provider: { type: "string", description: "Exact provider ID from the supplied eligible inventory and selected pool" }, model: str, effort: str, reason: str });
+const legacyTask = obj({ id: identifier, title: str, instructions: str, owner: { type: "string", description: "An active worker member ID (or coordinator for investigation). Never the reviewer: code-flow schedules independent review automatically." }, kind: { type: "string", enum: ["implementation", "investigation"] }, dependsOn: strings, requirements: strings, acceptance: strings, paths: strings });
+const task = obj({ ...legacyTask.properties, dependencyTypes: array(obj({ taskId: identifier, kind: { type: "string", enum: ["completion", "artifact", "knowledge"] } })) });
+const subplans = array(obj({ id: { type: "string", pattern: "^[a-z][a-z0-9-]{0,27}$" }, strategy: { type: "string", enum: ["investigate-implement", "implement-verify", "bounded-repair"] }, owner: str, requirements: strings, acceptance: strings, paths: strings, dependsOn: strings, instructions: str }));
+const LEGACY_TEAM_PLAN_SCHEMA = obj({ requirements: array(obj({ id: identifier, description: str })), members: array(member), tasks: array(legacyTask), contracts: strings, rationale: str });
+const TEAM_PLAN_SCHEMA = obj({ ...LEGACY_TEAM_PLAN_SCHEMA.properties, tasks: array(task), subplans });
+const TEMPLATE_TEAM_PLAN_SCHEMA = obj({ ...TEAM_PLAN_SCHEMA.properties, templateUses: array(obj({
+  id: { type: "string", pattern: "^[a-z][a-z0-9-]{0,11}$" },
+  templateId: identifier,
+  version: { type: "integer", minimum: 1 },
+  inputs: array(obj({ name: str, value: str })),
+  assignments: array(obj({ role: str, memberId: identifier })),
+  dependsOn: strings,
+  requirements: strings,
+  instructions: str
+})) });
+const reply = obj({ requestId: str, body: str, evidence: strings });
+const TASK_OUTCOME_SCHEMA = obj({
+  taskId: str,
+  memberId: str,
+  status: { type: "string", enum: ["submitted", "needs_info", "failed"], description: "submitted means the assigned artifact is ready for engine integration and verification; it does not claim final checks or review passed" },
+  checkpoint: str,
+  handover: str,
+  artifacts: strings,
+  unresolvedRequirements: strings,
+  questions: array(obj({ id: identifier, recipient: str, body: str, blocking: { type: "boolean" } })),
+  replies: array(reply),
+  findings: array(obj({ title: str, body: str, evidence: strings, paths: strings }))
+});
+function normalizeTaskOutcomeEvidence(outcome) {
+  return { ...outcome, findings: outcome.findings.map((finding) => {
+    const urls = finding.paths.filter((path) => /^https?:\/\//i.test(path));
+    return urls.length ? { ...finding, paths: finding.paths.filter((path) => !urls.includes(path)), evidence: [.../* @__PURE__ */ new Set([...finding.evidence, ...urls])] } : finding;
+  }) };
+}
+function taskOutcomeSchema(requirementIds) {
+  return obj({ ...TASK_OUTCOME_SCHEMA.properties, unresolvedRequirements: { type: "array", items: { type: "string", enum: requirementIds }, description: "Only known IDs of unfinished implementation requirements. Use [] on submission. Pending engine commits, checks, proof and independent review belong in handover text, not here." } });
+}
+const TEAM_ANSWERS_SCHEMA = obj({ replies: array(reply), unresolved: strings });
+const LEGACY_TEAM_REVISION_SCHEMA = obj({
+  reason: str,
+  addTasks: array(legacyTask),
+  reassignments: array(obj({ taskId: str, memberId: str })),
+  retryTasks: strings,
+  contracts: strings,
+  answers: array(reply),
+  addMembers: array(member),
+  retireMembers: strings
+});
+const TEAM_REVISION_SCHEMA = obj({ ...LEGACY_TEAM_REVISION_SCHEMA.properties, addTasks: array(task), contractRequirements: strings });
+const ID = /^[a-z][a-z0-9-]{0,39}$/;
+const unique = (items) => new Set(items).size === items.length;
+const nonempty = (value) => !!value.trim();
+function pathAllowed(path) {
+  return path === "*" || !!path && path.length <= 500 && !/[\u0000-\u001f\u007f]/.test(path) && !path.startsWith("/") && !path.startsWith("-") && !path.includes("\\") && !path.split("/").some((p) => p === "." || p === ".." || p === ".git" || p === "") && !path.includes("*") && !/^[A-Za-z]:/.test(path);
+}
+function ownsPath(paths, file) {
+  return paths.some((p) => p === "*" || file === p || file.startsWith(`${p}/`));
+}
+function overlaps(a, b) {
+  return a.kind === "implementation" && b.kind === "implementation" && a.paths.some((p) => b.paths.some((q) => p === "*" || q === "*" || p === q || p.startsWith(`${q}/`) || q.startsWith(`${p}/`)));
+}
+function planProblem(plan, policy, retainedMembers = /* @__PURE__ */ new Set()) {
+  if (!plan.requirements.length || !plan.tasks.length) return "include requirements and at least one task";
+  if (plan.requirements.length > 48 || plan.contracts.length > 24 || plan.rationale.length > 4e3) return "requirements, contracts, and rationale must fit the bounded plan";
+  const activeMembers = plan.members.filter((m) => m.status !== "retired");
+  if (activeMembers.length > policy.maxMembers || activeMembers.length < 2) return `team size must be between 2 and ${policy.maxMembers}`;
+  if (plan.tasks.length > policy.maxTasks) return `the plan exceeds ${policy.maxTasks} tasks`;
+  for (const [kind, values] of [["member", plan.members], ["task", plan.tasks], ["requirement", plan.requirements]]) {
+    if (!unique(values.map((v) => v.id)) || values.some((v) => !ID.test(v.id))) return `${kind} IDs must be unique short lowercase identifiers`;
+  }
+  if (plan.requirements.some((r) => !nonempty(r.description) || r.description.length > 4e3)) return "requirements need bounded descriptions";
+  if (plan.contracts.some((c) => !nonempty(c) || c.length > 8e3)) return "contracts cannot be empty or exceed 8000 characters";
+  const coordinator = activeMembers.filter((m) => m.role === "coordinator");
+  const reviewers = activeMembers.filter((m) => m.role === "reviewer");
+  if (coordinator.length !== 1 || reviewers.length !== 1) return "include exactly one coordinator and one independent reviewer";
+  if (coordinator[0].id !== "coordinator") return "the coordinator member ID must be coordinator (preserving its planning session identity)";
+  if (coordinator[0].provider !== policy.coordinator) return "the coordinator must preserve the user's selected provider";
+  const available = policy.inventory.providers.filter((p) => p.available && !p.blockedReason && (policy.pool.includes(p.id) || p.id === policy.coordinator));
+  for (const m of activeMembers) {
+    if (m.id === "user") return "user is reserved for authenticated user replies";
+    if (m.role !== "coordinator" && !policy.pool.includes(m.provider)) return `${m.id} chose a provider outside the user's worker/reviewer pool`;
+    const provider = available.find((p) => p.id === m.provider) ?? (retainedMembers.has(m.id) ? policy.inventory.providers.find((p) => p.id === m.provider) : void 0);
+    if (!provider) return `${m.id} chose unavailable, exhausted, or unauthorized provider ${m.provider}`;
+    if (!nonempty(m.name) || m.name.length > 120 || !nonempty(m.reason) || m.reason.length > 2e3) return "every member needs a bounded name and composition reason";
+    const settings = provider.settingsByRole?.[m.role] ?? provider;
+    const model = provider.models?.find((model2) => model2.id === (m.model || provider.catalog?.defaultModel) || model2.aliases?.includes(m.model));
+    if (provider.catalog && !model) return `${m.id} chose a model whose availability in this environment is unknown`;
+    if (provider.catalog && m.effort && !model?.efforts?.includes(m.effort)) return `${m.id} chose an unsupported effort for this exact model`;
+    if (m.role === "coordinator" && (m.model !== (settings.model ?? "") || m.effort !== (settings.effort ?? ""))) return "The coordinator model settings and effort must remain unchanged";
+    const variants = m.role !== "coordinator" && "variants" in settings ? settings.variants : void 0;
+    const choices = variants?.length ? [settings, ...variants] : [settings];
+    const matching = choices.filter((choice) => variants?.length ? m.model === (choice.model ?? "") : choice.model ? m.model === choice.model : !m.model || !!model);
+    if (!matching.length) return `${m.id} must preserve supplied model settings or choose a supplied supported model (empty means default)`;
+    const efforts = model?.efforts ?? provider.efforts ?? [];
+    if (!matching.some((choice) => choice.effort ? m.effort === choice.effort : !m.effort || efforts.includes(m.effort))) return `${m.id} must preserve supplied effort settings or choose a supplied supported effort (empty means default)`;
+  }
+  for (const t of plan.tasks) {
+    const owner = plan.members.find((m) => m.id === t.owner);
+    if (!owner || owner.role === "reviewer" || owner.status === "retired" && !["submitted", "completed"].includes(t.status ?? "")) return `${t.id} must be assigned to an active non-reviewer member. The runtime supplies final independent review and checks; remove redundant final-review tasks instead of reassigning them.`;
+    if (t.kind === "implementation" && owner.role !== "worker") return `${t.id}: implementation belongs to a worker, keeping coordinator and reviewer read-only`;
+    if (!nonempty(t.title) || t.title.length > 180 || !nonempty(t.instructions) || t.instructions.length > 16e3 || !t.acceptance.length || t.acceptance.length > 16 || t.acceptance.some((a) => !nonempty(a) || a.length > 2e3)) return `${t.id} needs bounded instructions and acceptance criteria`;
+    if (!t.requirements.length || t.requirements.some((id) => !plan.requirements.some((r) => r.id === id))) return `${t.id} must cover existing requirements`;
+    if (t.dependencyTypes && (Object.keys(t.dependencyTypes).some((id) => !t.dependsOn.includes(id)) || Object.values(t.dependencyTypes).some((kind) => !["completion", "artifact", "knowledge"].includes(kind)))) return `${t.id} has invalid typed dependencies`;
+    if (!unique(t.dependsOn) || t.dependsOn.some((id) => id === t.id || !plan.tasks.some((other) => other.id === id))) return `${t.id} has an invalid dependency`;
+    if (t.paths.some((p) => !pathAllowed(p)) || t.kind === "implementation" && !t.paths.length) return `${t.id} needs safe owned repository paths (directories, files, or *)`;
+  }
+  if (plan.requirements.some((r) => !plan.tasks.some((t) => t.requirements.includes(r.id)))) return "every requirement must have a task; requirements cannot silently disappear";
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const cycle = (id) => {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+    if (plan.tasks.find((t) => t.id === id).dependsOn.some(cycle)) return true;
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  };
+  if (plan.tasks.some((t) => cycle(t.id))) return "task dependencies must be acyclic";
+  const author = plan.members.find((m) => m.id === plan.tasks.find((t) => t.kind === "implementation")?.owner) ?? coordinator[0];
+  if (reviewers[0].provider === author.provider && (policy.differentProviderReview || available.some((p) => policy.pool.includes(p.id) && p.id !== author.provider))) return "use a reviewer from another eligible provider (or disable strict provider independence when only one provider is available)";
+  return void 0;
+}
+function readyTasks(tasks, messages = [], eligible = () => true, priorities = {}) {
+  const priority = (id) => Object.hasOwn(priorities, id) && Number.isFinite(priorities[id]) ? priorities[id] : 0;
+  const selected = [];
+  for (const t of [...tasks].sort((a, b) => priority(b.id) - priority(a.id) || a.id.localeCompare(b.id))) {
+    if (t.status !== "pending" || !eligible(t)) continue;
+    if (tasks.some((active) => active.status === "running" && (active.owner === t.owner || overlaps(t, active)))) continue;
+    if (!t.dependsOn.every((id) => {
+      const dependency = tasks.find((d) => d.id === id);
+      if (!dependency) return false;
+      const kind = t.dependencyTypes?.[id] ?? "completion";
+      const finished = ["submitted", "completed"].includes(dependency.status ?? "") && !dependency.evidenceStale;
+      if (kind === "artifact") return finished && !!dependency.head && !!dependency.artifacts?.length;
+      if (kind === "knowledge" && dependency.evidenceStale) return false;
+      if (kind === "knowledge") return finished && !!dependency.artifacts?.length || messages.some((m) => m.kind === "reply" && m.sender === dependency.owner && m.recipient === t.owner && m.taskId === t.id && m.evidence.length > 0 && m.status !== "open");
+      return finished;
+    })) continue;
+    if (selected.some((other) => other.owner === t.owner || overlaps(t, other))) continue;
+    selected.push(t);
+  }
+  return selected;
+}
+function outcomeProblem(outcome, task2, member2, state) {
+  if (outcome.taskId !== task2.id || outcome.memberId !== member2.id) return "taskId and memberId must match this assignment";
+  if (!nonempty(outcome.checkpoint) || outcome.checkpoint.length > 12e3) return "include an observable checkpoint of at most 12000 characters";
+  if (!nonempty(outcome.handover) || outcome.handover.length > 8e3) return "publish a shareable handover of at most 8000 characters, separate from your private checkpoint";
+  if (outcome.questions.length > 8 || outcome.replies.length > 16 || outcome.findings.length > 6 || outcome.artifacts.length > 24) return "outcome exceeds the bounded message, artifact, or finding limit";
+  if (outcome.findings.some((f) => !f.title.trim() || f.title.length > 200 || !f.body.trim() || f.body.length > 8e3 || !f.evidence.some(nonempty) || f.paths.some((p) => !pathAllowed(p) || p === "*"))) return "findings need bounded text, evidence, and safe repository paths";
+  if (outcome.unresolvedRequirements.some((id) => !state.requirements.some((r) => r.id === id))) return "unresolved requirements must use known IDs";
+  if (outcome.status === "submitted" && outcome.unresolvedRequirements.length) return "unresolved requirements cannot be submitted as completed work";
+  if (!unique(outcome.questions.map((q) => q.id)) || outcome.questions.some((q) => !ID.test(q.id) || !nonempty(q.body) || q.body.length > 8e3)) return "questions need unique local IDs and bounded nonempty bodies";
+  if (outcome.questions.some((q) => q.recipient !== "user" && (!state.members.some((m) => m.id === q.recipient) || q.recipient === member2.id))) return "questions must address another known member or user";
+  if (outcome.replies.some((r) => !validReply(r, member2.id, state))) return "replies must answer questions addressed to this member, with evidence";
+  if (outcome.status === "needs_info" && !outcome.questions.some((q) => q.blocking) && !state.messages.some((q) => q.kind === "question" && q.taskId === task2.id && q.blocking && (q.status === "open" || q.sourceAttempt === task2.attempts))) return "needs_info requires a blocking question";
+  if (outcome.status === "submitted" && (outcome.questions.some((q) => q.blocking) || state.messages.some((q) => q.kind === "question" && q.taskId === task2.id && q.blocking && q.status === "open"))) return "a blocking question cannot accompany submitted work";
+  if (outcome.status === "submitted" && task2.kind === "investigation" && !outcome.artifacts.some(nonempty)) return "investigations need evidence-bearing artifacts";
+  return void 0;
+}
+function validReply(reply2, sender, state, coordinator = false) {
+  const question = state.messages.find((m) => m.id === reply2.requestId && m.kind === "question" && (m.status === "open" || state.messages.some((r) => r.kind === "reply" && r.requestId === m.id && r.sender === sender && r.body === reply2.body)));
+  return !!question && question.recipient !== "user" && (coordinator || question.recipient === sender) && !!reply2.body.trim() && reply2.body.length <= 8e3 && reply2.evidence.length <= 16 && reply2.evidence.some(nonempty);
+}
+function revisionProblem(revision, state, policy) {
+  const existing = new Set(state.tasks.map((t) => t.id));
+  if (revision.addTasks.some((t) => existing.has(t.id))) return "new tasks must have new IDs";
+  if (!unique(revision.reassignments.map((r) => r.taskId)) || !unique(revision.retryTasks)) return "each task may be revised only once per patch";
+  if (!unique(revision.retireMembers)) return "retire each member only once";
+  if (revision.addMembers.some((m) => m.role !== "worker" || state.members.some((old) => old.id === m.id))) return "new members need fresh IDs and must be workers; coordinator and reviewer are pinned";
+  if (state.members.length + revision.addMembers.length > policy.maxTasks + 2) return "member history exceeds the bounded replacement limit";
+  for (const id of revision.retireMembers) {
+    const member2 = state.members.find((m) => m.id === id);
+    if (!member2 || member2.role !== "worker" || member2.status === "working" || member2.status === "retired") return "only idle worker members can be retired";
+    if (state.tasks.some((t) => t.owner === id && !["submitted", "completed"].includes(t.status ?? "") && !revision.reassignments.some((r) => r.taskId === t.id && r.memberId !== id))) return "retiring a member requires handing off its unfinished assignments";
+    if (state.scheduler !== "event" && state.messages.some((m) => m.kind === "question" && m.status === "open" && m.recipient === id)) return "answer outstanding requests before retiring their recipient";
+  }
+  for (const r of revision.reassignments) {
+    const target = state.tasks.find((t) => t.id === r.taskId);
+    if (!target || ["submitted", "completed", "running"].includes(target.status ?? "")) return "only unfinished idle tasks can be reassigned";
+  }
+  for (const id of revision.retryTasks) if (!state.tasks.some((t) => t.id === id && t.status === "failed" && (t.attempts ?? 0) - (t.allocationStartAttempt ?? 0) <= state.maxRepairs)) return "only failed tasks within the repair limit can be retried";
+  if (revision.answers.some((r) => !validReply(r, "", state, true))) return "coordinator answers need an open non-user request and evidence";
+  if (revision.contractRequirements?.some((id) => !state.requirements.some((r) => r.id === id))) return "contract changes may only invalidate known requirements";
+  if (revision.contracts.some((c) => !nonempty(c))) return "contracts cannot be empty";
+  const plan = { ...state, contracts: [...state.contracts, ...revision.contracts.filter((contract) => !state.contracts.includes(contract))], members: state.members.map((m) => revision.retireMembers.includes(m.id) ? { ...m, status: "retired" } : m).concat(revision.addMembers), tasks: state.tasks.map((t) => ({ ...t, owner: revision.reassignments.find((r) => r.taskId === t.id)?.memberId ?? t.owner })).concat(revision.addTasks) };
+  const admittedOwners = /* @__PURE__ */ new Set([
+    ...revision.addTasks.map((t) => t.owner),
+    ...revision.reassignments.map((r) => r.memberId),
+    ...revision.retryTasks.map((id) => plan.tasks.find((t) => t.id === id).owner)
+  ]);
+  for (const id of admittedOwners) {
+    const member2 = plan.members.find((m) => m.id === id);
+    const provider = member2 && policy.inventory.providers.find((p) => p.id === member2.provider);
+    if (!provider?.available || provider.blockedReason) return `${id} cannot receive new or retried work while its provider is unavailable`;
+  }
+  return planProblem(plan, policy, new Set(state.members.map((m) => m.id)));
+}
+export {
+  LEGACY_TEAM_PLAN_SCHEMA,
+  LEGACY_TEAM_REVISION_SCHEMA,
+  TASK_OUTCOME_SCHEMA,
+  TEAM_ANSWERS_SCHEMA,
+  TEAM_PLAN_SCHEMA,
+  TEAM_REVISION_SCHEMA,
+  TEMPLATE_TEAM_PLAN_SCHEMA,
+  normalizeTaskOutcomeEvidence,
+  outcomeProblem,
+  overlaps,
+  ownsPath,
+  pathAllowed,
+  planProblem,
+  readyTasks,
+  replacementSettings,
+  revisionProblem,
+  taskOutcomeSchema,
+  validReply
+};