@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+
+/** Prepare a durable, idempotent intake without treating it as lifecycle state. */
+export async function prepareLoopIntake({ root, taskId, requirement, authority, createTask, readTask }) {
+  if (!ID.test(taskId ?? "")) throw new Error("Invalid task ID");
+  if (!["local", "fleet"].includes(authority)) throw new Error("Invalid loop authority");
+  if (typeof requirement !== "string" || !requirement.trim() || Buffer.byteLength(requirement) > 8192) throw new Error("Requirement must contain 1–8192 bytes");
+  if (typeof createTask !== "function" || typeof readTask !== "function") throw new Error("Intake requires lifecycle callbacks");
+  const project = resolve(root), base = join(project, ".agents", "data", "tasks");
+  for (const path of [join(project, ".agents"), join(project, ".agents", "data"), base]) {
+    if (!existsSync(path)) mkdirSync(path);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Unsafe intake directory");
+  }
+  const directory = join(base, taskId);
+  if (!existsSync(directory)) mkdirSync(directory, { mode: 0o700 });
+  const stat = lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Unsafe task directory");
+  const recordPath = join(directory, "loop-intake.json");
+  const record = { schemaVersion: 1, taskId, authority, requirementHash: digest(requirement) };
+  if (!existsSync(recordPath) && await readTask(taskId)) throw new Error("Existing task has no matching loop intake record");
+  try { writeFileSync(recordPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const currentStat = lstatSync(recordPath);
+    if (!currentStat.isFile() || currentStat.isSymbolicLink()) throw new Error("Unsafe intake record");
+    let current; try { current = JSON.parse(readFileSync(recordPath, "utf8")); } catch { throw new Error("Invalid intake record"); }
+    if (JSON.stringify(current) !== JSON.stringify(record)) throw new Error("Existing intake has different authority or requirement");
+  }
+  const requirementPath = join(directory, "requirement.md");
+  try { writeFileSync(requirementPath, requirement, { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const existing = lstatSync(requirementPath);
+    if (!existing.isFile() || existing.isSymbolicLink() || digest(readFileSync(requirementPath, "utf8")) !== record.requirementHash) throw new Error("Existing requirement does not match intake");
+  }
+  const title = `Loop task ${taskId}`;
+  let task = await readTask(taskId);
+  if (!task) {
+    try { await createTask({ taskId, title }); }
+    catch (error) { task = await readTask(taskId); if (!task || task.title !== title) throw error; }
+    task ??= await readTask(taskId);
+  }
+  if (!task || task.id !== taskId || task.title !== title) throw new Error("Existing task conflicts with intake");
+  return { taskId, authority, requirementPath };
+}

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

@@ -0,0 +1,63 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const hash = (data) => createHash("sha256").update(data).digest("hex");
+const digest = (path) => {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("Unsafe lead artifact file");
+  return hash(readFileSync(path));
+};
+const syncDir = (dir) => { const fd = openSync(dir, "r"); try { fsyncSync(fd); } finally { closeSync(fd); } };
+const hexOrNull = (x) => x === null || (typeof x === "string" && /^[a-f0-9]{64}$/.test(x));
+const safeFile = (path) => { const stat = lstatSync(path); if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("Unsafe lead artifact journal"); };
+function directory(root, id) {
+  let cursor = root;
+  for (const part of [".agents", "data", "tasks", id]) { cursor = join(cursor, part); const stat = lstatSync(cursor); if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Unsafe lead artifact directory"); }
+  return cursor;
+}
+/** Read the expected digest for a phase packet while holding the same lock. */
+export function leadArtifactDigest({ root, taskId, task, name }) {
+  if (!["intent", "design", "workplan"].includes(name) || task.artifacts?.[name] !== `.agents/data/tasks/${taskId}/${name}.md`) throw new Error("Invalid canonical artifact path");
+  return digest(join(directory(root, taskId), `${name}.md`));
+}
+/** Must be called while holding the canonical state lock and supervisor fence. */
+export async function recoverLeadArtifact({ root, taskId, task, assertOwned }) {
+  let dir;
+  try { dir = directory(root, taskId); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  const journal = join(dir, ".lead-artifact-journal.json");
+  try { safeFile(journal); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  let entry; try { entry = JSON.parse(readFileSync(journal, "utf8")); } catch { throw new Error("Invalid lead artifact journal"); }
+  if (!entry || entry.version !== 1 || !["intent", "design", "workplan"].includes(entry.name) || !hexOrNull(entry.before) || typeof entry.after !== "string" || !/^[a-f0-9]{64}$/.test(entry.after) || typeof entry.temp !== "string" || !/^\.lead-artifact-[0-9a-f-]{36}\.tmp$/.test(entry.temp) || task.artifacts?.[entry.name] !== `.agents/data/tasks/${taskId}/${entry.name}.md`) throw new Error("Invalid lead artifact journal");
+  const target = join(dir, `${entry.name}.md`), temp = join(dir, entry.temp), current = digest(target);
+  if (current !== entry.before && current !== entry.after) throw new Error("Lead artifact journal conflicts with current file; reconcile manually");
+  await assertOwned();
+  // Once the target contains the after digest the write committed. Otherwise the
+  // intent was not committed; discard the temp so the original can be retried.
+  try { safeFile(temp); unlinkSync(temp); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  unlinkSync(journal); syncDir(dir);
+}
+/** Compare the reviewed artifact digest, stage a durable intent, then rename.
+ * Recovery never guesses when the target was changed by another writer. */
+export async function writeLeadArtifact({ root, taskId, task, operation: op, assertOwned }) {
+  const dir = directory(root, taskId);
+  if (task.artifacts?.[op.name] !== `.agents/data/tasks/${taskId}/${op.name}.md`) throw new Error("Canonical artifact path is not the expected task path");
+  await recoverLeadArtifact({ root, taskId, task, assertOwned });
+  const target = join(dir, `${op.name}.md`), before = digest(target);
+  if (before !== op.expectedDigest) throw new Error("Stale lead artifact digest");
+  const after = hash(Buffer.from(op.content)), name = `.lead-artifact-${randomUUID()}.tmp`, temp = join(dir, name), journal = join(dir, ".lead-artifact-journal.json");
+  let fd, journaled = false;
+  try {
+    fd = openSync(temp, "wx", 0o600); writeFileSync(fd, op.content, "utf8"); fsyncSync(fd); closeSync(fd); fd = undefined;
+    await assertOwned();
+    fd = openSync(journal, "wx", 0o600); writeFileSync(fd, JSON.stringify({ version: 1, name: op.name, before, after, temp: name }), "utf8"); fsyncSync(fd); closeSync(fd); fd = undefined; journaled = true; syncDir(dir);
+    await assertOwned();
+    if (digest(target) !== before) throw new Error("Lead artifact changed during commit");
+    renameSync(temp, target); syncDir(dir);
+    await assertOwned(); unlinkSync(journal); syncDir(dir);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (!journaled && existsSync(temp)) unlinkSync(temp);
+  }
+}

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

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+
+const LIMIT = 65536;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const validId = (x) => typeof x === "string" && ID.test(x);
+const record = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const exact = (x, keys) => record(x) && Object.keys(x).length === keys.length && keys.every((key) => Object.hasOwn(x, key));
+const text = (x, max) => typeof x === "string" && x.trim().length > 0 && Buffer.byteLength(x) <= max && !x.includes("\0");
+const scope = (x) => text(x, 512) && !isAbsolute(x) && !x.includes("\\") && !/[\x00-\x1f]/.test(x) && x.split("/").every((part) => part && part !== "." && part !== ".." && part !== ".git" && part !== ".agents");
+export const leadTaskDigest = (task) => createHash("sha256").update(JSON.stringify(task)).digest("hex");
+
+/** Parse an untrusted, bounded model proposal. This schema never admits approval,
+ * evidence, execution commands, phase transitions, or arbitrary artifact paths. */
+export function parseLeadProposal(raw) {
+  if (typeof raw !== "string" || Buffer.byteLength(raw) > LIMIT) throw new Error("Invalid or oversized lead proposal");
+  let p; try { p = JSON.parse(raw); } catch { throw new Error("Invalid lead proposal JSON"); }
+  if (!exact(p, ["version", "taskId", "phase", "taskDigest", "operation"]) || p.version !== 1 || !validId(p.taskId) || !["clarify", "plan"].includes(p.phase) || !/^[a-f0-9]{64}$/.test(p.taskDigest)) throw new Error("Invalid lead proposal envelope");
+  const op = p.operation;
+  if (op?.kind === "artifact") {
+    if (!exact(op, ["kind", "name", "content", "expectedDigest"]) || !({ clarify: ["intent"], plan: ["design", "workplan"] }[p.phase]).includes(op.name) || !text(op.content, 60000) || !(op.expectedDigest === null || (typeof op.expectedDigest === "string" && /^[a-f0-9]{64}$/.test(op.expectedDigest)))) throw new Error("Invalid artifact proposal");
+  } else if (op?.kind === "decision") {
+    if (p.phase !== "plan" || !exact(op, ["kind", "id", "label", "resolution"]) || !validId(op.id) || !text(op.label, 512) || !text(op.resolution, 4096)) throw new Error("Invalid decision proposal");
+  } else if (op?.kind === "item") {
+    if (p.phase !== "plan" || !exact(op, ["kind", "id", "label", "dependsOn", "ownedPaths"]) || !validId(op.id) || !text(op.label, 512) || !Array.isArray(op.dependsOn) || op.dependsOn.length > 64 || new Set(op.dependsOn).size !== op.dependsOn.length || !op.dependsOn.every((id) => validId(id) && id !== op.id) || !Array.isArray(op.ownedPaths) || !op.ownedPaths.length || op.ownedPaths.length > 64 || new Set(op.ownedPaths).size !== op.ownedPaths.length || !op.ownedPaths.every(scope)) throw new Error("Invalid item proposal");
+  } else throw new Error("Lead operation not allowed");
+  return p;
+}
+
+/** adapter.withTaskLock MUST hold the canonical lock and supervisor fence through
+ * read, validation, one apply, and reading nextAction. The adapter is trusted
+ * host code; this module does not expose it to the model or container. */
+export async function applyLeadProposal(raw, adapter) {
+  const proposal = parseLeadProposal(raw);
+  if (typeof adapter?.withTaskLock !== "function") throw new Error("Atomic fenced broker adapter required");
+  return adapter.withTaskLock(proposal.taskId, async (tx) => {
+    if (typeof tx?.assertOwned !== "function" || typeof tx?.readTask !== "function" || typeof tx?.nextAction !== "function" || typeof tx?.applyOne !== "function") throw new Error("Incomplete fenced broker transaction");
+    await tx.assertOwned();
+    const task = await tx.readTask();
+    if (!task || task.id !== proposal.taskId || task.status !== "active" || task.phase !== proposal.phase || leadTaskDigest(task) !== proposal.taskDigest) throw new Error("Stale lead proposal");
+    const action = await tx.nextAction(task);
+    if (action?.classification !== "run_phase" || action.phase !== proposal.phase) throw new Error("Task is not actionable in proposed phase");
+    if (proposal.operation.kind === "item") {
+      const known = new Set(task.tasks.map((item) => item.id));
+      if (proposal.operation.dependsOn.some((id) => !known.has(id))) throw new Error("Unknown item dependency");
+      if (known.has(proposal.operation.id)) throw new Error("Item already exists");
+    }
+    await tx.assertOwned();
+    await tx.applyOne(proposal.operation);
+    await tx.assertOwned();
+    return tx.nextAction(await tx.readTask());
+  });
+}

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

@@ -0,0 +1,44 @@
+import { resolve } from "node:path";
+import { acquireStateLock, loadState, nextAction, readyTaskItems, saveState } from "./store.mjs";
+import { requireLocalAuthority } from "./authority.mjs";
+import { recoverLeadArtifact, writeLeadArtifact } from "./loop-lead-artifacts.mjs";
+
+/** Create a trusted host-only adapter. assertOwned comes directly from the live
+ * supervisor lease and must remain valid throughout the transaction. */
+export function createLocalLeadBrokerAdapter({ root: inputRoot, taskId, assertOwned }) {
+  const root = resolve(inputRoot);
+  if (typeof assertOwned !== "function" || typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId)) throw new Error("Local broker requires a live supervisor fence and task ID");
+  return { async withTaskLock(id, run) {
+    requireLocalAuthority();
+    if (id !== taskId || typeof run !== "function") throw new Error("Broker task mismatch");
+    await assertOwned();
+    const release = acquireStateLock(root);
+    try {
+      await assertOwned();
+      const state = loadState(root), task = state.tasks[taskId];
+      if (!task) throw new Error("Unknown active broker task");
+      await recoverLeadArtifact({ root, taskId, task, assertOwned });
+      let applied = false;
+      return await run({
+        assertOwned,
+        readTask: async () => task,
+        nextAction: async (value) => nextAction(value, root),
+        applyOne: async (op) => {
+          if (applied) throw new Error("Broker permits only one mutation per transaction");
+          applied = true; await assertOwned();
+          if (op.kind === "artifact") {
+            await writeLeadArtifact({ root, taskId, task, operation: op, assertOwned });
+          } else if (op.kind === "decision") {
+            if (task.decisions.some((entry) => entry.id === op.id)) throw new Error("Decision already exists; broker cannot overwrite human decisions");
+            task.decisions.push({ id: op.id, label: op.label, status: "unresolved", resolution: op.resolution });
+            task.updatedAt = new Date().toISOString(); await assertOwned(); saveState(root, state);
+          } else if (op.kind === "item") {
+            if (task.tasks.some((entry) => entry.id === op.id)) throw new Error("Item already exists");
+            task.tasks.push({ id: op.id, label: op.label, status: "todo", dependsOn: op.dependsOn, ownedPaths: op.ownedPaths });
+            readyTaskItems(task); task.updatedAt = new Date().toISOString(); await assertOwned(); saveState(root, state);
+          } else throw new Error("Broker operation not allowed");
+        }
+      });
+    } finally { release(); }
+  } };
+}

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

@@ -0,0 +1,88 @@
+import { realpathSync, statSync } from "node:fs";
+import { isLoopProvider } from "./loop-drivers.mjs";
+import { OPENCODE_CONTAINER_ERROR, workerDockerInvocation } from "./loop-worker-docker.mjs";
+
+/** Invocation only: callers must supply a sanitized, host-owned source snapshot,
+ * never the checkout. No host output directory, state, or broker channel is mounted.
+ * The bounded provider response carries the proposal back to the trusted host. */
+export function leadDockerInvocation({ snapshot, image, agent, args, credentialEnv, hostEnv, uid, gid, containerName }) {
+  const source = realpathSync(snapshot);
+  if (!statSync(source).isDirectory()) throw new Error("Lead snapshot must be a directory");
+  const invocation = workerDockerInvocation({ workspace: source, image, command: agent, args, credentialEnv, hostEnv, uid, gid, containerName });
+  const mount = `type=bind,src=${source},dst=/workspace`;
+  const index = invocation.args.indexOf(mount);
+  if (index < 0) throw new Error("Missing lead snapshot mount");
+  invocation.args[index] = `${mount},readonly`;
+  return invocation;
+}
+
+/** Create and clean an isolated source-only snapshot for exactly one turn. */
+export async function withLeadSnapshot({ root: inputRoot, snapshotsRoot: inputSnapshotsRoot }, use) {
+  const { execFileSync } = await import("node:child_process");
+  const { mkdtempSync, mkdirSync, rmSync } = await import("node:fs");
+  const { resolve, sep, join } = await import("node:path");
+  const { createWorkerSnapshot } = await import("./loop-worker-snapshot.mjs");
+  if (typeof use !== "function" || typeof inputRoot !== "string" || typeof inputSnapshotsRoot !== "string") throw new Error("Lead snapshot requires paths and a callback");
+  const root = realpathSync(inputRoot);
+  const requested = resolve(inputSnapshotsRoot);
+  if (requested === root || requested.startsWith(`${root}${sep}`) || root.startsWith(`${requested}${sep}`)) throw new Error("Lead snapshots root must be outside the project");
+  mkdirSync(requested, { recursive: true, mode: 0o700 });
+  const parent = realpathSync(requested);
+  if (parent === root || parent.startsWith(`${root}${sep}`) || root.startsWith(`${parent}${sep}`)) throw new Error("Lead snapshots root resolves inside or above the project");
+  const snapshot = mkdtempSync(join(parent, "aidlc-lead-"));
+  try {
+    const output = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8", timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+    const paths = output.split("\0").filter((path) => path && path !== ".agents/data" && !path.startsWith(".agents/data/"));
+    createWorkerSnapshot(root, snapshot, paths);
+    return await use(snapshot);
+  } finally { rmSync(snapshot, { recursive: true, force: true }); }
+}
+
+/** Execute one lead proposal in a separate read-only container. No broker or
+ * lifecycle capability is passed to the container. Caller applies the returned
+ * proposal separately under its fence and canonical lock. */
+export async function runIsolatedLeadTurn({ root, snapshotsRoot, image, agent, prompt, assertOwned, timeoutMs = 600000, signal }) {
+  const { execFileSync, spawn } = await import("node:child_process");
+  const { randomUUID } = await import("node:crypto");
+  const { runAgentTurn } = await import("./loop-drivers.mjs");
+  const { parseLeadProposal } = await import("./loop-lead-broker.mjs");
+  if (agent === "opencode") throw new Error(OPENCODE_CONTAINER_ERROR);
+  if (process.platform !== "linux" || !isLoopProvider(agent) || typeof prompt !== "string" || !prompt || Buffer.byteLength(prompt) > 262144 || typeof assertOwned !== "function") throw new Error("Invalid isolated lead configuration");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error("Invalid isolated lead timeout or signal");
+  const uid = process.getuid?.(), gid = process.getgid?.();
+  if (!uid || !gid) throw new Error("Isolated lead requires a non-root Linux host user");
+  const credentialEnv = agent === "codex" ? ["OPENAI_API_KEY"] : ["ANTHROPIC_API_KEY"];
+  const env = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
+  const check = (...args) => execFileSync("docker", args, { env, stdio: "ignore", timeout: 30000 });
+  await assertOwned();
+  return withLeadSnapshot({ root, snapshotsRoot }, async (snapshot) => {
+    // Validation builds an invocation before any agent or task mutation starts.
+    leadDockerInvocation({ snapshot, image, agent, args: [], credentialEnv, hostEnv: process.env, uid, gid });
+    try { check("info"); check("image", "inspect", image); check("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, lead image, or provider CLI preflight failed"); }
+    const name = `aidlc-lead-${randomUUID()}`, controller = new AbortController();
+    let lost;
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) controller.abort();
+    const timer = setInterval(() => { Promise.resolve().then(assertOwned).catch((error) => { lost = error; controller.abort(); }); }, 1000);
+    try {
+      await assertOwned();
+      const result = await runAgentTurn({ agent, root: "/workspace", prompt, timeoutMs, signal: controller.signal, spawnProcess: (command, args, options) => {
+        const invocation = leadDockerInvocation({ snapshot, image, agent: command, args, credentialEnv, hostEnv: process.env, uid, gid, containerName: name });
+        return spawn(invocation.command, invocation.args, { ...options, cwd: snapshot, env: invocation.env, shell: false });
+      } });
+      if (lost || controller.signal.aborted) throw lost ?? new Error("Lead turn aborted");
+      await assertOwned();
+      return parseLeadProposal(result.resultText);
+    } finally {
+      clearInterval(timer); signal?.removeEventListener("abort", abort);
+      try { check("rm", "-f", name); }
+      catch {
+        try { check("info"); } catch { throw new Error("Lead container cleanup uncertain: Docker unavailable"); }
+        try { check("inspect", name); throw new Error("Lead container cleanup uncertain: container remains"); }
+        catch (error) { if (error.message === "Lead container cleanup uncertain: container remains") throw error; }
+      }
+    }
+  });
+}

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,161 @@
+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 (!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 };
+};