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

package/src/deferred-runs.js

@@ -0,0 +1,515 @@
+import { permissionRequirements } from "./run-permissions.js";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+import { validateAgentSettings } from "./adapters/index.js";
+import { validateAgentContainer } from "./agent-container.js";
+import { validateVerificationProfile } from "./verification.js";
+import { validateContextBudget } from "./context-budget.js";
+import { exhausted } from "./routing.js";
+import { redactText } from "./privacy.js";
+class DeferredRunConflictError extends Error {
+  constructor(current2) {
+    super("This deferred job changed. Refresh before acting on it.");
+    this.current = current2;
+  }
+  status = 409;
+}
+class DeferredRunRejectedError extends Error {
+}
+const AGENTS = ["claude", "codex", "agy"];
+const STATUSES = ["queued", "waiting-time", "waiting-provider", "claimed", "started", "failed", "unknown", "cancelled"];
+const PENDING = /* @__PURE__ */ new Set(["queued", "waiting-time", "waiting-provider"]);
+const DEFERRED_RUN_LIMITS = { active: 100, retained: 200, history: 30, attempts: 3, requestBytes: 96 * 1024, fileBytes: 32 * 1024 * 1024, futureMs: 365 * 24 * 60 * 6e4 };
+const queues = /* @__PURE__ */ new Map();
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const clone = (value) => structuredClone(value);
+function text(value, max, label) {
+  if (typeof value !== "string" || !value.trim() || value.length > max || value.includes("\0")) throw new Error(`Invalid deferred ${label}`);
+  return value.trim();
+}
+function keys(value, allowed, label) {
+  if (!object(value) || Object.keys(value).some((key) => !allowed.includes(key))) throw new Error(`Unsupported deferred ${label} fields`);
+  return value;
+}
+function record(raw, max, parse, label) {
+  if (!object(raw) || Object.keys(raw).length > max || Object.keys(raw).some((key) => !/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(key))) throw new Error(`Invalid deferred ${label}`);
+  return Object.fromEntries(Object.entries(raw).map(([key, value]) => [key, parse(value)]));
+}
+const positiveDate = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= 864e13;
+const diagnostic = (value) => redactText(String(value ?? "Unknown deferred run error")).replace(/\0/g, "").slice(0, 1e3);
+const canonical = (value) => JSON.stringify(value, (_key, item) => object(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+function sanitizeDeferredRequest(value) {
+  const raw = keys(value, ["templateRef", "permissionRequirements", "repo", "project", "projectSelection", "pattern", "task", "roles", "options", "baseRef", "branchPrefix", "parentRunId", "context", "agentSettings", "roleSettings", "loop", "trust", "allowUntrusted", "approvals", "source", "externalSourceRef"], "run request");
+  const repo = text(raw.repo, 4e3, "repository");
+  if (!isAbsolute(repo)) throw new Error("Deferred runs need an absolute repository path");
+  const roles = record(raw.roles ?? {}, 20, (value2) => {
+    if (!Array.isArray(value2) || value2.length > 6 || value2.some((agent) => agent !== "auto" && !AGENTS.includes(agent))) throw new Error("Invalid deferred provider roles");
+    return [...new Set(value2)];
+  }, "roles");
+  const options = record(raw.options ?? {}, 64, (value2) => {
+    if (typeof value2 !== "boolean" && (typeof value2 !== "number" || !Number.isFinite(value2))) throw new Error("Invalid deferred pattern option");
+    return value2;
+  }, "options");
+  const loopRaw = raw.loop === void 0 ? {} : keys(raw.loop, ["check", "setup", "copy", "maxMinutes", "maxSteps", "maxInvocations", "maxTokens", "maxCostUsd", "checkTimeoutMin", "verification", "container", "agentContainer", "contextBudget", "remoteWorker"], "loop");
+  const loop = { copy: [] };
+  for (const key of ["check", "setup"]) if (loopRaw[key] !== void 0 && loopRaw[key] !== "") loop[key] = text(loopRaw[key], 4e3, `${key} command`);
+  const bounds = { maxMinutes: [1, 720], maxSteps: [1, 200], maxInvocations: [1, 200], maxTokens: [1, 1e9], maxCostUsd: [1e-3, 1e6], checkTimeoutMin: [1, 120] };
+  for (const key of Object.keys(bounds)) if (loopRaw[key] !== void 0) {
+    const number = loopRaw[key], [min, max] = bounds[key];
+    if (typeof number !== "number" || !Number.isFinite(number) || number < min || number > max) throw new Error(`Invalid deferred ${key}`);
+    loop[key] = number;
+  }
+  if (loopRaw.remoteWorker !== void 0) loop.remoteWorker = validateWorkerSelection(loopRaw.remoteWorker);
+  if (loopRaw.verification !== void 0) loop.verification = validateVerificationProfile(loopRaw.verification);
+  if (loopRaw.contextBudget !== void 0) loop.contextBudget = validateContextBudget(loopRaw.contextBudget);
+  if (loopRaw.agentContainer !== void 0) loop.agentContainer = validateAgentContainer(loopRaw.agentContainer);
+  if (loopRaw.container !== void 0) {
+    const container = keys(loopRaw.container, ["image", "network"], "check container");
+    const image = text(container.image, 200, "container image");
+    if (!/^[\w./:@-]+$/.test(image) || image.startsWith("-")) throw new Error("Invalid deferred container image");
+    if (container.network !== void 0 && typeof container.network !== "boolean") throw new Error("Invalid deferred container network");
+    loop.container = { image, network: container.network !== false };
+  }
+  const run = { repo, pattern: text(raw.pattern, 100, "pattern"), task: text(raw.task, 24e3, "task"), roles, options, loop, trust: "safe", allowUntrusted: false, approvals: { plan: false, tools: false } };
+  if (raw.permissionRequirements !== void 0) run.permissionRequirements = permissionRequirements(raw.permissionRequirements);
+  if (raw.templateRef !== void 0) {
+    const ref = keys(raw.templateRef, ["id", "version", "inputs"], "template reference");
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(ref.id) || !Number.isSafeInteger(ref.version) || ref.version < 1) throw new Error("Invalid deferred template version");
+    run.templateRef = { id: ref.id, version: ref.version, inputs: record(ref.inputs, 24, (v) => text(v, 1e4, "template input"), "template inputs") };
+  }
+  for (const key of ["project", "baseRef", "branchPrefix", "parentRunId"]) if (raw[key] !== void 0 && raw[key] !== "") run[key] = text(raw[key], key === "project" || key === "parentRunId" ? 240 : 1e3, key);
+  if (raw.projectSelection !== void 0) {
+    if (raw.projectSelection !== "explicit" || !run.project) throw new Error("Choose an explicit project for the deferred run");
+    run.projectSelection = "explicit";
+  }
+  if (raw.agentSettings !== void 0) run.agentSettings = validateAgentSettings(raw.agentSettings);
+  if (raw.roleSettings !== void 0) run.roleSettings = record(raw.roleSettings, 20, (value2) => validateAgentSettings(value2), "role settings");
+  if (raw.context !== void 0) {
+    const context = keys(raw.context, ["paths", "attachments"], "context (attachments cannot be deferred)");
+    if (context.attachments !== void 0 && (!Array.isArray(context.attachments) || context.attachments.length)) throw new Error("Attachments cannot be deferred; remove them before queueing the run");
+    if (!Array.isArray(context.paths) || context.paths.length > 50) throw new Error("Invalid deferred context paths");
+    run.context = { paths: context.paths.map((value2) => {
+      const path = text(keys(value2, ["path"], "context path").path, 2e3, "context path").replace(/\\/g, "/");
+      if (isAbsolute(path) || path.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("Deferred context paths must stay inside the repository");
+      return { path };
+    }) };
+  }
+  if (raw.source !== void 0) {
+    const source = keys(raw.source, ["kind", "number", "ciLogs", "tool", "numbers"], "GitHub source reference");
+    if (!["issue", "pr", "alert"].includes(source.kind) || !Number.isSafeInteger(source.number) || source.number < 1) throw new Error("Invalid deferred GitHub source reference");
+    if (source.ciLogs !== void 0 && typeof source.ciLogs !== "boolean") throw new Error("Invalid deferred CI log preference");
+    run.source = { kind: source.kind, number: source.number, ...source.ciLogs !== void 0 ? { ciLogs: source.ciLogs } : {} };
+    if (source.kind === "alert") {
+      if (!["dependabot", "code-scanning"].includes(source.tool)) throw new Error("Invalid deferred alert tool");
+      run.source.tool = source.tool;
+      if (source.numbers !== void 0) {
+        if (!Array.isArray(source.numbers) || source.numbers.length > 50 || source.numbers.some((number) => !Number.isSafeInteger(number) || Number(number) < 1)) throw new Error("Invalid deferred alert references");
+        run.source.numbers = [...new Set(source.numbers)];
+      }
+    } else if (source.tool !== void 0 || source.numbers !== void 0) throw new Error("Alert fields require an alert source");
+  }
+  if (raw.externalSourceRef !== void 0) {
+    const ref = keys(raw.externalSourceRef, ["integration", "kind", "key"], "external source reference");
+    if (!["issue", "pr"].includes(ref.kind) || run.source) throw new Error("Choose one deferred source reference");
+    run.externalSourceRef = { integration: text(ref.integration, 100, "integration"), kind: ref.kind, key: text(ref.key, 240, "source key") };
+  }
+  if (Buffer.byteLength(JSON.stringify(run)) > DEFERRED_RUN_LIMITS.requestBytes) throw new Error("Deferred run configuration is too large");
+  return run;
+}
+function deferredProviderReadiness(providers, quota, installed, now = Date.now()) {
+  const blocked = providers.flatMap((provider) => {
+    const reason = installed && !installed.has(provider) ? "is not installed" : exhausted(provider, quota, now);
+    if (!reason) return [];
+    const q = quota[provider];
+    const resets = Object.values(q?.windows ?? {}).flatMap((window) => window.resetsAt && window.resetsAt > now ? [window.resetsAt] : []);
+    return [{ provider, reason, retryAt: resets.length ? Math.max(...resets) : now + 6e4 }];
+  });
+  return blocked.length ? { ready: false, reason: blocked.map((item) => `${item.provider} ${item.reason}`).join("; "), retryAt: Math.max(...blocked.map((item) => item.retryAt)) } : { ready: true };
+}
+class DeferredRuns {
+  constructor(options) {
+    this.options = options;
+    this.file = resolve(options.file ?? join(CODEFLOW_HOME, "deferred-runs.json"));
+    this.now = options.now ?? Date.now;
+  }
+  file;
+  timer;
+  ticking;
+  stopped = false;
+  loaded = false;
+  controllers = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  now;
+  async load() {
+    if (this.loaded) return;
+    await this.change((document) => {
+      for (const job of document.jobs) if (job.status === "claimed") this.transition(job, "unknown", "The application stopped after claiming this launch. Inspect existing runs before explicitly recovering it.");
+    });
+    this.loaded = true;
+  }
+  async list() {
+    await queues.get(this.file);
+    return clone((await readDocument(this.file)).jobs).sort((a, b) => b.createdAt - a.createdAt || a.id.localeCompare(b.id));
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async enqueue(raw) {
+    const run = sanitizeDeferredRequest(raw.run), now = this.now();
+    const notBefore = raw.notBefore ?? now;
+    if (!positiveDate(notBefore) || notBefore > now + DEFERRED_RUN_LIMITS.futureMs) throw new Error("Choose a deferred start within the next year");
+    if (raw.waitForProviders !== void 0 && (!Array.isArray(raw.waitForProviders) || raw.waitForProviders.length > AGENTS.length || raw.waitForProviders.some((provider) => !AGENTS.includes(provider)))) throw new Error("Choose valid providers to wait for");
+    const providers = [...new Set(raw.waitForProviders ?? [])].sort();
+    const maxAttempts = raw.maxAttempts ?? 3;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > DEFERRED_RUN_LIMITS.attempts) throw new Error("Deferred jobs permit 1\u20133 explicit launch attempts");
+    const name = raw.name === void 0 || raw.name === "" ? run.task.split("\n")[0].slice(0, 120) : text(raw.name, 120, "name");
+    const operationId = raw.operationId === void 0 ? void 0 : text(raw.operationId, 240, "operation ID");
+    const operationHash = createHash("sha256").update(canonical({ run, name, notBefore: raw.notBefore, providers, maxAttempts })).digest("hex");
+    return this.change((document) => {
+      const previous = operationId ? document.jobs.find((job2) => job2.operationId === operationId) : void 0;
+      if (previous) {
+        if (previous.operationHash !== operationHash) throw new Error("Deferred operation ID already names different content");
+        return clone(previous);
+      }
+      if (document.jobs.filter((job2) => PENDING.has(job2.status) || job2.status === "claimed" || job2.status === "unknown").length >= DEFERRED_RUN_LIMITS.active) throw new Error("Deferred queue is full; cancel or resolve older jobs first");
+      const job = { id: `d-${randomUUID()}`, revision: 1, name, run, notBefore, waitForProviders: providers, createdAt: now, updatedAt: now, status: notBefore > now ? "waiting-time" : "queued", attempts: 0, maxAttempts, history: [], ...operationId ? { operationId, operationHash } : {} };
+      this.history(job, "Explicitly queued by you");
+      document.jobs.push(job);
+      trim(document);
+      return clone(job);
+    });
+  }
+  async cancel(id, expectedRevision) {
+    const job = await this.change((document) => {
+      const job2 = current(document, id, expectedRevision);
+      if (job2.status === "started") throw new Error("This job already started. Stop its run from the run view.");
+      if (job2.status === "cancelled") return clone(job2);
+      if (job2.status === "claimed") {
+        job2.cancelRequested = true;
+        this.transition(job2, "claimed", "Cancellation requested while launching; the outcome must still be confirmed.");
+      } else this.transition(job2, "cancelled", job2.status === "unknown" ? "Queue recovery cancelled. An unknown launched run may still need to be stopped separately." : "Cancelled before launch");
+      return clone(job2);
+    });
+    this.controllers.get(id)?.abort();
+    return job;
+  }
+  async retry(id, expectedRevision, options = {}) {
+    return this.change((document) => {
+      const job = current(document, id, expectedRevision);
+      if (job.status !== "failed" && job.status !== "unknown") throw new Error("Only failed or unknown launches can be explicitly retried");
+      if (job.status === "unknown" && options.acknowledgeUnknown !== true) throw new Error("Inspect existing runs and acknowledge that retrying an unknown launch can duplicate work");
+      if (job.attempts >= job.maxAttempts) throw new Error("This deferred job reached its launch attempt limit");
+      delete job.claimId;
+      delete job.claimedAt;
+      delete job.runId;
+      delete job.cancelRequested;
+      delete job.nextCheckAt;
+      this.transition(job, "queued", "Explicit retry requested; provider availability and configuration will be checked again");
+      return clone(job);
+    });
+  }
+  /** The HTTP boundary must verify the run's persisted deferred job/claim and repository. */
+  async attach(id, expectedRevision, runId) {
+    runId = text(runId, 240, "run ID");
+    const snapshot = (await this.list()).find((job) => job.id === id);
+    if (!snapshot) throw new Error("Deferred job not found");
+    if (snapshot.revision !== expectedRevision) throw new DeferredRunConflictError(snapshot);
+    if (snapshot.status !== "unknown" || !snapshot.claimId) throw new Error("Only an unknown claimed launch can be linked");
+    if (snapshot.cancelRequested) {
+      if (!this.options.cancelRun) throw new Error("The recovered run must be cancelled before resolving this requested cancellation");
+      await bounded(this.options.cancelRun(runId), 1e4, new AbortController(), "Recovered run cancellation could not be confirmed");
+    }
+    return this.change((document) => {
+      const job = current(document, id, expectedRevision);
+      if (job.status !== "unknown" || job.claimId !== snapshot.claimId) throw new Error("Only the reviewed unknown launch can be linked");
+      job.runId = runId;
+      this.transition(job, job.cancelRequested ? "cancelled" : "started", job.cancelRequested ? "Recovered the matching run and sent its requested cancellation" : "Recovered by linking the run belonging to this exact launch claim");
+      return clone(job);
+    });
+  }
+  start(intervalMs = 5e3) {
+    if (!this.loaded) throw new Error("Load deferred runs before starting the queue");
+    if (this.timer) return;
+    if (!Number.isInteger(intervalMs) || intervalMs < 100 || intervalMs > 6e4) throw new Error("Invalid deferred queue interval");
+    this.stopped = false;
+    this.timer = setInterval(() => {
+      void this.tick().catch(() => {
+      });
+    }, intervalMs);
+    this.timer.unref?.();
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+    for (const controller of this.controllers.values()) controller.abort();
+    await this.ticking;
+    await queues.get(this.file);
+  }
+  /** At most one launch per tick. Claims are durable before the launch callback can run. */
+  tick(force = false) {
+    if (!this.loaded) return Promise.reject(new Error("Load deferred runs before checking the queue"));
+    if (this.stopped) return Promise.resolve();
+    if (this.ticking) return this.ticking;
+    const work = this.tickOnce(force).finally(() => {
+      if (this.ticking === work) this.ticking = void 0;
+    });
+    this.ticking = work;
+    return work;
+  }
+  async tickOnce(force) {
+    const jobs = (await this.list()).reverse();
+    for (const snapshot of jobs) {
+      if (!PENDING.has(snapshot.status)) continue;
+      const now = this.now();
+      if (snapshot.notBefore > now) continue;
+      if (!force && (snapshot.nextCheckAt ?? 0) > now) continue;
+      const controller = new AbortController();
+      this.controllers.set(snapshot.id, controller);
+      try {
+        let ready;
+        try {
+          ready = await bounded(this.options.ready(clone(snapshot.run), [...snapshot.waitForProviders], controller.signal), this.options.readinessTimeoutMs ?? 1e4, controller, "Provider availability check timed out");
+        } catch (error) {
+          ready = { ready: false, reason: diagnostic(error.message), retryAt: this.now() + 6e4 };
+        }
+        if (typeof ready?.ready !== "boolean") ready = { ready: false, reason: "Provider readiness returned no valid answer", retryAt: this.now() + 6e4 };
+        if (!ready.ready) {
+          await this.change((document) => {
+            const job = document.jobs.find((job2) => job2.id === snapshot.id);
+            if (!job || !PENDING.has(job.status) || job.revision !== snapshot.revision) return;
+            const reason = diagnostic(ready.reason ?? "Waiting for provider capacity");
+            job.nextCheckAt = positiveDate(ready.retryAt) && ready.retryAt > this.now() ? ready.retryAt : this.now() + 6e4;
+            this.transition(job, "waiting-provider", reason);
+          });
+          continue;
+        }
+        if (controller.signal.aborted) continue;
+        const claimed = await this.change((document) => {
+          const job = document.jobs.find((job2) => job2.id === snapshot.id);
+          if (!job || !PENDING.has(job.status) || job.revision !== snapshot.revision || job.notBefore > this.now() || job.attempts >= job.maxAttempts) return void 0;
+          job.attempts++;
+          job.claimId = randomUUID();
+          job.claimedAt = this.now();
+          delete job.nextCheckAt;
+          this.transition(job, "claimed", "Launch claim saved before execution");
+          return clone(job);
+        });
+        if (!claimed) continue;
+        const claim = { jobId: claimed.id, claimId: claimed.claimId, attempt: claimed.attempts };
+        if (controller.signal.aborted || this.stopped) {
+          await this.change((document) => {
+            const job = document.jobs.find((job2) => job2.id === claimed.id);
+            if (job?.claimId === claim.claimId && job.status === "claimed") this.transition(job, job.cancelRequested ? "cancelled" : "failed", "Launch stopped before execution began");
+          });
+          return;
+        }
+        const launch = Promise.resolve().then(() => this.options.launch(clone(claimed.run), claim, controller.signal));
+        try {
+          const receipt = await bounded(launch, this.options.launchTimeoutMs ?? 3e4, controller, "Launch receipt timed out; the run may already exist");
+          const runId = text(receipt?.runId, 240, "launch receipt");
+          const cancel = await this.change((document) => {
+            const job = document.jobs.find((job2) => job2.id === claimed.id);
+            if (!job || job.claimId !== claim.claimId || job.status !== "claimed") return false;
+            job.runId = runId;
+            this.transition(job, job.cancelRequested ? "claimed" : "started", job.cancelRequested ? "Launch completed during cancellation; stopping its run" : "Run started; open it to follow execution");
+            return job.cancelRequested === true;
+          });
+          if (cancel) {
+            if (!this.options.cancelRun) throw new Error("Launch completed during cancellation; its run must be inspected and stopped manually");
+            await bounded(this.options.cancelRun(runId), 1e4, new AbortController(), "Run cancellation could not be confirmed");
+            await this.change((document) => {
+              const job = document.jobs.find((job2) => job2.id === claimed.id);
+              if (job?.claimId === claim.claimId && job.status === "claimed") this.transition(job, "cancelled", "The launched run was sent a cancellation request");
+            });
+          }
+        } catch (error) {
+          await this.change((document) => {
+            const job = document.jobs.find((job2) => job2.id === claimed.id);
+            if (!job || job.claimId !== claim.claimId || job.status !== "claimed") return;
+            this.transition(job, error instanceof DeferredRunRejectedError ? "failed" : "unknown", diagnostic(error.message));
+          });
+          void launch.then(async (receipt) => {
+            const runId = text(receipt?.runId, 240, "late launch receipt");
+            const cancel = await this.change((document) => {
+              const job = document.jobs.find((job2) => job2.id === claimed.id);
+              if (!job) return false;
+              if (job.claimId === claim.claimId && job.status === "unknown") {
+                job.runId = runId;
+                this.transition(job, "unknown", "A late run receipt arrived. Link this run after verifying its launch claim.");
+              } else {
+                job.history = [...job.history, { id: randomUUID(), at: this.now(), status: "unknown", detail: "A late receipt arrived for an earlier launch attempt", claimId: claim.claimId, runId }].slice(-DEFERRED_RUN_LIMITS.history);
+                job.revision++;
+                job.updatedAt = this.now();
+              }
+              return job.cancelRequested === true && job.claimId === claim.claimId;
+            });
+            if (cancel && this.options.cancelRun) await this.options.cancelRun(runId);
+          }).catch(() => void 0);
+        }
+        return;
+      } finally {
+        if (this.controllers.get(snapshot.id) === controller) this.controllers.delete(snapshot.id);
+      }
+    }
+  }
+  history(job, detail) {
+    job.history = [...job.history, { id: randomUUID(), at: this.now(), status: job.status, detail: diagnostic(detail), ...job.claimId ? { claimId: job.claimId } : {}, ...job.runId ? { runId: job.runId } : {} }].slice(-DEFERRED_RUN_LIMITS.history);
+  }
+  transition(job, status, reason) {
+    job.status = status;
+    job.reason = diagnostic(reason);
+    job.revision++;
+    job.updatedAt = this.now();
+    this.history(job, reason);
+  }
+  change(mutate) {
+    const work = (queues.get(this.file) ?? Promise.resolve()).then(async () => {
+      const document = await readDocument(this.file);
+      const before = JSON.stringify(document);
+      const result = mutate(document);
+      trim(document);
+      if (JSON.stringify(document) !== before) await writeDocument(this.file, document);
+      return result;
+    });
+    const tail = work.then(() => void 0, () => void 0);
+    queues.set(this.file, tail);
+    void tail.then(() => {
+      if (queues.get(this.file) === tail) queues.delete(this.file);
+    });
+    return work.then((result) => {
+      for (const listener of this.listeners) {
+        try {
+          listener();
+        } catch {
+        }
+      }
+      return result;
+    });
+  }
+}
+function current(document, id, revision) {
+  const job = document.jobs.find((job2) => job2.id === id);
+  if (!job) throw new Error("Deferred job not found");
+  if (!Number.isSafeInteger(revision) || revision !== job.revision) throw new DeferredRunConflictError(clone(job));
+  return job;
+}
+function trim(document) {
+  if (document.jobs.length <= DEFERRED_RUN_LIMITS.retained) return;
+  const removable = document.jobs.filter((job) => ["started", "failed", "cancelled"].includes(job.status)).sort((a, b) => a.updatedAt - b.updatedAt);
+  const remove = new Set(removable.slice(0, document.jobs.length - DEFERRED_RUN_LIMITS.retained).map((job) => job.id));
+  document.jobs = document.jobs.filter((job) => !remove.has(job.id));
+}
+async function bounded(promise, timeoutMs, controller, message) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 6e4) throw new Error("Deferred callback timeout must be 1\u201360,000 ms");
+  let timer;
+  let abort;
+  try {
+    return await Promise.race([promise, new Promise((_resolve, reject) => {
+      abort = () => reject(new Error("Deferred operation was cancelled; its outcome may require review"));
+      controller.signal.addEventListener("abort", abort, { once: true });
+      if (controller.signal.aborted) abort();
+      timer = setTimeout(() => {
+        reject(new Error(message));
+        controller.abort();
+      }, timeoutMs);
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (abort) controller.signal.removeEventListener("abort", abort);
+  }
+}
+async function readDocument(file) {
+  let body;
+  try {
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const info = await handle.stat();
+      if (!info.isFile() || info.size > DEFERRED_RUN_LIMITS.fileBytes) throw new Error("queue must be a bounded regular file");
+      body = await handle.readFile("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return { version: 1, jobs: [] };
+    throw new Error(`Deferred queue cannot be read: ${error.message}`);
+  }
+  try {
+    return validateDeferredDocument(JSON.parse(body));
+  } catch (error) {
+    throw new Error(`Deferred queue cannot be read: ${error.message}`);
+  }
+}
+function validateDeferredDocument(value) {
+  const document = clone(value);
+  if (document?.version !== 1 || !Array.isArray(document.jobs) || document.jobs.length > DEFERRED_RUN_LIMITS.retained) throw new Error("invalid document");
+  const ids = /* @__PURE__ */ new Set();
+  for (const job of document.jobs) {
+    if (!object(job) || typeof job.id !== "string" || !/^d-[a-f0-9-]{36}$/.test(job.id) || ids.has(job.id) || !Number.isSafeInteger(job.revision) || job.revision < 1 || !STATUSES.includes(job.status) || !positiveDate(job.createdAt) || !positiveDate(job.updatedAt) || !positiveDate(job.notBefore) || !Number.isInteger(job.attempts) || !Number.isInteger(job.maxAttempts) || job.attempts < 0 || job.attempts > job.maxAttempts || job.maxAttempts < 1 || job.maxAttempts > 3 || !Array.isArray(job.waitForProviders) || job.waitForProviders.length > 3 || job.waitForProviders.some((provider) => !AGENTS.includes(provider)) || !Array.isArray(job.history) || job.history.length > DEFERRED_RUN_LIMITS.history) throw new Error("invalid job");
+    ids.add(job.id);
+    text(job.name, 120, "saved job name");
+    if (job.nextCheckAt !== void 0 && !positiveDate(job.nextCheckAt) || job.claimedAt !== void 0 && !positiveDate(job.claimedAt) || job.cancelRequested !== void 0 && typeof job.cancelRequested !== "boolean" || job.reason !== void 0 && (typeof job.reason !== "string" || job.reason.length > 1e3 || job.reason.includes("\0")) || job.operationId !== void 0 && (typeof job.operationId !== "string" || !job.operationId.trim() || job.operationId.length > 240) || job.operationHash !== void 0 && !/^[a-f0-9]{64}$/.test(job.operationHash)) throw new Error("invalid job metadata");
+    if (job.run?.trust !== "safe" || job.run.allowUntrusted !== false || job.run.approvals?.plan !== false || job.run.approvals?.tools !== false || !Array.isArray(job.run.loop?.copy) || job.run.loop.copy.length) throw new Error("unsafe saved run policy");
+    job.run = sanitizeDeferredRequest(job.run);
+    if (job.claimId !== void 0 && (typeof job.claimId !== "string" || !/^[a-f0-9-]{36}$/.test(job.claimId)) || ["claimed", "unknown", "started"].includes(job.status) && (!job.claimId || !job.attempts) || job.runId !== void 0 && (typeof job.runId !== "string" || job.runId.length > 240)) throw new Error("invalid claim");
+    if (job.claimId && job.claimedAt === void 0 || job.status === "started" && !job.runId) throw new Error("incomplete claim receipt");
+    for (const event of job.history) if (!object(event) || typeof event.id !== "string" || !positiveDate(event.at) || !STATUSES.includes(event.status) || typeof event.detail !== "string" || event.detail.length > 1e3) throw new Error("invalid history");
+  }
+  return document;
+}
+function disableRestoredDeferredRuns(value, now = Date.now()) {
+  if (!positiveDate(now)) throw new Error("Invalid deferred restore time");
+  const document = validateDeferredDocument(value);
+  let cancelled = 0;
+  for (const job of document.jobs) {
+    if (job.status === "started" || job.status === "cancelled") continue;
+    cancelled++;
+    job.status = "cancelled";
+    job.cancelRequested = true;
+    job.revision++;
+    job.updatedAt = now;
+    delete job.nextCheckAt;
+    job.reason = "Cancelled during backup restore. Review the configuration and explicitly enqueue a new job to execute it.";
+    job.history = [...job.history, { id: randomUUID(), at: now, status: "cancelled", detail: job.reason, ...job.claimId ? { claimId: job.claimId } : {}, ...job.runId ? { runId: job.runId } : {} }].slice(-DEFERRED_RUN_LIMITS.history);
+  }
+  return { document, cancelled };
+}
+async function writeDocument(file, document) {
+  const body = JSON.stringify(document);
+  if (Buffer.byteLength(body) > DEFERRED_RUN_LIMITS.fileBytes) throw new Error("Deferred queue storage limit reached");
+  await mkdir(dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temporary, "wx", 384);
+    try {
+      await handle.writeFile(body);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, file);
+    const folder = await open(dirname(file), "r");
+    try {
+      await folder.sync();
+    } finally {
+      await folder.close();
+    }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+import { validateWorkerSelection } from "./remote-workers/protocol.js";
+export {
+  DEFERRED_RUN_LIMITS,
+  DeferredRunConflictError,
+  DeferredRunRejectedError,
+  DeferredRuns,
+  deferredProviderReadiness,
+  disableRestoredDeferredRuns,
+  sanitizeDeferredRequest,
+  validateDeferredDocument
+};

package/src/dependency-health.js

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { doctor, checkGit } from "./doctor.js";
+import { childEnv } from "./env.js";
+import { ptyAvailable, shellProgram } from "./shell.js";
+import { findChrome } from "./snapshot.js";
+const versionLine = (text) => text.replace(/\x1b\[[0-9;]*m/g, "").split(/\r?\n/).find((line) => /\d+\.\d+/.test(line))?.slice(0, 160);
+function capture(command, args) {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout: 5e3, maxBuffer: 64 * 1024, env: childEnv() }, (error, stdout, stderr) => resolve({ ok: !error, missing: error?.code === "ENOENT", stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }));
+  });
+}
+async function optionalDependencyHealth(options = {}) {
+  const browser = options.chrome === void 0 ? findChrome() : options.chrome;
+  const [terminal, python, chrome, docker] = await Promise.all([
+    ptyAvailable(options.python, { refresh: true }),
+    capture(options.python ?? process.env.CODEFLOW_PYTHON ?? "python3", ["--version"]),
+    browser ? capture(browser, ["--version"]) : void 0,
+    capture(options.docker ?? "docker", ["--version"])
+  ]);
+  const runtime = docker.ok ? await capture(options.docker ?? "docker", ["info", "--format", "{{.ServerVersion}}"]) : void 0;
+  const daemonReady = !!runtime?.ok && /^\d+\.\d+/.test(runtime.stdout.trim());
+  return [
+    { id: "terminal", name: "Interactive terminal", installed: !python.missing, ready: terminal, path: shellProgram(), version: versionLine(python.stdout || python.stderr), detail: terminal ? "Python 3 can load the pseudo-terminal modules; interactive shells are available." : "Interactive pseudo-terminals are unavailable. The terminal can still use its line-based fallback.", ...!terminal ? { fix: "Install Python 3 with pty, termios and fcntl support, or choose its executable with CODEFLOW_PYTHON. Windows does not support this terminal helper." } : {} },
+    { id: "snapshots", name: "Browser snapshots", installed: !!browser, ready: !!chrome?.ok, ...browser ? { path: browser } : {}, ...chrome ? { version: versionLine(chrome.stdout || chrome.stderr) } : {}, detail: !browser ? "No supported local browser was found for snapshots." : chrome?.ok ? "The configured Chrome-compatible browser responds to its version probe." : "The browser file exists but its version probe failed or timed out.", ...!browser || !chrome?.ok ? { fix: "Install Chrome, Chromium, Edge or Brave, or set CODEFLOW_CHROME to its executable. The embedded preview remains available without browser snapshots." } : {} },
+    { id: "docker", name: "Optional Docker isolation", installed: !docker.missing, ready: !!docker.ok && daemonReady, ...docker.ok ? { version: versionLine(docker.stdout || docker.stderr) } : {}, detail: docker.missing ? "Docker was not found. Host CLI execution remains available." : !docker.ok ? "Docker's version probe failed or timed out." : daemonReady ? `The Docker daemon responds (${runtime.stdout.trim().slice(0, 80)}). Images and authenticated volumes must still be prepared deliberately.` : "Docker is installed, but its daemon is unavailable or access is denied.", ...!docker.ok || !daemonReady ? { fix: "Install or start Docker and check access to its daemon before choosing isolated agents. This check does not pull images or change Docker configuration." } : {} }
+  ];
+}
+async function discoverDependencies(quota = {}) {
+  const [providers, git, optional] = await Promise.all([doctor(quota), checkGit(), optionalDependencyHealth()]);
+  return { checkedAt: Date.now(), node: { version: process.version, ok: Number(process.versions.node.split(".")[0]) > 22 || Number(process.versions.node.split(".")[0]) === 22 && Number(process.versions.node.split(".")[1]) >= 13 }, git, providers, optional };
+}
+export {
+  discoverDependencies,
+  optionalDependencyHealth
+};

package/src/diff.js

@@ -0,0 +1,43 @@
+const LOW_PRIORITY = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|go\.sum|poetry\.lock|uv\.lock|composer\.lock|Gemfile\.lock|Pipfile\.lock)$|\.(min\.(js|css)|map|snap)$|(^|\/)(dist|build|vendor|node_modules|__snapshots__)\//;
+function fileName(chunk) {
+  return chunk.match(/^diff --git a\/(.+?) b\//)?.[1] ?? chunk.match(/^diff --git (\S+)/)?.[1] ?? "?";
+}
+function stat(chunk) {
+  let add = 0;
+  let del = 0;
+  for (const line of chunk.split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) add++;
+    else if (line.startsWith("-") && !line.startsWith("---")) del++;
+  }
+  return `+${add} -${del}`;
+}
+function fitDiff(full, max, base) {
+  if (full.length <= max) return full;
+  const chunks = full.split(/^(?=diff --git )/m).filter(Boolean);
+  const budget = max - Math.min(Math.floor(max / 4), 300 + chunks.length * 60);
+  const shown = /* @__PURE__ */ new Map();
+  let used = 0;
+  const order = chunks.map((c, i) => ({ c, i, low: LOW_PRIORITY.test(fileName(c)) })).sort((a, b) => Number(a.low) - Number(b.low));
+  for (const { c, i } of order) {
+    if (used + c.length > budget) continue;
+    shown.set(i, c);
+    used += c.length;
+  }
+  const big = order.find(({ i, low }) => !shown.has(i) && !low);
+  if (big && budget - used > 2e3) {
+    const room = budget - used;
+    const cut = big.c.lastIndexOf("\n", room);
+    shown.set(big.i, `${big.c.slice(0, cut > 0 ? cut : room)}
+\u2026 (the rest of ${fileName(big.c)} is cut: ${stat(big.c)} in total)
+`);
+  }
+  const omitted = order.filter(({ i }) => !shown.has(i)).map(({ c }) => `- ${fileName(c)} (${stat(c)})`);
+  const body = chunks.map((_, i) => shown.get(i) ?? "").join("");
+  if (!omitted.length) return body;
+  return body + `
+\u2026 the diff is ${full.length} characters, too long to show whole. ${omitted.length} file(s) aren't shown above; run \`git diff ${base}..HEAD -- <file>\` to read them:
+${omitted.join("\n")}`;
+}
+export {
+  fitDiff
+};