@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

package/dist/assets/.agents/aidlc/scripts/lib/loop-runtime.mjs

@@ -0,0 +1,254 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { acquireLoopLease, assertLoopPath, readLiveLease } from "./loop-lease.mjs";
+import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+
+export const DEFAULT_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600000, maxStallTurns: 2 });
+const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete"]);
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const iso = () => new Date().toISOString();
+const bounded = (value, name, max) => { const n = Number(value); if (!Number.isSafeInteger(n) || n < 1 || n > max) throw new Error(`${name} must be an integer from 1 to ${max}`); return n; };
+
+export function validateLimits(input = {}) {
+  return {
+    maxTurns: bounded(input.maxTurns ?? DEFAULT_LIMITS.maxTurns, "maxTurns", 1000),
+    turnTimeoutMs: bounded(input.turnTimeoutMs ?? DEFAULT_LIMITS.turnTimeoutMs, "turnTimeoutMs", 3600000),
+    maxStallTurns: bounded(input.maxStallTurns ?? DEFAULT_LIMITS.maxStallTurns, "maxStallTurns", 20)
+  };
+}
+
+export function validateRoot(root) {
+  const absolute = resolve(root);
+  if (!existsSync(absolute) || !statSync(absolute).isDirectory()) throw new Error(`Invalid project root: ${absolute}`);
+  for (const part of [".agents", ".agents/aidlc", ".agents/aidlc/scripts", ".agents/data"]) {
+    const path = join(absolute, part);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Invalid installed workflow path: ${path}`);
+  }
+  return absolute;
+}
+
+export const loopRecordPath = (root, taskId) => assertLoopPath(root, taskId);
+
+function validateRecord(value, taskId) {
+  if (!value || value.schemaVersion !== 1 || value.taskId !== taskId || typeof value.runId !== "string" || !value.runId || !isLoopProvider(value.agent) || !states.has(value.status) || !Number.isSafeInteger(value.iteration) || value.iteration < 0 || !Number.isSafeInteger(value.stallTurns) || value.stallTurns < 0 || (value.sessionId !== null && (typeof value.sessionId !== "string" || !value.sessionId)) || !value.limits || !value.updatedAt || Number.isNaN(Date.parse(value.updatedAt))) throw new Error(`Corrupt loop run record for ${taskId}`);
+  if (typeof value.pausedByLoop !== "boolean" || (value.stopReason !== null && typeof value.stopReason !== "string") || (value.checkpoint !== null && (typeof value.checkpoint !== "object" || Array.isArray(value.checkpoint))) || (value.status === "paused" && !value.stopReason)) throw new Error(`Corrupt loop run record for ${taskId}`);
+  validateLimits(value.limits);
+  if (value.lastFingerprint !== null && (typeof value.lastFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(value.lastFingerprint))) throw new Error(`Corrupt loop fingerprint for ${taskId}`);
+  return value;
+}
+
+export function readLoopRecord(root, taskId) {
+  const path = loopRecordPath(root, taskId);
+  try { lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+  let value;
+  try { value = JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { throw new Error(`Corrupt loop run record for ${taskId}: ${error.message}`); }
+  return validateRecord(value, taskId);
+}
+
+export function writeLoopRecord(root, record) {
+  validateRecord(record, record.taskId);
+  const path = loopRecordPath(root, record.taskId);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  let fd;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, `${JSON.stringify(record, null, 2)}\n`);
+    fsyncSync(fd);
+    closeSync(fd); fd = undefined;
+    renameSync(temporary, path);
+    const dir = openSync(dirname(path), "r"); try { fsyncSync(dir); } finally { closeSync(dir); }
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function cli(root, script, args) {
+  return execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts", script), ...args, "--root", root], { cwd: root, encoding: "utf8", timeout: 30000, maxBuffer: 2 * 1024 * 1024 });
+}
+function checkAgent(agent, root) {
+  try { execFileSync(agent, ["--version"], { cwd: root, encoding: "utf8", timeout: 5000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] }); }
+  catch (error) { throw new Error(`Agent CLI ${agent} is unavailable: ${error?.code ?? error?.message ?? "unknown error"}`); }
+}
+function envelope(root, script, args) {
+  const result = JSON.parse(cli(root, script, args));
+  if (result?.ok !== true) throw new Error(`${script} did not return a valid result`);
+  return result;
+}
+export function readCanonical(root, taskId) {
+  const next = envelope(root, "state.mjs", ["task", "next", taskId]);
+  const shown = envelope(root, "state.mjs", ["task", "show", taskId]);
+  const task = shown.result;
+  if (!task || task.id !== taskId || next.result?.id !== taskId || !next.nextAction?.classification) throw new Error(`Conflicting canonical task state for ${taskId}`);
+  return { task, action: next.nextAction };
+}
+
+function safeArtifact(root, relative) {
+  if (typeof relative !== "string" || !relative.startsWith(".agents/data/tasks/")) return null;
+  const target = resolve(root, relative);
+  if (!target.startsWith(`${root}/`)) return null;
+  let cursor = root;
+  for (const part of relative.split("/")) { cursor = join(cursor, part); try { if (lstatSync(cursor).isSymbolicLink()) return null; } catch (error) { if (error?.code !== "ENOENT") return null; } }
+  return target;
+}
+
+function worktreeSignal(root) {
+  let raw;
+  try { raw = execFileSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "buffer", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }); }
+  catch { return { kind: "unknown", reason: "git status unavailable or oversized" }; }
+  const entries = raw.toString("utf8").split("\0").filter(Boolean);
+  if (entries.length > 128) return { kind: "unknown", reason: "too many changed files" };
+  const files = [];
+  let bytes = 0;
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const status = entry.slice(0, 2);
+    let name = entry.slice(3);
+    if (/^[RC]/.test(status) || /[RC]$/.test(status)) name = entries[++i] ?? name;
+    if (name.startsWith(".agents/data/loop/")) continue;
+    const path = resolve(root, name);
+    if (!path.startsWith(`${root}/`)) return { kind: "unknown", reason: "unsafe changed path" };
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.size > 1024 * 1024 || bytes + stat.size > 4 * 1024 * 1024) return { kind: "unknown", reason: "changed file unreadable or oversized" };
+      bytes += stat.size;
+      files.push([name, status, hash(readFileSync(path))]);
+    } catch (error) {
+      if (error?.code === "ENOENT") files.push([name, status, "deleted"]);
+      else return { kind: "unknown", reason: "changed file unreadable" };
+    }
+  }
+  return { kind: "known", digest: hash(JSON.stringify(files.sort((a, b) => a[0].localeCompare(b[0])))) };
+}
+
+export function fingerprint(root, task, action) {
+  const artifacts = {};
+  for (const [key, relative] of Object.entries(task.artifacts ?? {})) {
+    const path = safeArtifact(root, relative);
+    if (!path) { artifacts[key] = "unknown"; continue; }
+    try { const stat = statSync(path); artifacts[key] = stat.size > 1024 * 1024 ? "unknown" : hash(readFileSync(path)); }
+    catch (error) { artifacts[key] = error?.code === "ENOENT" ? "missing" : "unknown"; }
+  }
+  const projection = { phase: task.phase, status: task.status, gate: task.gate, decisions: task.decisions, items: task.tasks, evidence: task.evidence, artifacts, action: { classification: action.classification, itemId: action.itemId, reason: action.reason } };
+  const tree = worktreeSignal(root);
+  return { digest: hash(JSON.stringify({ projection, tree: tree.kind === "known" ? tree.digest : null })), tree };
+}
+
+function checkpoint(task, action, signal, iteration, reason = null) {
+  return { goal: task.title.slice(0, 500), state: `${task.phase}/${task.status}/${task.gate}`, completed: task.tasks.filter((item) => item.status === "done").map((item) => item.id).slice(0, 30), observations: [`iteration ${iteration}`, `next: ${action.classification}`, `working tree: ${signal.kind}`], hypothesis: null, blockers: reason ? [reason.slice(0, 500)] : [], files: Object.values(task.artifacts ?? {}).slice(0, 10), links: [], nextAction: { classification: action.classification, phase: action.phase, gate: action.gate, itemId: action.itemId, reason: action.reason }, capturedAt: iso() };
+}
+export const classifyAction = (action) => {
+  if (!["run_phase", "await_user", "blocked", "terminal", "complete"].includes(action?.classification)) throw new Error(`Unknown nextAction classification: ${action?.classification}`);
+  return action.classification;
+};
+
+function approvalCount(task) { return task.evidence.filter((item) => item.kind === "approval" && item.result === "pass").length; }
+function outputStop(record, action, gateView) { return { taskId: record.taskId, runId: record.runId, status: record.status, iteration: record.iteration, sessionId: record.sessionId, stopReason: record.stopReason, nextAction: action, ...(gateView ? { gateView } : {}) }; }
+
+export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, onEvent = () => {}, preflight = false, precondition }) {
+  const root = validateRoot(rootInput);
+  let record = readLoopRecord(root, taskId);
+  if (mode === "run") {
+    if (record) throw new Error(`Loop record already exists for ${taskId}; use resume`);
+    if (!isLoopProvider(agent)) throw new Error(`--agent must be ${LOOP_PROVIDER_LIST}`);
+  } else if (mode === "resume") {
+    if (!record) throw new Error(`No loop record for ${taskId}; use run`);
+    if (["complete", "terminal"].includes(record.status)) throw new Error(`Cannot resume ${record.status} loop`);
+    if (agent && agent !== record.agent) throw new Error("Resume must use the recorded agent");
+    if (record.status === "running" && !record.sessionId) throw new Error("Interrupted run has no captured session id; inspect canonical task state before starting a new run");
+  } else throw new Error(`Invalid loop mode: ${mode}`);
+  const limits = validateLimits({ ...(record?.limits ?? {}), ...(limitInput ?? {}) });
+  if (preflight) checkAgent(record?.agent ?? agent, root);
+  if (!record) record = { schemaVersion: 1, taskId, runId: randomUUID(), agent, status: "running", sessionId: null, iteration: 0, stallTurns: 0, limits, lastFingerprint: null, checkpoint: null, stopReason: null, pausedByLoop: false, updatedAt: iso() };
+  else { const prior = { iteration: record.iteration, status: record.status, stopReason: record.stopReason, limits: record.limits }; record.limits = limits; record.stallTurns = 0; onEvent({ type: "resume", prior }); }
+  const release = acquireLoopLease(root, taskId, record.runId);
+  try {
+    let current = readCanonical(root, taskId);
+    if (precondition) {
+      const expectedHash = hash(JSON.stringify(current.task));
+      const evidenceHash = hash(JSON.stringify(current.task.evidence));
+      if (precondition.taskId !== taskId || precondition.phase !== current.task.phase || precondition.taskHash !== expectedHash || precondition.evidenceHash !== evidenceHash || precondition.evidenceCount !== current.task.evidence.length || current.task.status !== "active" || current.action.classification !== "run_phase") throw new Error("Supervisor precondition changed before acquiring loop lease");
+    }
+    if (mode === "resume" && current.task.status === "paused") {
+      if (!record.pausedByLoop || current.task.handoff) throw new Error("Task was paused outside this loop; explicit user handling is required");
+      current = readCanonical(root, taskId);
+      if (current.task.status !== "paused") throw new Error("Task state changed during resume");
+      envelope(root, "state.mjs", ["task", "status", taskId, "--status", "active"]);
+      record.pausedByLoop = false;
+      current = readCanonical(root, taskId);
+    }
+    const initial = fingerprint(root, current.task, current.action);
+    if (mode === "resume" && record.lastFingerprint && record.lastFingerprint !== initial.digest) onEvent({ type: "context_changed", message: "Canonical task context changed since the last checkpoint; continuing from fresh nextAction", previousCheckpointAt: record.checkpoint?.capturedAt ?? null });
+    record.lastFingerprint = initial.digest;
+    record.checkpoint = checkpoint(current.task, current.action, initial.tree, record.iteration);
+    record.status = "running"; record.stopReason = null; record.updatedAt = iso(); writeLoopRecord(root, record);
+    for (;;) {
+      const kind = classifyAction(current.action);
+      if (kind !== "run_phase") {
+        record.status = kind === "await_user" ? "gate" : kind;
+        record.stopReason = current.action.reason ?? kind;
+        record.updatedAt = iso(); writeLoopRecord(root, record);
+        const gateView = kind === "await_user" ? cli(root, "gate-view.mjs", [taskId]).trim() : undefined;
+        return outputStop(record, current.action, gateView);
+      }
+      if (record.iteration >= limits.maxTurns) return pause("turn limit reached");
+      let prompt;
+      try {
+        const packet = JSON.parse(cli(root, "context.mjs", [taskId, "--phase", current.action.phase, ...(current.action.itemId ? ["--item", current.action.itemId] : []), "--format", "json"]));
+        if (typeof packet?.content !== "string" || !packet.content.trim()) throw new Error("Context packet was empty or invalid");
+        prompt = packet.content;
+      } catch {
+        // No driver has started for this turn, so it is safe to resume after repairing context.
+        // Do not persist arbitrary subprocess output or malformed context in the stop reason.
+        return pause("context packet generation or validation failed; inspect context.mjs and resume after repair");
+      }
+      const beforeApprovals = approvalCount(current.task);
+      let observedId = record.sessionId;
+      try {
+        const result = await driver({ agent: record.agent, root, sessionId: record.sessionId ?? undefined, prompt: `${prompt}\n\nLoop supervisor: complete the current authorized phase or item. Use canonical lifecycle commands for evidence and gates. Never approve a human gate. Stop at a gate and report progress.`, timeoutMs: limits.turnTimeoutMs, onSessionId: (id) => { if (typeof id !== "string" || !id) throw new Error("Invalid agent session id"); observedId = id; record.sessionId = id; record.updatedAt = iso(); writeLoopRecord(root, record); }, onEvent: (event) => { onEvent(event); if (event?.type === "lifecycle_command") { const observed = readCanonical(root, taskId); const signal = fingerprint(root, observed.task, observed.action); record.checkpoint = checkpoint(observed.task, observed.action, signal.tree, record.iteration); record.updatedAt = iso(); writeLoopRecord(root, record); } } });
+        if (!observedId && result?.sessionId) { observedId = result.sessionId; record.sessionId = observedId; record.updatedAt = iso(); writeLoopRecord(root, record); }
+        if (!observedId) throw new Error("Agent turn ended without a resumable session id");
+      } catch (error) {
+        current = readCanonical(root, taskId);
+        if (classifyAction(current.action) === "await_user") continue;
+        return pause(`agent transport failure: ${error.message}`);
+      }
+      const refreshed = readCanonical(root, taskId);
+      if (approvalCount(refreshed.task) !== beforeApprovals) return pause("Approval evidence changed during an agent turn");
+      const signal = fingerprint(root, refreshed.task, refreshed.action);
+      record.iteration += 1;
+      record.stallTurns = signal.digest === record.lastFingerprint ? record.stallTurns + 1 : 0;
+      record.lastFingerprint = signal.digest;
+      record.checkpoint = checkpoint(refreshed.task, refreshed.action, signal.tree, record.iteration);
+      record.updatedAt = iso(); writeLoopRecord(root, record);
+      current = refreshed;
+      if (classifyAction(current.action) === "run_phase" && record.stallTurns >= limits.maxStallTurns) return pause(`${record.stallTurns} consecutive turns without observable progress`);
+    }
+    function pause(reason) {
+      const fresh = readCanonical(root, taskId);
+      record.status = "paused"; record.stopReason = reason;
+      if (fresh.task.status === "active" && classifyAction(fresh.action) === "run_phase") {
+        envelope(root, "state.mjs", ["task", "status", taskId, "--status", "paused", "--mode", "audited", "--reason", reason, "--source", `loop run ${record.runId}`]);
+        record.pausedByLoop = true;
+      }
+      const stopped = readCanonical(root, taskId);
+      const signal = fingerprint(root, stopped.task, stopped.action);
+      record.lastFingerprint = signal.digest;
+      record.checkpoint = checkpoint(stopped.task, stopped.action, signal.tree, record.iteration, reason);
+      record.updatedAt = iso(); writeLoopRecord(root, record);
+      return outputStop(record, stopped.action);
+    }
+  } finally { release(); }
+}
+
+export function loopStatus(rootInput, taskId) {
+  const root = validateRoot(rootInput);
+  const record = readLoopRecord(root, taskId);
+  const current = readCanonical(root, taskId);
+  return { record, liveLease: readLiveLease(root, taskId), nextAction: current.action };
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-supervisor-local.mjs

@@ -0,0 +1,131 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertLoopPath } from "./loop-lease.mjs";
+import { validateRoot } from "./loop-runtime.mjs";
+import { acquireStateLock, loadTask, nextAction } from "./store.mjs";
+import { recoverLeadArtifact } from "./loop-lead-artifacts.mjs";
+
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const checkAuthority = (authority) => { if (authority !== "local") throw new Error("local supervisor adapter requires local authority"); };
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };
+const wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function readLease(path, taskId) {
+  try {
+    const lease = JSON.parse(readFileSync(path, "utf8"));
+    if (lease?.taskId !== taskId || !Number.isSafeInteger(lease.pid) || lease.pid < 1 || typeof lease.token !== "string" || !lease.token) throw new Error("invalid fields");
+    return lease;
+  } catch (error) { if (error?.code === "ENOENT") return null; throw new Error(`Corrupt supervisor lease for ${taskId}: ${error.message}`); }
+}
+
+function writeExclusive(path, value) {
+  const fd = openSync(path, "wx", 0o600);
+  try { writeFileSync(fd, `${JSON.stringify(value)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+/** Local durable checkpoint + separate PID-fenced supervisor lock.
+ * The lock uses a distinct task key from the runner's lease so humans can approve.
+ * This adapter intentionally does not implement runTurn or perform approvals.
+ */
+export function createLocalSupervisorAdapter({ root: rootInput, taskId }) {
+  const root = validateRoot(rootInput);
+  const checkpointPath = assertLoopPath(root, taskId, ".supervisor.json");
+  const leasePath = assertLoopPath(root, taskId, ".supervisor.lease");
+  const guardPath = assertLoopPath(root, taskId, ".supervisor.guard");
+  let token;
+  const withGuard = (action) => {
+    assertLoopPath(root, taskId, ".supervisor.guard");
+    mkdirSync(dirname(guardPath), { recursive: true });
+    const guard = { taskId, pid: process.pid, token: randomUUID() }, deadline = Date.now() + 5000;
+    for (;;) {
+      try { writeExclusive(guardPath, guard); break; }
+      catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        const existing = readLease(guardPath, taskId);
+        if (!existing) continue;
+        if (!alive(existing.pid)) { if (readLease(guardPath, taskId)?.token === existing.token) { try { unlinkSync(guardPath); } catch (e) { if (e?.code !== "ENOENT") throw e; } } continue; }
+        if (Date.now() >= deadline) throw new Error(`Timed out waiting for supervisor guard: ${taskId}`);
+        wait(10);
+      }
+    }
+    try { return action(); } finally { if (readLease(guardPath, taskId)?.token === guard.token) unlinkSync(guardPath); }
+  };
+  const checkScope = (input) => { checkAuthority(input?.authority); if (input?.taskId !== taskId) throw new Error("supervisor task mismatch"); };
+  const assertOwned = async () => {
+    assertLoopPath(root, taskId, ".supervisor.lease");
+    const current = readLease(leasePath, taskId);
+    if (!token || !current || current.token !== token || current.pid !== process.pid) throw new Error("local supervisor ownership lost");
+  };
+  const readCheckpoint = () => {
+    assertLoopPath(root, taskId, ".supervisor.json");
+    try {
+      const value = JSON.parse(readFileSync(checkpointPath, "utf8"));
+      if (!value || value.version !== 1 || value.taskId !== taskId || value.authority !== "local") throw new Error("wrong task or authority");
+      return value;
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw new Error(`Corrupt supervisor checkpoint for ${taskId}: ${error.message}`);
+    }
+  };
+  const syncDir = () => { const dir = openSync(dirname(checkpointPath), "r"); try { fsyncSync(dir); } finally { closeSync(dir); } };
+  return {
+    async acquireSupervisor(input) {
+      checkScope(input);
+      if (token) throw new Error("local supervisor adapter is already acquired");
+      if (input.signal?.aborted) throw new Error("supervisor already aborted");
+      const newToken = randomUUID();
+      withGuard(() => {
+        assertLoopPath(root, taskId, ".supervisor.lease");
+        const existing = readLease(leasePath, taskId);
+        if (existing && alive(existing.pid)) throw new Error(`Task ${taskId} already has a live supervisor (pid ${existing.pid})`);
+        if (existing && readLease(leasePath, taskId)?.token === existing.token) unlinkSync(leasePath);
+        writeExclusive(leasePath, { taskId, pid: process.pid, token: newToken });
+      });
+      token = newToken;
+      return { assertOwned, release: async () => { if (token !== newToken) return; withGuard(() => { if (readLease(leasePath, taskId)?.token === newToken) unlinkSync(leasePath); }); token = undefined; } };
+    },
+    async readTask(input) {
+      checkScope({ ...input, authority: "local" });
+      const release = acquireStateLock(root);
+      try {
+        if (token) await assertOwned();
+        const task = loadTask(root, taskId);
+        if (!task || task.id !== taskId) throw new Error("invalid local canonical task snapshot");
+        if (token) {
+          await recoverLeadArtifact({ root, taskId, task, assertOwned });
+          await assertOwned();
+        } else {
+          const journal = join(root, ".agents", "data", "tasks", taskId, ".lead-artifact-journal.json");
+          try { lstatSync(journal); throw new Error("Pending lead artifact journal requires supervised recovery"); }
+          catch (error) { if (error?.code !== "ENOENT") throw error; }
+        }
+        return { task, nextAction: nextAction(task, root) };
+      } finally { release(); }
+    },
+    async loadCheckpoint(input) { checkScope(input); await assertOwned(); return readCheckpoint(); },
+    async saveCheckpoint(input) {
+      checkScope(input); await assertOwned();
+      if (!input.checkpoint || input.checkpoint.taskId !== taskId || input.checkpoint.authority !== "local") throw new Error("invalid local checkpoint");
+      if (!same(readCheckpoint(), input.previous ?? null)) throw new Error("supervisor checkpoint conflict");
+      mkdirSync(dirname(checkpointPath), { recursive: true });
+      const temporary = `${checkpointPath}.tmp-${process.pid}-${randomUUID()}`;
+      let fd;
+      try {
+        fd = openSync(temporary, "wx", 0o600); writeFileSync(fd, `${JSON.stringify(input.checkpoint)}\n`); fsyncSync(fd); closeSync(fd); fd = undefined;
+        await assertOwned();
+        if (!same(readCheckpoint(), input.previous ?? null)) throw new Error("supervisor checkpoint conflict");
+        renameSync(temporary, checkpointPath); syncDir();
+      } finally {
+        if (fd !== undefined) closeSync(fd);
+        if (existsSync(temporary)) unlinkSync(temporary);
+      }
+    },
+    async clearCheckpoint(input) {
+      checkScope(input); await assertOwned();
+      const current = readCheckpoint();
+      if (!same(current, input.checkpoint)) throw new Error("supervisor checkpoint conflict");
+      if (current) { unlinkSync(checkpointPath); syncDir(); }
+    }
+  };
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-supervisor-run-local.mjs

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { requireLocalAuthority } from "./authority.mjs";
+import { runAgentTurn, isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { readLoopRecord, runLoop, validateRoot } from "./loop-runtime.mjs";
+import { runSupervisor } from "./loop-supervisor.mjs";
+import { createLocalSupervisorAdapter } from "./loop-supervisor-local.mjs";
+
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+/**
+ * Bind the canonical local store, distinct supervisor lease and the existing
+ * leased runner. The caller owns process supervision and human gate approval.
+ * Abort stops polling or the next turn; the current runLoop call is bounded by
+ * its existing timeouts and is not cancelled by this wrapper.
+ */
+export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limits, driver = runAgentTurn, preflight = true, pollMs, signal, onEvent = () => {}, runner = runLoop } = {}) {
+  requireLocalAuthority();
+  const root = validateRoot(rootInput);
+  if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
+  if (typeof driver !== "function" || typeof runner !== "function" || typeof onEvent !== "function") throw new Error("invalid local supervisor callbacks");
+  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const getRecord = () => readLoopRecord(root, taskId);
+  const execute = async (mode) => {
+    requireLocalAuthority();
+    const record = getRecord();
+    if (mode === "run" && record) throw new Error("Local loop record already exists; use resume");
+    if (mode === "resume" && !record) throw new Error("Local loop record missing; use start");
+    if (record && record.agent !== agent) throw new Error("Resume must use the recorded lead agent");
+    let nextMode = mode;
+    return runSupervisor({ taskId, authority: "local", ...adapter, pollMs, signal, onEvent,
+      runTurn: async ({ precondition }) => {
+        if (signal?.aborted) return { status: "stopped", taskId };
+        requireLocalAuthority();
+        let expected = precondition;
+        if (!expected) {
+          const snapshot = await adapter.readTask({ taskId });
+          if (snapshot.task.status !== "active" || snapshot.nextAction.classification !== "run_phase") return { status: "blocked", taskId, reason: "Canonical state changed before runner acquired lease" };
+          expected = { taskId, phase: snapshot.task.phase, taskHash: digest(snapshot.task), evidenceHash: digest(snapshot.task.evidence), evidenceCount: snapshot.task.evidence.length };
+        }
+        const result = await runner({ root, taskId, agent, mode: nextMode, limits, driver, preflight, precondition: expected, onEvent });
+        nextMode = "resume";
+        return result;
+      }
+    });
+  };
+  return {
+    start: () => execute("run"),
+    resume: () => execute("resume"),
+    async status() {
+      requireLocalAuthority();
+      const snapshot = await adapter.readTask({ taskId });
+      return { taskId, authority: "local", record: getRecord(), nextAction: snapshot.nextAction };
+    }
+  };
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-supervisor.mjs

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const TARGET = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const required = (value, name) => { if (typeof value !== "function") throw new Error(`${name} is required`); return value; };
+const validId = (value, name) => { if (typeof value !== "string" || !ID.test(value)) throw new Error(`invalid ${name}`); };
+
+function validateSnapshot(snapshot, taskId) {
+  if (!snapshot || snapshot.task?.id !== taskId || !Array.isArray(snapshot.task.evidence) || !snapshot.nextAction || !["run_phase", "await_user", "blocked", "terminal", "complete"].includes(snapshot.nextAction.classification)) throw new Error("invalid canonical task snapshot");
+  return snapshot;
+}
+
+/** Checkpoints contain a digest, not the task evidence or user-provided approval text. */
+export function makeGateCheckpoint({ taskId, authority, snapshot, result }) {
+  validId(taskId, "task ID");
+  if (!["local", "fleet"].includes(authority)) throw new Error("invalid authority");
+  validateSnapshot(snapshot, taskId);
+  const gate = result?.gate ?? result?.nextAction?.gate;
+  if (!TARGET[gate] || snapshot.task.gate !== gate || snapshot.task.status !== "blocked_on_user" || snapshot.nextAction.classification !== "await_user" || (result.taskId && result.taskId !== taskId)) throw new Error("gate changed before supervisor checkpoint; inspect state manually");
+  if (authority === "fleet" && (!result.snapshotId || !Number.isSafeInteger(snapshot.revision))) throw new Error("fleet gate requires snapshot ID and revision");
+  return { version: 1, taskId, authority, gate, phase: snapshot.task.phase, taskHash: hash(snapshot.task), evidenceCount: snapshot.task.evidence.length, evidenceHash: hash(snapshot.task.evidence), ...(authority === "fleet" ? { snapshotId: result.snapshotId, revision: snapshot.revision } : {}) };
+}
+
+/** Return wait/resume/blocked only from fresh canonical state, never grant approval. */
+export async function checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApproval, verifyLocalApproval }) {
+  if (!checkpoint || checkpoint.version !== 1 || !TARGET[checkpoint.gate] || !["local", "fleet"].includes(checkpoint.authority) || !Number.isSafeInteger(checkpoint.evidenceCount) || checkpoint.evidenceCount < 0 || typeof checkpoint.evidenceHash !== "string" || typeof checkpoint.taskHash !== "string") throw new Error("invalid gate checkpoint");
+  validId(checkpoint.taskId, "checkpoint task ID");
+  validateSnapshot(snapshot, checkpoint.taskId);
+  const { task, nextAction } = snapshot;
+  if (task.evidence.length < checkpoint.evidenceCount || hash(task.evidence.slice(0, checkpoint.evidenceCount)) !== checkpoint.evidenceHash) return { status: "blocked", reason: "gate evidence changed since checkpoint" };
+  if (task.status === "paused" || task.handoff || ["blocked", "terminal", "complete"].includes(nextAction.classification)) return { status: "blocked", reason: "task is paused, blocked, or terminal" };
+  if (task.phase === checkpoint.phase && task.gate === checkpoint.gate && task.status === "blocked_on_user" && nextAction.classification === "await_user") {
+    if (checkpoint.authority === "fleet" && hash(task) !== checkpoint.taskHash) return { status: "blocked", reason: "fleet review snapshot is stale" };
+    return { status: "wait" };
+  }
+  const appended = task.evidence.slice(checkpoint.evidenceCount);
+  const approvals = appended.filter((entry) => entry.kind === "approval" && entry.gate === checkpoint.gate && entry.result === "pass" && typeof entry.source === "string" && entry.source.trim());
+  if (task.phase !== TARGET[checkpoint.gate] || task.status !== "active" || nextAction.classification !== "run_phase" || approvals.length !== 1) return { status: "blocked", reason: "gate changed without its matching approval" };
+  if (checkpoint.authority === "local" && verifyLocalApproval && !await verifyLocalApproval({ checkpoint, snapshot })) return { status: "blocked", reason: "local approval lacks the matching host receipt" };
+  if (checkpoint.authority === "fleet") {
+    if (!checkpoint.snapshotId || !Number.isSafeInteger(checkpoint.revision) || !Number.isSafeInteger(snapshot.revision) || snapshot.revision <= checkpoint.revision) return { status: "blocked", reason: "fleet gate revision is stale" };
+    if (!await required(verifyFleetApproval, "verifyFleetApproval")({ checkpoint, snapshot })) return { status: "blocked", reason: "fleet approval does not match review snapshot" };
+  }
+  return { status: "resume", precondition: { taskId: checkpoint.taskId, gate: checkpoint.gate, phase: task.phase, taskHash: hash(task), evidenceCount: task.evidence.length, evidenceHash: hash(task.evidence), ...(checkpoint.authority === "fleet" ? { revision: snapshot.revision, snapshotId: checkpoint.snapshotId } : {}) } };
+}
+
+/**
+ * Supervises short runner invocations. runTurn MUST acquire its existing exclusive
+ * loop lease/lead epoch, reread canonical state, and enforce the supplied precondition
+ * before doing any work; if no precondition is supplied it MUST still verify
+ * run_phase under the lease. It MUST release the lease before returning a gate. Fleet
+ * runTurn additionally reconciles uncertain jobs and Git before dispatch. The
+ * checkpoint adapter MUST persist atomically, be scoped to task+authority, and be
+ * concurrency safe. acquireSupervisor MUST provide an independently fenced,
+ * renewable exclusive supervisor lease that does not block human gate approval.
+ * No callback is allowed to approve a human gate.
+ */
+export async function runSupervisor({ taskId, authority, acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, verifyFleetApproval, verifyLocalApproval, pollMs = 5000, signal, onEvent = () => {} }) {
+  validId(taskId, "task ID");
+  if (!["local", "fleet"].includes(authority)) throw new Error("invalid authority");
+  for (const [name, value] of Object.entries({ acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, onEvent })) required(value, name);
+  if (!Number.isSafeInteger(pollMs) || pollMs < 1 || pollMs > 300000) throw new Error("invalid poll interval");
+  const ownership = await acquireSupervisor({ taskId, authority, signal });
+  if (!ownership || typeof ownership.assertOwned !== "function" || typeof ownership.release !== "function") throw new Error("supervisor ownership must provide assertOwned and release");
+  try {
+  let checkpoint = await loadCheckpoint({ taskId, authority });
+  if (checkpoint && (checkpoint.taskId !== taskId || checkpoint.authority !== authority)) throw new Error("checkpoint authority or task mismatch");
+  while (!signal?.aborted) {
+    const snapshot = validateSnapshot(await readTask({ taskId }), taskId);
+    let precondition;
+    if (checkpoint) {
+      const verdict = await checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApproval, verifyLocalApproval });
+      if (verdict.status === "blocked") return { status: "blocked", taskId, reason: verdict.reason };
+      if (verdict.status === "wait") {
+        try { await sleep(pollMs, undefined, { signal }); } catch (error) { if (error?.name !== "AbortError") throw error; }
+        continue;
+      }
+      precondition = verdict.precondition;
+    } else if (snapshot.nextAction.classification !== "run_phase") {
+      return { status: snapshot.nextAction.classification === "await_user" ? "blocked" : snapshot.nextAction.classification, taskId, reason: snapshot.nextAction.classification === "await_user" ? "gate checkpoint missing; inspect the gate before resuming" : snapshot.nextAction.reason };
+    }
+    // Leave the durable gate checkpoint intact until the next stop is saved. A
+    // crash during a turn then cannot cause an unverified automatic restart.
+    await ownership.assertOwned();
+    const result = await runTurn({ taskId, authority, precondition, signal });
+    if (result?.status !== "gate") {
+      if (checkpoint && ["complete", "terminal"].includes(result?.status)) await clearCheckpoint({ taskId, authority, checkpoint });
+      return result;
+    }
+    const fresh = validateSnapshot(await readTask({ taskId }), taskId);
+    const next = makeGateCheckpoint({ taskId, authority, snapshot: fresh, result });
+    await ownership.assertOwned();
+    await saveCheckpoint({ taskId, authority, checkpoint: next, previous: checkpoint });
+    checkpoint = next;
+    await onEvent({ type: "gate", taskId, gate: next.gate, ...(next.snapshotId ? { snapshotId: next.snapshotId } : {}), gateView: result.gateView });
+  }
+  return { status: "stopped", taskId };
+  } finally { await ownership.release(); }
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-worker-docker.mjs

