@felixdotgo/aidlc-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+export function assertLoopPath(root, taskId, suffix = ".json") {
+  if (!idPattern.test(taskId)) throw new Error(`Invalid task id: ${taskId}`);
+  const base = resolve(root);
+  let cursor = base;
+  for (const part of [".agents", "data", "loop", `${taskId}${suffix}`]) {
+    cursor = join(cursor, part);
+    try { if (lstatSync(cursor).isSymbolicLink()) throw new Error(`Loop path crosses a symlink: ${cursor}`); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+  return cursor;
+}
+
+export const loopLeasePath = (root, taskId) => assertLoopPath(root, taskId, ".lease");
+const guardPath = (root, taskId) => assertLoopPath(root, taskId, ".lease.guard");
+
+function parseLease(path) {
+  let value;
+  try { value = JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { throw new Error(`Corrupt loop lease: ${path}: ${error.message}`); }
+  if (!value || value.schemaVersion !== 1 || !idPattern.test(value.taskId) || typeof value.runId !== "string" || !value.runId || !Number.isInteger(value.pid) || value.pid < 1 || typeof value.token !== "string" || !value.token || typeof value.createdAt !== "string" || Number.isNaN(Date.parse(value.createdAt))) throw new Error(`Corrupt loop lease: ${path}`);
+  return value;
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { if (error?.code === "ESRCH") return false; return true; }
+}
+
+function withGuard(root, taskId, action) {
+  const path = guardPath(root, taskId);
+  mkdirSync(dirname(path), { recursive: true });
+  const guard = { schemaVersion: 1, taskId, runId: "guard", pid: process.pid, token: randomUUID(), createdAt: new Date().toISOString() };
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      try { writeFileSync(fd, `${JSON.stringify(guard)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const current = parseLease(path);
+      if (current.taskId !== taskId) throw new Error(`Conflicting loop lease guard: ${path}`);
+      if (!alive(current.pid)) { try { if (parseLease(path).token === current.token) unlinkSync(path); } catch (unlinkError) { if (unlinkError?.code !== "ENOENT") throw unlinkError; } continue; }
+      if (Date.now() >= deadline) throw new Error(`Timed out waiting for loop lease guard: ${taskId}`);
+      sleep(10);
+    }
+  }
+  try { return action(); }
+  finally { if (parseLease(path).token === guard.token) unlinkSync(path); }
+}
+
+export function readLiveLease(root, taskId) {
+  const path = loopLeasePath(root, taskId);
+  try { lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+  const lease = parseLease(path);
+  if (lease.taskId !== taskId) throw new Error(`Conflicting loop lease: ${path}`);
+  return alive(lease.pid) ? lease : null;
+}
+
+export function acquireLoopLease(root, taskId, runId) {
+  const path = loopLeasePath(root, taskId);
+  mkdirSync(dirname(path), { recursive: true });
+  const lease = { schemaVersion: 1, taskId, runId, pid: process.pid, token: randomUUID(), createdAt: new Date().toISOString() };
+  return withGuard(root, taskId, () => {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      try { writeFileSync(fd, `${JSON.stringify(lease)}\n`); fsyncSync(fd); }
+      finally { closeSync(fd); }
+      return () => withGuard(root, taskId, () => { try { if (parseLease(path).token === lease.token) unlinkSync(path); } catch (error) { if (error?.code !== "ENOENT") throw error; } });
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const existing = parseLease(path);
+      if (existing.taskId !== taskId) throw new Error(`Conflicting loop lease: ${path}`);
+      if (alive(existing.pid)) throw new Error(`Task ${taskId} already has a live loop runner (pid ${existing.pid})`);
+      // A dead owner may be reclaimed. A competing reclaimer may win; retry with wx.
+      try { if (parseLease(path).token === existing.token) unlinkSync(path); }
+      catch (unlinkError) { if (unlinkError?.code !== "ENOENT") throw unlinkError; }
+    }
+  }
+  throw new Error(`Could not acquire loop lease for ${taskId}`);
+  });
+}

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

@@ -0,0 +1,32 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { assertLoopPath } from "./loop-lease.mjs";
+const digest = (x) => createHash("sha256").update(JSON.stringify(x)).digest("hex");
+const read = (path) => {
+  const st = lstatSync(path);
+  if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || st.size > 16384) throw new Error("Unsafe local gate receipt or checkpoint");
+  return JSON.parse(readFileSync(path, "utf8"));
+};
+export function readLocalGateCheckpoint(root, task) {
+  const checkpoint = read(assertLoopPath(root, task.id, ".supervisor.json"));
+  if (checkpoint?.version !== 1 || checkpoint.taskId !== task.id || checkpoint.authority !== "local" || checkpoint.gate !== task.gate || checkpoint.phase !== task.phase || checkpoint.taskHash !== digest(task)) throw new Error("Supervisor gate checkpoint does not match current review");
+  return checkpoint;
+}
+/** Host gate process writes only after canonical approval is persisted. A crash
+ * in between is intentionally fail-closed and requires manual reconciliation. */
+export function writeLocalGateReceipt(root, checkpoint, task, reviewHash) {
+  const path = assertLoopPath(root, task.id, ".gate-receipt.json"), temp = `${path}.${randomUUID()}.tmp`;
+  if (existsSync(path)) read(path);
+  const receipt = { version: 1, taskId: task.id, gate: checkpoint.gate, checkpointHash: digest(checkpoint), taskHash: digest(task), reviewHash };
+  let fd;
+  try { fd = openSync(temp, "wx", 0o600); writeFileSync(fd, JSON.stringify(receipt)); fsyncSync(fd); closeSync(fd); fd = undefined; renameSync(temp, path); const dir = openSync(dirname(path), "r"); try { fsyncSync(dir); } finally { closeSync(dir); } }
+  finally { if (fd !== undefined) closeSync(fd); if (existsSync(temp)) unlinkSync(temp); }
+}
+export async function verifyLocalGateReceipt({ root, checkpoint, snapshot }) {
+  let receipt;
+  try { receipt = read(assertLoopPath(root, checkpoint.taskId, ".gate-receipt.json")); } catch { return false; }
+  const approved = snapshot?.task;
+  const evidence = approved?.evidence?.slice(checkpoint.evidenceCount) ?? [];
+  return receipt?.version === 1 && receipt.taskId === checkpoint.taskId && receipt.gate === checkpoint.gate && receipt.checkpointHash === digest(checkpoint) && receipt.taskHash === digest(approved) && typeof receipt.reviewHash === "string" && /^[a-f0-9]{64}$/.test(receipt.reviewHash) && evidence.some((item) => item.kind === "approval" && item.gate === checkpoint.gate && item.result === "pass" && item.source === `Trusted host terminal: approve (${receipt.reviewHash})`);
+}

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

@@ -0,0 +1,162 @@
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
+import { OPENCODE_CONTAINER_ERROR, workerDockerInvocation } from "./loop-worker-docker.mjs";
+import { isLoopProvider, runAgentTurn } from "./loop-drivers.mjs";
+import { claimLocalAssignment, heartbeatLocalAssignment, reportLocalAssignment, releaseLocalAssignment } from "./assignment-store.mjs";
+
+const git = (root, ...args) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000 });
+const lines = (value) => value.split("\0").filter(Boolean);
+const identifier = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
+const safePath = (path) => typeof path === "string" && path.length > 0 && !isAbsolute(path) && !path.includes("\\") && !path.split("/").some((part) => !part || part === "." || part === ".." || part === ".git" || part === ".agents") && !/[\x00-\x1f]/.test(path);
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+const scoped = (paths, scopes) => paths.every((path) => safePath(path) && scopes.some((scope) => path === scope || path.startsWith(`${scope}/`)));
+const statusPaths = (root) => {
+  // --no-renames yields one entry per path, including both sides of a rename.
+  return lines(git(root, "status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all")).map((row) => row.slice(3));
+};
+const commitPaths = (root, base, head) => lines(git(root, "diff", "--name-only", "-z", "--no-renames", base, head, "--"));
+// Workflow state and assignment records are lead-owned and never in worker
+// scopes. Their ordinary updates must not block integrating code-only commits.
+const clean = (root) => { if (statusPaths(root).some((path) => !path.startsWith(".agents/data/"))) throw new Error("Local integration worktree must be clean outside workflow data"); };
+
+/**
+ * Execute a batch of independent local jobs in isolated worktrees, then integrate
+ * verified scoped commits sequentially. Assignment metadata is not lifecycle
+ * state: the caller alone marks canonical items done after inspecting results.
+ * A failed batch is deliberately left for reconciliation, not auto-retried.
+ */
+export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, worktreesRoot: inputWorktreesRoot, docker, timeoutMs = 600000, leaseMs = 300000, maxTurns = 12, maxStallTurns = 2, claim = claimLocalAssignment, heartbeat = heartbeatLocalAssignment, report = reportLocalAssignment, release = releaseLocalAssignment, onEvent = () => {} }) {
+  const root = resolve(inputRoot), worktreesRoot = resolve(inputWorktreesRoot);
+  if (!identifier(taskId) || !Array.isArray(jobs) || !jobs.length) throw new Error("Valid task and non-empty jobs are required");
+  if (root === worktreesRoot || worktreesRoot.startsWith(`${root}${sep}`)) throw new Error("Worker worktree root must be outside the integration checkout");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(leaseMs) || leaseMs < 1000 || leaseMs > 3600000) throw new Error("Invalid timeout or lease");
+  if (!Number.isSafeInteger(maxTurns) || maxTurns < 1 || maxTurns > 1000 || !Number.isSafeInteger(maxStallTurns) || maxStallTurns < 1 || maxStallTurns > 20) throw new Error("Invalid worker turn or stall limit");
+  const ids = new Set(), workers = new Set(), scopes = [];
+  for (const job of jobs) {
+    if (Array.isArray(job.ownedPaths)) job.ownedPaths = [...new Set(job.ownedPaths.map((path) => (typeof path === "string" ? path.replace(/\/+$/, "") : path)).filter((path) => path))];
+    if (!identifier(job.itemId) || !identifier(job.workerId) || !isLoopProvider(job.agent) || typeof job.prompt !== "string" || !job.prompt.trim() || !Array.isArray(job.ownedPaths) || !job.ownedPaths.length || job.ownedPaths.length > 64 || !job.ownedPaths.every(safePath)) throw new Error("Invalid local job");
+    if (ids.has(job.itemId) || workers.has(job.workerId)) throw new Error("Items and workers must be distinct within a batch");
+    ids.add(job.itemId); workers.add(job.workerId);
+    for (const path of job.ownedPaths) { if (scopes.some((prior) => overlaps(path, prior))) throw new Error(`Overlapping assignment scope: ${path}`); scopes.push(path); }
+  }
+  if (jobs.some((job) => job.agent === "opencode")) throw new Error(OPENCODE_CONTAINER_ERROR);
+  if (process.platform !== "linux" || !docker || typeof docker.image !== "string" || !docker.credentials || typeof docker.credentials !== "object") throw new Error("Linux Docker worker isolation and explicit image and provider credentials are required");
+  const uid = process.getuid?.(), gid = process.getgid?.();
+  if (!uid || !gid) throw new Error("Docker workers require a non-root host user");
+  for (const job of jobs) {
+    const keys = docker.credentials[job.agent];
+    workerDockerInvocation({ workspace: root, image: docker.image, command: job.agent, args: [], credentialEnv: keys, hostEnv: process.env, uid, gid });
+  }
+  const dockerEnv = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
+  const dockerCheck = (...args) => execFileSync("docker", args, { env: dockerEnv, stdio: "ignore", timeout: 30000 });
+  let image;
+  try {
+    dockerCheck("info");
+    image=execFileSync("docker",["image","inspect","--format","{{.Id}}",docker.image],{env:dockerEnv,encoding:"utf8",stdio:["ignore","pipe","ignore"],timeout:30000}).trim();
+    if (!/^sha256:[a-f0-9]{64}$/.test(image)) throw new Error("Docker worker image lacks immutable image ID");
+    for (const agent of new Set(jobs.map((job) => job.agent))) dockerCheck("run", "--rm", "--network", "none", "--read-only", "--user", `${uid}:${gid}`, "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--entrypoint", agent, image, "--version");
+  } catch { throw new Error("Docker engine, image, or provider CLI preflight failed"); }
+  clean(root);
+  const base = git(root, "rev-parse", "HEAD").trim();
+  const initialBranch = git(root, "symbolic-ref", "--short", "HEAD").trim();
+  mkdirSync(worktreesRoot, { recursive: true });
+  const realRoot = realpathSync(root), realWorktreesRoot = realpathSync(worktreesRoot);
+  if (realRoot === realWorktreesRoot || realWorktreesRoot.startsWith(`${realRoot}${sep}`)) throw new Error("Worker worktree root must be outside the integration checkout");
+  const prepared = [];
+  try {
+    for (const job of jobs) {
+      const token = randomUUID(), branch = `aidlc/local/${token}`, workspace = resolve(worktreesRoot, token), snapshot = resolve(worktreesRoot, `${token}-snapshot`);
+      const assignment = await claim(root, { taskId, itemId: job.itemId, workerId: job.workerId, ownedPaths: job.ownedPaths, baseCommit: base, branch, leaseMs });
+      prepared.push({ job, assignment, workspace, snapshot, branch, created: false });
+      git(root, "worktree", "add", "-b", branch, workspace, base);
+      prepared.at(-1).created = true;
+      mkdirSync(snapshot);
+      const tracked = lines(git(workspace, "ls-files", "-z")).filter((path) => path !== ".agents/data" && !path.startsWith(".agents/data/"));
+      prepared.at(-1).baseline = createWorkerSnapshot(workspace, snapshot, tracked);
+    }
+  } catch (error) {
+    // No worker was started; release only claims whose worktree was never run.
+    for (const entry of prepared) { if (entry.created) git(root, "worktree", "remove", entry.workspace); rmSync(entry.snapshot, { recursive: true, force: true }); await release(root, taskId, entry.assignment.id); }
+    throw error;
+  }
+  const execute = async ({ job, assignment, workspace, snapshot, baseline, branch }) => {
+    let renewalError;
+    const controller = new AbortController();
+    const timer = setInterval(() => { Promise.resolve().then(() => heartbeat(root, taskId, assignment.id, leaseMs)).catch((error) => { renewalError = error; controller.abort(); }); }, Math.max(500, Math.floor(leaseMs / 3)));
+    try {
+      const home=mkdtempSync(join(tmpdir(), "aidlc-local-home-")); chmodSync(home,0o700);
+      let sessionId, previousFingerprint, stalls=0, result;
+      try {
+        for (let turn=0; turn<maxTurns; turn++) {
+          if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+          const containerName = `aidlc-worker-${randomUUID()}`;
+          const spawnProcess = (command, args, options) => {
+            const invocation = workerDockerInvocation({ workspace: snapshot, image, command, args, credentialEnv: docker.credentials[job.agent], hostEnv: process.env, uid, gid, containerName, sessionHome:home });
+            return spawn(invocation.command, invocation.args, { ...options, cwd: snapshot, env: invocation.env, shell: false });
+          };
+          try { result = await runAgentTurn({ agent: job.agent, root: "/workspace", sessionId, spawnProcess, prompt: `${job.prompt}\n\nOnly modify assigned paths: ${job.ownedPaths.join(", ")}. Do not modify AI-DLC lifecycle state or approve gates. End with AI-DLC-ITEM-COMPLETE on its own line.`, timeoutMs, signal: controller.signal, onSessionId: async (id) => { await heartbeat(root, taskId, assignment.id, leaseMs, id); } }); }
+          finally {
+            try { dockerCheck("rm", "-f", containerName); }
+            catch {
+              try { dockerCheck("info"); } catch { throw new Error("Docker cleanup uncertain: engine unavailable"); }
+              try { dockerCheck("inspect", containerName); throw new Error("Docker cleanup uncertain: container remains"); }
+              catch (error) { if (error.message === "Docker cleanup uncertain: container remains") throw error; }
+            }
+          }
+          if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+          sessionId=result.sessionId;
+          const changed=inspectWorkerSnapshot(snapshot,baseline,job.ownedPaths);
+          if (result.resultText?.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE")) break;
+          const fingerprint=createHash("sha256").update(JSON.stringify(changed.map((path) => { try { const full=join(snapshot,path), info=lstatSync(full); return [path,info.mode,createHash("sha256").update(readFileSync(full)).digest("hex")]; } catch (error) { if(error.code === "ENOENT") return [path,null]; throw error; } }))).digest("hex");
+          stalls=fingerprint===previousFingerprint ? stalls+1 : 0; previousFingerprint=fingerprint;
+          if (stalls >= maxStallTurns) throw new Error(`Worker ${job.workerId} stalled`);
+          if (turn===maxTurns-1) throw new Error(`Worker ${job.workerId} exceeded turn limit`);
+        }
+      } finally { rmSync(home,{recursive:true,force:true}); }
+      if (git(workspace, "rev-parse", "HEAD").trim() !== base || statusPaths(workspace).length) throw new Error("Host worker worktree changed during isolated execution");
+      const snapshotChanges = inspectWorkerSnapshot(snapshot, baseline, job.ownedPaths);
+      if (!snapshotChanges.length) throw new Error(`Worker ${job.workerId} changed no files`);
+      await heartbeat(root, taskId, assignment.id, leaseMs);
+      if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+      for (const path of snapshotChanges) {
+        const destination = join(workspace, path), from = join(snapshot, path);
+        let parent = workspace;
+        for (const segment of path.split("/").slice(0, -1)) { parent = join(parent, segment); try { const info = lstatSync(parent); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe integration directory"); } catch (error) { if (error.code !== "ENOENT") throw error; mkdirSync(parent); } }
+        try { const info = lstatSync(destination); if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error("Unsafe integration target"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+        try { const info = lstatSync(from); copyFileSync(from, destination); chmodSync(destination, info.mode & 0o777); } catch (error) { if (error.code !== "ENOENT") throw error; rmSync(destination, { force: true }); }
+      }
+      if (git(workspace, "symbolic-ref", "--short", "HEAD").trim() !== branch) throw new Error("Worker changed its assigned branch");
+      git(workspace, "merge-base", "--is-ancestor", base, "HEAD");
+      const changed = [...new Set([...statusPaths(workspace), ...commitPaths(workspace, base, "HEAD")])];
+      if (!changed.length || !scoped(changed, job.ownedPaths)) throw new Error(`Worker ${job.workerId} changed no files or files outside its scope`);
+      // Fold any commits made by the agent into one scoped assignment commit.
+      git(workspace, "reset", "--soft", base);
+      git(workspace, "add", "-A", "--", ...changed);
+      if (git(workspace, "diff", "--cached", "--name-only").trim()) git(workspace, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", `AI-DLC ${taskId}/${job.itemId}`);
+      const commit = git(workspace, "rev-parse", "HEAD").trim(), committed = commitPaths(workspace, base, commit);
+      if (commit === base || !committed.length || !scoped(committed, job.ownedPaths)) throw new Error("Worker commit is outside assignment scope");
+      await report(root, taskId, assignment.id, { commit, changedPaths: committed, checkpoint: `provider=${job.agent}` });
+      return { assignmentId: assignment.id, itemId: job.itemId, workerId: job.workerId, agent: job.agent, baseCommit: base, branch, commit, changedPaths: committed, workspace };
+    } finally { clearInterval(timer); }
+  };
+  const results = await Promise.allSettled(prepared.map(execute));
+  const failure = results.find((result) => result.status === "rejected");
+  if (failure) throw new Error(`Local worker batch requires reconciliation: ${failure.reason instanceof Error ? failure.reason.message : String(failure.reason)}`);
+  const completed = results.map((result) => result.value);
+  let expectedHead = base;
+  for (const result of completed) {
+    clean(root);
+    if (git(root, "symbolic-ref", "--short", "HEAD").trim() !== initialBranch) throw new Error("Integration branch changed during worker run");
+    if (git(root, "rev-parse", "HEAD").trim() !== expectedHead) throw new Error("Integration HEAD changed during worker run");
+    if (!scoped(commitPaths(root, base, result.commit), jobs.find((job) => job.itemId === result.itemId).ownedPaths)) throw new Error("Worker scope changed before integration");
+    git(root, "-c", "user.name=AI-DLC integrator", "-c", "user.email=aidlc-integrator@localhost", "cherry-pick", result.commit);
+    result.integrationCommit = git(root, "rev-parse", "HEAD").trim();
+    expectedHead = result.integrationCommit;
+    await onEvent({ type: "job_integrated", taskId, itemId: result.itemId, assignmentId: result.assignmentId, commit: result.integrationCommit });
+  }
+  return completed;
+}

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

@@ -0,0 +1,13 @@
+import { nextAction, readyTaskItems } from "./store.mjs";
+
+// Scheduling is derived from canonical lifecycle state. Assignments are operational hints only.
+export const planLoop = ({ task, assignments = [], root }) => {
+  const action = nextAction(task, root);
+  const itemGraph = readyTaskItems(task);
+  if (action.classification !== "run_phase" || task.phase !== "build") return { ...action, readyItems: [], blockedItems: itemGraph.blocked };
+  const busy = new Set(assignments.filter((entry) => ["leased", "reported", "uncertain"].includes(entry.state) && entry.taskId === task.id).map((entry) => entry.itemId));
+  const readyItems = itemGraph.ready.filter((id) => !busy.has(id));
+  if (readyItems.length) return { classification: "dispatch", phase: task.phase, gate: task.gate, readyItems, blockedItems: itemGraph.blocked, nextAction: action };
+  if (busy.size) return { classification: "reconcile", phase: task.phase, gate: task.gate, readyItems: [], blockedItems: itemGraph.blocked, nextAction: action, reason: "Recover or integrate outstanding assignments" };
+  return { ...action, readyItems: [], blockedItems: itemGraph.blocked };
+};

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

@@ -0,0 +1,260 @@
+/**
+ * Local loop runtime: record management, checkpointing, turn orchestration,
+ * and pause/resume handling for a single lead.
+ */
+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);
+  // --- Validate mode and load/create the loop record -------------------------
+  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);
+    // --- Main turn loop --------------------------------------------------------
+  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 };
+}