@@ -0,0 +1,32 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+import { isLoopProvider } from './loop-drivers.mjs';
+
+/** Container workers receive credentials as environment keys only. OpenCode
+ * authenticates from a file-based data store, so it fails closed here. */
+export const OPENCODE_CONTAINER_ERROR = 'OpenCode workers require file-based credentials and are not available in isolated containers yet';
+
+/** Build a Docker invocation. This function never accepts a shell command or credentials in arguments. */
+export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome }) {
+  const root = realpathSync(workspace);
+  if (/[\x00-\x1f,]/.test(root)) throw new Error('Invalid Docker workspace path');
+  if (typeof image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(image)) throw new Error('Explicit Docker image is required');
+  if (command === 'opencode') throw new Error(OPENCODE_CONTAINER_ERROR);
+  if (!isLoopProvider(command) || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) throw new Error('Invalid worker provider command');
+  if (!Number.isSafeInteger(uid) || uid < 1 || !Number.isSafeInteger(gid) || gid < 1) throw new Error('Non-root worker uid and gid are required');
+  if (!hostEnv || typeof hostEnv !== 'object' || !Array.isArray(credentialEnv) || !credentialEnv.length || credentialEnv.some((key) => !/^[A-Z][A-Z0-9_]*$/.test(key) || typeof hostEnv[key] !== 'string' || !hostEnv[key])) throw new Error('Explicit worker provider credentials are required');
+  const allowed = command === 'codex' ? ['OPENAI_API_KEY'] : ['ANTHROPIC_API_KEY'];
+  if (credentialEnv.some((key) => !allowed.includes(key)) || new Set(credentialEnv).size !== credentialEnv.length) throw new Error('Unsupported worker credential environment');
+  if (containerName !== undefined && (typeof containerName !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(containerName))) throw new Error('Invalid container name');
+  let homeMount;
+  if (sessionHome !== undefined) {
+    const info = lstatSync(sessionHome);
+    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid || (info.mode & 0o077)) throw new Error('Private worker session HOME is required');
+    const home = realpathSync(sessionHome);
+    if (/[\x00-\x1f,]/.test(home) || home === root || home.startsWith(`${root}${sep}`) || root.startsWith(`${home}${sep}`)) throw new Error('Worker session HOME must be separate from workspace');
+    homeMount = `type=bind,src=${home},dst=/home/worker`;
+  }
+  const env = { PATH: hostEnv.PATH ?? '/usr/bin:/bin' };
+  for (const key of credentialEnv) env[key] = hostEnv[key];
+  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), '--entrypoint', command, image, ...args], env };
+}